[07] Hermes Agent 技能进化系统拆解：Skill 的元数据结构、自注册加载与退化机制

---
name: axolotl
description: Axolotl: YAML LLM fine-tuning (LoRA, DPO, GRPO).
version: 1.0.0
category: mlops
metadata:
  hermes:
    tags: [fine-tuning, lora, dpo]
    related_skills: [unsloth, trl]
---
# Axolotl Fine-tuning Skill
使用 Axolotl 进行 LLM 微调的完整工作流。核心操作：
```bash
# 安装
pip install axolotl
# 训练
accelerate launch -m axolotl.cli.train config.yml

每个 Skill 对应 `~/.hermes/skills/<category>/<skill-name>/` 下的一个目录：

---
## 2. SKILL.md 元数据结构
SKILL.md 的头部 YAML frontmatter 定义了 Agent 和工具系统需要的全部结构化信息。`skills_tool.py` 中的 `_parse_frontmatter()` 负责解析它，但不重复实现——它委托给 `agent.skill_utils.parse_frontmatter()`：
```python
def _parse_frontmatter(content: str) -> Tuple[Dict[str, Any], str]:
    from agent.skill_utils import parse_frontmatter
    return parse_frontmatter(content)

def _get_required_environment_variables(frontmatter, legacy_env_vars=None):
    required_raw = frontmatter.get("required_environment_variables")
    # 支持三种输入格式：
    # 1. 字符串列表: ["OPENAI_API_KEY"]
    # 2. 带描述的 dict: {"name": "OPENAI_API_KEY", "prompt": "输入 key"}
    # 3. 旧版 prerequisites.env_vars
    for item in required_raw:
        if isinstance(item, str):
            _append_required({"name": item})
        if isinstance(item, dict):
            _append_required(item)
    # 旧版兼容
    if legacy_env_vars is None:
        legacy_env_vars, _ = _collect_prerequisite_values(frontmatter)

has_skills_tools = any(name in agent.valid_tool_names for name in ['skills_list', 'skill_view', 'skill_manage'])
if has_skills_tools:
    skills_prompt = _r.build_skills_system_prompt(
        available_tools=agent.valid_tool_names,
        available_toolsets=avail_toolsets,
        compact_categories=_compact_cats or None,
    )

tools/skill_name: 简短描述（10-30字）

# tools.registry 中的注册（在 skills_tool.py 的模块顶层）
registry.register(
    name="skills_list",
    toolset="skills",
    schema={
        "description": "按类别列出所有可用的技能，返回元数据",
        "parameters": {
            "type": "object",
            "properties": {
                "category": {"type": "string", "description": "按类别筛选（可选）"}
            }
        }
    },
    handler=skills_list,
    check_fn=check_skills_requirements,
)
registry.register(
    name="skill_view",
    toolset="skills",
    # ... 读取完整内容或引用文件
)
registry.register(
    name="skill_manage",
    toolset="skills",
    # ... 增删改
)

def check_skills_requirements() -> bool:
    """Skills are always available — the directory is created on first use if needed."""
    return True

def _load_skill_payload(skill_identifier, task_id=None):
    raw_identifier = (skill_identifier or "").strip()
    if not raw_identifier:
        return None
    try:
        from tools.skills_tool import SKILLS_DIR, skill_view
        # 支持绝对路径和相对路径
        identifier_path = Path(raw_identifier).expanduser()
        if identifier_path.is_absolute():
            # 安全检测：只允许在 SKILLS_DIR 和 external_skills_dirs 内的路径
            for root in trusted_roots:
                try:
                    normalized = str(identifier_path.relative_to(root))
                    break
                except ValueError:
                    continue
        else:
            normalized = raw_identifier.lstrip("/")
        loaded_skill = json.loads(
            skill_view(normalized, task_id=task_id, preprocess=False)
        )
    except Exception:
        return None

_INJECTION_PATTERNS: list = [
    "ignore previous instructions",
    "ignore all previous",
    "you are now",
    "disregard your",
    "forget your instructions",
    "new instructions:",
    "system prompt:",
    "<system>",
    "]]>",
]

_PLATFORM_MAP = {
    "macos": "darwin",
    "linux": "linux",
    "windows": "win32",
}
def skill_matches_platform(frontmatter) -> bool:
    from agent.skill_utils import skill_matches_platform as _impl
    return _impl(frontmatter)

def skill_matches_environment(frontmatter) -> bool:
    from agent.skill_utils import skill_matches_environment as _impl
    return _impl(frontmatter)

if _is_gateway_surface() and not env_var_enabled("HERMES_INTERACTIVE"):
    return {
        "missing_names": missing_names,
        "setup_skipped": False,
        "gateway_setup_hint": _gateway_setup_hint(),
    }

用户创建 SKILL.md
    ↓
文件写入 ~/.hermes/skills/<category>/<name>/
    ↓
Agent 启动 → System Prompt 构建
    ↓
prompt_builder 调用 build_skills_system_prompt()
    → 扫描 skills/ 目录
    → 读取每个 SKILL.md 的 frontmatter
    → 两层缓存（LRU + disk snapshot）
    → 生成 Skills Index（名称+描述列表）
    ↓
System Prompt 注入 → Agent 看到可用工具
    ↓
用户："/check-server"
    ↓
skill_commands._load_skill_payload("check-server")
    → skill_view() 读取 SKILL.md
    → 注入检测扫描
    → 平台/环境检查
    → 环境变量检查
    ↓
Agent 执行 Skill 中定义的工作流
    ↓
完成后 → Hindsight 自动 retain 总结
    → 如果够复杂，新建/更新 SKILL.md（技能进化）