如何构建 AI Skill 体系：从设计哲学到工程实践的深度分析

第一层：元数据（~100 词）
  └── name + description
      └── 始终存在于上下文，用于触发判断

第二层：SKILL.md 主体（<500 行）
  └── 触发后加载
      └── 核心流程、关键决策点

第三层：捆绑资源（无限制）
  └── 按需加载
      └── 脚本、参考文档、模板资产

my-skill/
├── SKILL.md                   ← 必须，核心文件
│   ├── YAML frontmatter       ← name, description（触发机制）
│   └── Markdown instructions  ← 工作流、决策树、示例
│
├── scripts/                   ← 可选，确定性/重复性任务
│   ├── process.py
│   └── validate.sh
│
├── references/                ← 可选，按需加载的参考文档
│   ├── api-spec.md
│   ├── style-guide.md
│   └── edge-cases.md
│
├── assets/                    ← 可选，输出用的模板和静态资源
│   ├── template.docx
│   ├── logo.png
│   └── fonts/
│
└── evals/                     ← 可选，测试用例
    ├── evals.json
    └── files/                 ← 测试输入文件
        ├── sample1.pdf
        └── sample2.xlsx

---
name: skill-identifier           # 唯一标识符，kebab-case
description: |                   # 触发描述（最重要的字段）
  这个 Skill 做什么、何时触发。
  要略带"强制性"——描述触发条件时要
  明确列出关键词和场景，防止欠触发。
  例如：当用户提到 X、Y、Z 时使用此技能，
  即使他们没有明确要求也应触发。
compatibility:                   # 可选
  tools: [bash, python]
  mcp: [filesystem, github]
---

# Skill 名称

## 概述
用 2-3 句话描述这个 Skill 解决什么问题。

## 前置条件
执行此 Skill 前需要检查什么。

## 核心工作流

### 步骤 1：[动词+名词]
具体的操作说明...

### 步骤 2：[动词+名词]
...

## 决策树
面对特定情况时如何选择路径。

## 输出规范
期望的输出格式和质量标准。

## 错误处理
常见错误和处理方式。

## 示例
输入/输出示例（最有效的学习材料）。

用户输入
    │
    ▼
AI 扫描 available_skills 列表
    │
    ▼
逐一比对 name + description
    │
    ▼
相关性判断（内部推理）
    │
    ├── 匹配 → 读取 SKILL.md → 执行
    └── 不匹配 → 直接回答

# ❌ 弱触发描述
description: "创建 Word 文档的方法"

# ✅ 强触发描述
description: |
  创建专业 Word 文档（.docx）。当用户要求生成报告、
  备忘录、信件、合同或任何需要保存为 Word 格式的文档时，
  必须使用此技能，即使用户只是说"写一份文档"或"做个总结"。
  包含表格、目录、页眉页脚等复杂格式时尤其适用。

┌─────────────────────────────────────────────────────────────┐
│                   Skill 开发生命周期                         │
│                                                             │
│  1. 意图捕获  →  2. 访谈调研  →  3. 编写草稿               │
│       │               │               │                    │
│       └───────────────┴───────────────┘                    │
│                       │                                    │
│              4. 编写测试用例                                 │
│                       │                                    │
│              5. 执行测试运行                                 │
│                       │                                    │
│              6. 人工评审结果        ←─────────┐            │
│                       │                       │            │
│              7. 量化评估打分                   │            │
│                       │                       │            │
│              8. 改进 Skill ────────────────────┘           │
│                       │                                    │
│              9. 扩大测试集                                   │
│                       │                                    │
│             10. 优化触发描述                                 │
│                       │                                    │
│             11. 打包分发（.skill）                          │
└─────────────────────────────────────────────────────────────┘

{
  "skill_name": "pdf-processor",
  "evals": [
    {
      "id": 1,
      "prompt": "从这份合同中提取所有甲乙双方信息和关键条款",
      "expected_output": "包含双方名称、签约日期、核心条款的结构化摘要",
      "files": ["evals/files/contract_sample.pdf"],
      "expectations": [
        "输出包含甲方和乙方的完整名称",
        "签约日期被正确识别和格式化",
        "关键条款以列表形式呈现",
        "生成了可下载的结构化输出文件",
        "未出现内容幻觉（捏造原文没有的信息）"
      ]
    },
    {
      "id": 2,
      "prompt": "合并这三个报告为一个综合文档",
      "files": [
        "evals/files/report_q1.pdf",
        "evals/files/report_q2.pdf",
        "evals/files/report_q3.pdf"
      ],
      "expectations": [
        "输出是单一的合并 PDF 文件",
        "原始三个文档的内容均被保留",
        "包含统一的目录页",
        "页码连续编排"
      ]
    }
  ]
}

测试运行
    │
    ▼
grading.json（每个用例的评估结果）
    │
    ├── expectations[]    ← 每条断言的 passed/failed + evidence
    ├── summary           ← pass_rate, passed, failed, total
    ├── execution_metrics ← tool_calls, total_steps, errors
    └── timing            ← executor/grader 耗时
    │
    ▼
benchmark.json（跨配置的统计汇总）
    │
    ├── with_skill:    { pass_rate: {mean: 0.85, stddev: 0.05} }
    ├── without_skill: { pass_rate: {mean: 0.35, stddev: 0.08} }
    └── delta:         { pass_rate: "+0.50" }

版本历史（history.json）示例：

v0 (baseline):  pass_rate = 0.45  → grading_result: "baseline"
v1 (改进流程):  pass_rate = 0.67  → grading_result: "won"
v2 (增加脚本):  pass_rate = 0.82  → grading_result: "won"
v3 (优化断言):  pass_rate = 0.79  → grading_result: "lost"  ← 回退到 v2
v4 (调整提示):  pass_rate = 0.88  → grading_result: "won"   ← current_best

# 运行自动化优化循环
python -m scripts.run_loop \
  --eval-set trigger_evals.json \
  --skill-path ./my-skill \
  --model claude-sonnet-4-20250514 \
  --max-iterations 5 \
  --verbose

{
  "skill_name": "docx",
  "evals": [
    { "prompt": "帮我写一份项目报告", "should_trigger": true },
    { "prompt": "生成一个 Word 格式的周报", "should_trigger": true },
    { "prompt": "做个 PPT 演示", "should_trigger": false },
    { "prompt": "把数据整理成表格", "should_trigger": false },
    { "prompt": "起草一封正式信件", "should_trigger": true }
  ]
}

迭代 0 (原始):
  触发率（应触发查询）: 62%
  误触发率（不应触发）: 28%
  综合得分: 0.67

迭代 1 (增加关键词):
  触发率: 78%
  误触发率: 22%
  综合得分: 0.78

迭代 2 (细化场景描述):
  触发率: 89%
  误触发率: 11%
  综合得分: 0.89  ← 测试集最优

迭代 3 (过度强调):
  触发率: 95%
  误触发率: 35%  ← 误触发率上升
  综合得分: 0.80  ← 退步，选择 v2

输入：上传的文件（PDF、Excel、Word...）
处理：提取、转换、合并、拆分
输出：新格式文件
代表：docx-skill、pdf-skill、xlsx-skill
特点：确定性强，易于测试，脚本化程度高

输入：描述、风格要求、参考材料
处理：理解意图、应用风格规则、生成内容
输出：文章、代码、设计、演示文稿
代表：frontend-design-skill、pptx-skill
特点：主观性强，需要质量评判标准

输入：复杂任务描述
处理：分解任务、调用工具、协调多步骤
输出：任务完成结果
代表：skill-creator、mcp-builder
特点：依赖 MCP 和外部工具，状态管理复杂

输入：领域专业问题
处理：应用专业知识框架、检索参考文档
输出：专业建议、分析报告
代表：product-self-knowledge
特点：知识密集型，更新频率高

轻量 Skill（无依赖）
  └── 仅需 SKILL.md
  └── 示例：写作风格指南、代码规范

中量 Skill（脚本依赖）
  └── SKILL.md + scripts/
  └── 示例：pdf-skill（依赖 pypdf）、xlsx-skill（依赖 openpyxl）

重量 Skill（MCP 依赖）
  └── SKILL.md + scripts/ + MCP servers
  └── 示例：github-workflow-skill、slack-integration-skill
  └── 需要在 compatibility 中声明

cloud-deploy-skill/
├── SKILL.md              ← 入口：识别场景，路由到具体文档
└── references/
    ├── aws.md            ← AWS 特定指南
    ├── gcp.md            ← GCP 特定指南
    └── azure.md          ← Azure 特定指南

## 平台选择

根据用户描述的环境，读取对应的参考文档：
- 提到 EC2、S3、Lambda → 读取 `references/aws.md`
- 提到 GKE、Cloud Run → 读取 `references/gcp.md`
- 提到 AKS、Azure Functions → 读取 `references/azure.md`
- 未指定 → 询问用户偏好

用户: "分析这份财报 PDF，生成 PPT 汇报，发送到 Slack"

触发顺序：
  1. pdf-skill      → 提取财报数据
  2. pptx-skill     → 生成 PPT
  3. slack-skill    → 发送消息（MCP）

skill-creator/
├── SKILL.md                    ← 主工作流
├── agents/
│   ├── grader.md               ← 评估智能体指令
│   ├── comparator.md           ← 对比智能体指令
│   └── analyzer.md             ← 分析智能体指令
├── scripts/
│   ├── run_eval.py             ← 执行评估
│   ├── run_loop.py             ← 优化循环
│   ├── generate_report.py      ← 生成报告
│   └── package_skill.py        ← 打包分发
└── eval-viewer/
    └── generate_review.py      ← 人工审查界面

skill-registry/
├── public/                     ← 所有人可用
│   ├── docx.skill
│   ├── pdf.skill
│   └── xlsx.skill
│
├── private/                    ← 仅内部团队
│   ├── company-guidelines.skill
│   └── internal-api.skill
│
├── examples/                   ← 参考实现
│   ├── skill-creator.skill
│   └── mcp-builder.skill
│
└── deprecated/                 ← 即将退役
    └── old-formatter.skill

# SKILL.md frontmatter 版本字段
---
name: pdf-processor
version: "2.3.1"
min_claude_version: "claude-sonnet-4"
changelog:
  - "2.3.1": "修复大文件处理的内存溢出问题"
  - "2.3.0": "新增 OCR 支持"
  - "2.2.0": "支持批量处理"
deprecated_since: null
---

□ pass_rate (with_skill) ≥ 0.80
□ delta.pass_rate ≥ 0.30（相比无 Skill 的提升）
□ stddev ≤ 0.10（结果稳定性）
□ errors_encountered = 0（无执行错误）
□ 触发率 ≥ 0.85（description 优化后）
□ 误触发率 ≤ 0.15
□ 有完整的 evals.json（≥ 5 个测试用例）
□ 有边界情况测试（空输入、异常格式等）
□ README 或 description 中有使用示例
□ 依赖项在 compatibility 中声明

Skill 体系（工作流方法论）
    ├── 调用 MCP Tools（原子操作）
    ├── 检索 RAG（背景知识）
    └── 使用系统提示词（基础行为规范）

目标：生成结构化的竞品分析报告（.docx 格式）
触发场景：用户要求分析竞争对手、市场格局、产品对比
输入：竞品名称列表 + 分析维度（可选）
输出：专业的竞品分析 Word 文档

---
name: competitive-analysis
description: |
  生成专业竞品分析报告（Word 文档）。当用户提到竞争对手分析、
  市场格局研究、产品对比、行业调研时必须使用此技能。
  即使用户只说"分析一下竞品"或"看看对手在做什么"也应触发。
---

# 竞品分析 Skill

## 工作流

### 步骤 1：确认分析范围
- 询问或确认目标竞品列表（2-6 家）
- 确认分析维度（默认：功能、定价、用户评价、市场份额）

### 步骤 2：信息收集（使用 Web Search）
- 为每家竞品搜索：官网信息、定价页面、用户评价
- 重点收集：核心功能列表、定价策略、差异化卖点

### 步骤 3：结构化整理
按以下结构组织数据：
| 维度 | 竞品A | 竞品B | 竞品C |
|------|-------|-------|-------|
| 核心定位 | ... | ... | ... |
| 价格区间 | ... | ... | ... |
| 主要功能 | ... | ... | ... |
| 市场口碑 | ... | ... | ... |

### 步骤 4：生成文档
读取 docx-skill，按照文档规范生成报告，包含：
- 执行摘要（1 页）
- 竞品概况（每家半页）
- 对比矩阵（表格）
- 战略建议（1 页）

{
  "skill_name": "competitive-analysis",
  "evals": [
    {
      "id": 1,
      "prompt": "帮我分析 Notion、Obsidian 和 Roam Research 的竞争格局",
      "expectations": [
        "生成了 .docx 格式的分析报告",
        "报告包含三个竞品的对比内容",
        "包含功能对比表格",
        "有战略建议部分",
        "报告超过 3 页"
      ]
    }
  ]
}

v0 pass_rate: 0.60  → 缺失战略建议部分
v1 pass_rate: 0.75  → 表格格式不规范
v2 pass_rate: 0.88  → ✅ 达到质量门禁

用户偏好: "我喜欢简洁的报告，不超过 2 页"
→ Skill 自动调整输出规范，无需修改 SKILL.md

公司 A 发布：financial-report-skill
公司 B 发布：legal-contract-skill
社区贡献：100+ 专业领域 Skill

→ AI 系统按需订阅，构建个性化能力图谱

复杂项目管理 Agent
  ├── 需要文档？→ 调用 docx-skill
  ├── 需要数据？→ 调用 xlsx-skill
  ├── 需要汇报？→ 调用 pptx-skill
  └── 需要发布？→ 调用 github-release-skill