从零构建 Agent Skill 系统：设计哲学与实战全解

摘要： 2026年，AI Agent 不再靠 prompt 死记硬背——Skills 框架正在成为 Agent 基础设施的标配。本文将深入剖析三大主流 Skills 框架的设计哲学，并带你从零构建一个可运行的 Agent Skill 系统，附完整代码。

---

一、为什么 Agent 需要 Skills？

2026 年 5 月的 GitHub Trending 上，前十名中有超过一半是 Agent 相关项目。Anthropic 推出了 anthropics/skills（140k⭐），Jesse Vincent 的 superpowers（205k⭐）成为跨平台标准，Nous Research 的 hermes-agent（166k⭐）甚至让 Agent 自己写 Skill。

这一切指向同一个趋势：Agent 从「靠 prompt 硬记」进化到「像插件一样加载能力」。

Skills 解决的核心问题

问题	没有 Skills	有 Skills
知识复用	每次对话重新教 Agent	Skill 文件持久化，一次编写到处运行
质量保证	Agent 凭记忆，质量不稳定	Skill 定义标准流程，Agent 严格遵循
上下文效率	Prompt 越写越长	按需加载，不浪费 token
协作共享	每个人的 Agent 要单独教	Skills 像 npm 包一样分发
自主进化	靠人工维护	Agent 可以自己创建和改进 Skills

agentskills.io 标准

2025 年底，Anthropic 联合社区推出了 agentskills.io 开放标准——一个极简的格式规范：

---
name: my-skill
description: Use when [触发条件]
---

# 指令内容

就这么简单。两个必填字段 + Markdown 正文。但这简单背后，各家框架演化出了完全不同的设计哲学。

---

二、三大框架设计哲学对比

2.1 Superpowers：方法论驱动的 Skill 编排

核心理念： Skills 不只是参考文档，而是一套强制执行的软件工程方法论。

Superpowers 核心工作流：

  需求分析 ──► 实现计划 ──► Git Worktree 隔离
      │                          │
      ▼                          ▼
  brainstorming            writing-plans
  (苏格拉底式追问)          (任务拆分到2-5分钟粒度)
                                  │
                          ┌───────┴───────┐
                          ▼               ▼
                   TDD 驱动开发      子Agent并发执行
                          │               │
                    test-driven-     subagent-driven-
                    development      development
                          │               │
                          └───────┬───────┘
                                  ▼
                           代码审查 + 分支合并
                           requesting-code-review
                           finishing-a-development-branch

设计特点：

• 上下文自动触发： Agent 在合适的阶段自动加载对应 Skill，用户无需手动指定
• TDD 铁律： “NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST”——违反即删除代码
• Skill 的 Skill： writing-skills 用 TDD 方法论来写 Skill——先让 Agent 在没有 Skill 的情况下失败（RED），再写 Skill 让它成功（GREEN），最后堵漏洞（REFACTOR）
• 跨 Agent 兼容： 同时支持 Claude Code、Codex、Gemini CLI、Cursor、OpenCode 等 10+ 平台

哲学洞察： Superpowers 把 Skill 从「参考指南」升级为「行为约束」。它不信任 Agent 会”记住”最佳实践——它用 Skill 机制强制执行。

2.2 Anthropic Skills：极简主义的开放标准

核心理念： Skills 应该像文件系统中的文件夹一样简单——一个 SKILL.md 就是一个 Skill。

Anthropic Skills 的设计原则：

  极简格式          渐进复杂度          开放生态
  ┌─────────┐     ┌──────────┐      ┌──────────┐
  │ name     │     │ 入门只需  │      │ 任何人可  │
  │ desc     │ ──► │ 2个字段   │ ──►  │ 创建分发  │
  │ body     │     │ 高级可加  │      │ agentskills│
  └─────────┘     │ 更多元数据│      │ .io 注册表 │
                  └──────────┘      └──────────┘

Skill 结构：

my-skill/
├── SKILL.md           # 必需：YAML frontmatter + Markdown 指令
├── scripts/           # 可选：可执行脚本
├── references/        # 可选：参考文档
└── templates/         # 可选：模板文件

设计特点：

• 最简格式： 只有 name 和 description 两个必填字段，5 分钟就能写一个 Skill
• 渐进增强： 入门极简，但支持 scripts/、references/、templates/ 等子目录扩展
• 官方示范： 仓库包含文档 Skill（docx/pdf/pptx/xlsx）作为生产级参考实现
• 标准化先行： 通过 agentskills.io 推动行业标准，不做平台锁定

哲学洞察： Anthropic 把 Skill 定位为「AI 时代的文件格式」——像 Markdown 之于文档、JSON 之于数据。格式越简单，生态越繁荣。

2.3 Hermes Agent：自我进化的 Skill 系统

核心理念： Agent 不应该只使用 Skills——它应该能自己创建和改进 Skills。

Hermes Agent 的闭环学习系统：

  ┌──────────────────────────────────────────┐
  │                                          │
  │   执行任务    复杂任务完成     自动创建    │
  │   ────────►  (5+ tool calls) ──► Skill   │
  │                                          │
  │      │                          │        │
  │      │                          ▼        │
  │      │                    使用过程中发现  │
  │      │                    步骤缺失/过时   │
  │      │                          │        │
  │      │                          ▼        │
  │      │                    自动 patch     │
  │      │                    更新 Skill     │
  │      │                          │        │
  │      ▼                          ▼        │
  │   下次会话                  更完善的      │
  │   自动加载 ◄─────────────── Skill         │
  │                                          │
  └──────────────────────────────────────────┘

设计特点：

• 自主创建： Agent 完成复杂任务后，主动提出保存为 Skill（skill_manage(action='create')）
• 运行时改进： 使用 Skill 时发现步骤缺失，立即 patch（skill_manage(action='patch')）
• 记忆联动： Skills 是「过程记忆」，Memory 是「事实记忆」——两者协同工作
• 符合标准： 兼容 agentskills.io 格式，Skill 可以跨平台使用

哲学洞察： Hermes 把 Skill 系统从「静态知识库」变成了「活的知识引擎」。Skill 不是人写给 Agent 的命令——而是 Agent 从经验中提炼的方法论。

2.4 三方设计对比总结

维度	Superpowers	Anthropic Skills	Hermes Agent
定位	方法论强制执行	开放标准 + 参考实现	自我进化的知识引擎
Skill 格式	SKILL.md（YAML + MD）	SKILL.md（YAML + MD）	SKILL.md（YAML + MD）
触发方式	上下文自动匹配	用户显式调用	自动匹配 + 用户调用
依赖管理	无显式依赖	无显式依赖	requires 字段支持
Skill 创建	人写（TDD 方法）	人写（模板化）	Agent 自主创建 + 人写
跨平台	10+ Agent 平台	Claude 生态	自主平台
学习能力	无	无	从经验中学习改进

---

三、动手构建：Agent Skill System

理解了设计哲学，我们来动手实现一个自己的 Agent Skill 系统。目标：

• 符合 agentskills.io 标准格式
• 支持 Skill 发现、加载、匹配
• 支持依赖链解析
• 完整测试覆盖（30 个测试用例，100% 通过）

3.1 环境搭建

# 克隆项目
git clone https://github.com/liyeping/agent-skill-system.git
cd agent-skill-system

# 安装依赖
pip install -r requirements.txt

# 运行测试
pytest tests/ -v

# 启动交互式 Demo
python examples/chat_demo.py

核心依赖只有两个：pyyaml（解析 YAML frontmatter）和 pytest（测试）。

3.2 架构设计

┌──────────────────────────────────────────────────┐
│                  Agent Skill System                │
│                                                    │
│  ┌──────────────┐   ┌──────────────┐              │
│  │  SKILL.md    │   │  SKILL.md    │   ...        │
│  │  (code-      │   │  (debugging) │              │
│  │   review)    │   │              │              │
│  └──────┬───────┘   └──────┬───────┘              │
│         │                  │                       │
│         ▼                  ▼                       │
│  ┌─────────────────────────────────┐              │
│  │        SkillRegistry            │              │
│  │  ┌───────────┐ ┌─────────────┐ │              │
│  │  │ discover  │ │   index     │ │              │
│  │  │ (walk dir)│ │ (by name/   │ │              │
│  │  │           │ │  tag/prio)  │ │              │
│  │  └───────────┘ └─────────────┘ │              │
│  │  ┌───────────────────────────┐ │              │
│  │  │        match()            │ │              │
│  │  │  name→keyword→partial→prio│ │              │
│  │  └───────────────────────────┘ │              │
│  └──────────────┬──────────────────┘              │
│                 │                                  │
│                 ▼                                  │
│  ┌─────────────────────────────────┐              │
│  │       SkillExecutor             │              │
│  │  ┌────────────┐ ┌────────────┐ │              │
│  │  │ resolve    │ │  format    │ │              │
│  │  │ deps       │ │  prompt    │ │              │
│  │  └────────────┘ └────────────┘ │              │
│  └─────────────────────────────────┘              │
│                                                    │
│  输出：格式化的 Prompt Injection，注入 Agent 的     │
│  System Prompt，让 Agent 按照 Skill 指令执行        │
└──────────────────────────────────────────────────┘

---

四、核心模块实现

4.1 Frontmatter 解析器

这是整个系统的基石——按照 agentskills.io 标准解析 SKILL.md：

# skill_core/frontmatter.py

@dataclass
class SkillFrontmatter:
    """解析后的 YAML frontmatter"""
    name: str
    description: str
    version: str = "1.0.0"
    author: str = ""
    tags: list[str] = field(default_factory=list)
    priority: int = 0
    requires: list[str] = field(default_factory=list)

@dataclass
class Skill:
    """完整的 Skill 对象"""
    frontmatter: SkillFrontmatter
    body: str              # Markdown 正文
    source_path: Path      # 文件路径

关键设计决策：

• priority：多个 Skill 匹配同一上下文时，高优先级的胜出
• requires：声明依赖，加载时自动解析依赖链
• extras：保留所有未知字段，向前兼容 agentskills.io 规范演进

4.2 Skill 注册表

注册表负责发现、加载、索引和匹配：

# skill_core/registry.py

class SkillRegistry:
    def discover(self, skills_dir: str) -> int:
        """递归扫描目录，发现所有 SKILL.md"""
        for skill_md in Path(skills_dir).rglob("SKILL.md"):
            skill = self._load_one(skill_md)
            self._index(skill)  # 按 name + tags 建索引

    def match(self, context: str) -> Optional[Skill]:
        """四级匹配策略"""
        # 1. 精确名称匹配（"review my code" → code-review）
        # 2. 关键词 Jaccard 重叠（描述词 vs 上下文词）
        # 3. 子串/部分匹配（"debug" ↔ "debugging"）
        # 4. Priority 加成（同匹配度时高优先生效）

匹配算法打分流程：

def _score_one(self, skill, context_lower) -> float:
    exact_score = jaccard(skill_tokens, ctx_tokens)  # 精确重叠
    name_bonus = 30.0 if skill_name in context else 0  # 名称命中强信号
    priority_bonus = priority * 5 if content_match else 0
    return exact + partial + name + priority

跨语言困境：

4.2.1 跨语言匹配：LLM 驱动的语义匹配

问题本质： 关键词匹配依赖词形重叠（”debug” ↔ “debugging”），但中文 “排查Bug” 和英文描述 “encountering bugs” 之间没有任何词形重叠。

Hermes Agent 的做法： 不在代码层做匹配，而是让 LLM 自己做。Agent 的 System Prompt 里注入了所有 Skill 的摘要（name + description），用户发来中文消息后，LLM 读一遍 Skill 列表，自己判断该加载哪个。

这个设计有两个精妙之处：

1. 语言无关： LLM 理解语义，不依赖词形。中文 “排查Bug” 和英文 “debugging” 在语义空间里是邻居。
2. 意图理解： “帮我看看这段代码有什么问题” → LLM 判断意图是 code-review，不是 debugging。

我们把这个能力加入系统——不是替换关键词匹配，而是作为fallback：

匹配策略架构：

  用户输入
     │
     ▼
  ┌──────────────┐
  │  关键词匹配   │  ← 快速，免费，90%场景
  │  (Jaccard +   │
  │   子串匹配)    │
  └──────┬───────┘
         │
    命中? │─── 是 ──► 返回结果
         │
         否
         │
         ▼
  ┌──────────────┐
  │  LLM 语义匹配 │  ← 准确，跨语言，10%场景
  │  (将 Skill 列表 │
  │   发给 LLM)    │
  └──────────────┘
         │
         ▼
      返回结果

实现代码：

# skill_core/llm_matcher.py

class LLMMatcher:
    """让 LLM 从用户消息中匹配 Skill"""

    MATCH_PROMPT = """You are a skill matching system...

## Available Skills
{skills_summary}

## User Request
{user_message}

## Instructions
...
Respond with ONLY the skill name or "NONE"."""

    def match(self, context: str) -> Optional[Skill]:
        prompt = self.MATCH_PROMPT.format(
            skills_summary=self._build_skills_summary(),
            user_message=context,
        )
        response = self._llm(prompt).strip()
        return self._registry.get(self._parse_response(response))

接入真实 LLM 只需一行：

import openai

def call_openai(prompt: str) -> str:
    return openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}],
    ).choices[0].message.content

matcher = LLMMatcher(llm_call=call_openai)
registry.attach_llm_matcher(matcher)

# 现在中文也能匹配了！
registry.match("帮我审查一下这个PR")  # → code-review ✅

为了可测试，我们内置了一个 mock_llm_call（中英文关键词映射），无需 API 调用即可验证整个链路。

效果对比：

# 纯关键词模式
python examples/chat_demo.py
💬 帮我审查一下这个PR
❌ 未匹配到任何 Skill

# 混合匹配模式（关键词 + LLM fallback） python examples/chat_demo.py --llm
💬 帮我审查一下这个PR
✅ 匹配成功 [🌐 LLM语义]: code-review

💬 生产环境有个报错需要排查
✅ 匹配成功 [🌐 LLM语义]: debugging

💬 调研一下最新的AI框架
✅ 匹配成功 [🌐 LLM语义]: web-research

💬 今天天气怎么样
❌ 未匹配到任何 Skill（无关话题正确拒绝）

关键设计决策： 为什么不做纯粹的中文分词匹配？因为做不到。中文 “排查” 可以映射到 “debugging”，但 “排查” 也可以映射到 “code-review”（审查代码也是一种排查）。只有 LLM 能理解 意图 而非只是 词形。

4.3 Skill 执行器

执行器负责加载匹配到的 Skill，解决依赖链，格式化输出：

# skill_core/executor.py

class SkillExecutor:
    def load(self, skill: Skill) -> str:
        """加载 Skill 及所有依赖，返回可注入 Agent 的 prompt"""
        resolved = self._resolve_deps(skill)  # 拓扑排序依赖
        blocks = [self._format_skill(s) for s in resolved]
        return "\n\n".join(blocks)

    def match_and_load(self, context: str) -> Optional[str]:
        """一站式：匹配 + 加载 + 格式化"""
        skill = self.registry.match(context)
        return self.load(skill) if skill else None

依赖链解析：

def _resolve_deps(self, skill, visited=None):
    """深度优先 + 环检测，返回拓扑序（依赖在前）"""
    # base-skill → derived-skill
    # 输出顺序：base-skill 的指令在前，derived-skill 在后

4.4 示例 Skill

系统自带 4 个可用的示例 Skill，覆盖完整的 Agent 工作流：

Skill	用途	Tags
code-review	PR 审查流程，含评论规范	code, review, quality
test-driven-dev	RED-GREEN-REFACTOR 铁律	testing, tdd, quality
debugging	4阶段系统化排错	debugging, troubleshooting
web-research	网络调研+来源评估	research, web, search

---

五、运行与测试

5.1 交互式 Demo

$ python examples/chat_demo.py

============================================================
  🧠  Agent Skill System — Interactive Demo
============================================================

📚 Loaded Skills (4):
  🔹 code-review (v1.0.0, pri=10)
     Use when reviewing pull requests, code changes, or merge requests...
     Tags: code, review, quality, collaboration
  🔹 test-driven-dev (v1.0.0, pri=15)
     Use when implementing any feature or bugfix, before writing implementation...
     Tags: testing, tdd, quality, development
  ...

💬 You: please review my pull request
✅ Matched Skill: code-review

💬 You: I found a strange bug in production
✅ Matched Skill: debugging

💬 You: what's the weather like?
❌ No skill matched for this input.

5.2 测试结果

$ pytest tests/ -v
============================= 30 passed in 0.10s ==============================

tests/test_skills.py::TestParseSkill::test_basic_parse PASSED
tests/test_skills.py::TestParseSkill::test_missing_frontmatter PASSED
tests/test_skills.py::TestParseSkill::test_missing_name PASSED
tests/test_skills.py::TestParseSkill::test_missing_description PASSED
tests/test_skills.py::TestParseSkill::test_empty_body PASSED
tests/test_skills.py::TestParseSkill::test_name_too_long PASSED
tests/test_skills.py::TestParseSkill::test_tags_and_priority PASSED
tests/test_skills.py::TestValidateSkill::test_valid_skill PASSED
tests/test_skills.py::TestValidateSkill::test_description_not_starting_with_use_when PASSED
tests/test_skills.py::TestValidateSkill::test_invalid_name_format PASSED
tests/test_skills.py::TestRegistry::test_discover_and_list PASSED
tests/test_skills.py::TestRegistry::test_get_by_name PASSED
tests/test_skills.py::TestRegistry::test_by_tag PASSED
tests/test_skills.py::TestMatching::test_exact_name_match PASSED
tests/test_skills.py::TestMatching::test_tag_match PASSED
tests/test_skills.py::TestMatching::test_no_match PASSED
tests/test_skills.py::TestMatching::test_priority_tiebreaker PASSED
tests/test_skills.py::TestExecutor::test_load_single_skill PASSED
tests/test_skills.py::TestExecutor::test_dependency_chain PASSED
tests/test_skills.py::TestExecutor::test_match_and_load PASSED
tests/test_skills.py::TestExecutor::test_no_match_returns_none PASSED
tests/test_skills.py::TestIntegration::test_full_workflow PASSED
tests/test_skills.py::TestLLMMatcher::test_chinese_code_review PASSED
tests/test_skills.py::TestLLMMatcher::test_chinese_debugging PASSED
tests/test_skills.py::TestLLMMatcher::test_chinese_research PASSED
tests/test_skills.py::TestLLMMatcher::test_auto_strategy_falls_back_to_keyword PASSED
tests/test_skills.py::TestLLMMatcher::test_auto_strategy_llm_fallback PASSED
tests/test_skills.py::TestLLMMatcher::test_llm_no_match PASSED
tests/test_skills.py::TestLLMMatcher::test_mock_llm_keyword_map PASSED
tests/test_skills.py::TestHybridMatcher::test_keyword_first_llm_fallback PASSED

---

六、进阶玩法

6.1 接入真实 Agent

将 Skill 系统的输出注入到 LLM 的 System Prompt：

from skill_core import SkillRegistry, SkillExecutor

registry = SkillRegistry()
registry.discover("./skills")
executor = SkillExecutor(registry)

# 获取 Skill 上下文
skill_context = executor.match_and_load(user_message)

# 注入到 LLM 调用
system_prompt = f"""You are a helpful coding assistant.
When relevant skills are available, follow them strictly.

{skill_context if skill_context else ""}
"""

response = llm.chat(
    system=system_prompt,
    messages=[{"role": "user", "content": user_message}]
)

6.2 创建自定义 Skill

只需创建一个目录和 SKILL.md：

---
name: api-design
description: Use when designing REST APIs, endpoints, or request/response schemas
tags: [api, design, rest]
priority: 10
---

# API Design Skill

## Principles
1. **Resources, not actions**: `/users` not `/getUsers`
2. **Consistent naming**: plural nouns, kebab-case URLs
3. **Proper HTTP methods**: GET (read), POST (create), PUT (replace),
   PATCH (update), DELETE (remove)

## Checklist
- [ ] URLs use nouns, not verbs
- [ ] POST returns 201 with Location header
- [ ] Errors use consistent format: `{"error": "message", "code": "TYPE"}`
- [ ] Pagination via `?page=1&limit=20`, response includes `total` count
- [ ] All endpoints have OpenAPI/Swagger documentation

6.3 接入真实 LLM 做语义匹配（替换关键词匹配）

当前实现使用 Jaccard + 子串匹配 + LLM fallback。对于生产环境，可以直接将默认匹配器切换为 LLM 驱动的语义匹配：

# 使用 embedding 做语义匹配
from sentence_transformers import SentenceTransformer

model = SentenceTransformer('all-MiniLM-L6-v2')

class SemanticSkillRegistry(SkillRegistry):
    def __init__(self):
        super().__init__()
        self._embeddings = {}  # skill_name → embedding

    def _index(self, skill):
        super()._index(skill)
        self._embeddings[skill.name] = model.encode(
            f"{skill.description} {' '.join(skill.frontmatter.tags)}"
        )

    def match(self, context):
        ctx_emb = model.encode(context)
        best = max(
            self._embeddings.items(),
            key=lambda kv: cosine_similarity(ctx_emb, kv[1])
        )
        return self.get(best[0])

6.4 Skill 市场 / 注册表

参考 agentskills.io 注册表 + Claude Plugin Marketplace 的模式：

# 从远程注册表安装 Skill
skill install code-review@community-registry
skill search "api design"
skill publish ./my-skill  # 发布到注册表

---

七、项目结构

agent-skill-system/
├── README.md
├── requirements.txt          # pyyaml + pytest
├── config.py                 # 环境变量配置
│
├── skill_core/               # 核心库
│   ├── __init__.py           # 公共 API 导出
│   ├── frontmatter.py        # SKILL.md 解析器 + 数据模型
│   ├── registry.py           # Skill 注册表（发现、索引、匹配）
│   ├── executor.py           # Skill 执行器（依赖解析、格式化）
│   └── llm_matcher.py        # LLM 语义匹配器 + 混合匹配策略
│
├── skills/                   # 示例 Skill 库
│   ├── code-review/SKILL.md
│   ├── test-driven-dev/SKILL.md
│   ├── debugging/SKILL.md
│   └── web-research/SKILL.md
│
├── examples/
│   └── chat_demo.py          # 交互式演示
│
└── tests/
    └── test_skills.py        # 22 个测试用例

---

八、总结

我们做了什么

1. 深入理解了三套主流 Skills 框架的设计哲学：
   • Superpowers 把 Skill 当方法论强制执行
   • Anthropic 把 Skill 当开放文件格式
   • Hermes 把 Skill 当自我进化的知识引擎
2. 从零构建了一个可用的 Agent Skill 系统（v1.1）：
   • 符合 agentskills.io 标准
   • 支持发现、加载、关键词匹配、LLM 语义匹配、依赖解析
   • 30 个测试用例，100% 通过
   • 4 个可直接使用的示例 Skill
   • 双语支持：关键词匹配（英文，零成本）+ LLM 语义匹配（中文/任意语言，智能 fallback）

Skills 的未来

Agent Skills 正在成为 AI 基础设施的关键层——就像 package manager 之于软件开发，Skills 让 Agent 的能力可以模块化、可复用、可分发。而最令人兴奋的是，像 Hermes Agent 这样的系统正在让 Skills 自我进化——Agent 从经验中学习，自己写自己的 Skill。

未来已来，而且它是分层的。

---

参考资料

• agentskills.io 规范
• Superpowers 仓库 — 205k⭐
• Anthropic Skills 仓库 — 140k⭐
• Hermes Agent 仓库 — 166k⭐
• Equipping agents for the real world with Agent Skills
• Superpowers 发布公告