Skill 深度解析 — cc4pm 第 6.1 课

从传统软件到 Skill：交付形态的演进

.exe / .app

安装程序

→

npm install

包管理器

→

SaaS URL

Web 应用

→

SKILL.md

自然语言入口

Skill 是新一代交互式软件的雏形。
入口是 SKILL.md，界面是自然语言，AI 根据上下文自适应执行。

Skill 的解剖结构

skill-name/

SKILL.md 必需

├ YAML frontmatter

└ Markdown body

scripts/ 可选

└ rotate_pdf.py

references/ 可选

├ finance.md

└ api_docs.md

assets/ 可选

├ logo.png

└ template.pptx

目录	用途	加载方式
`SKILL.md`	入口 + 工作流指令	触发时加载
`scripts/`	确定性操作（避免重写代码）	执行，不读入上下文
`references/`	领域知识、API 文档	Claude 按需读取
`assets/`	输出模板、品牌素材	用于输出，不读入上下文

三级渐进式披露——上下文的精妙管理

100 个 Skill 不会拖慢你的日常对话——因为只加载需要的部分。

Level 1：元数据 — name + description
始终在上下文中 · ~100 词 · 用于语义匹配触发常驻

Level 2：SKILL.md body — 工作流指令
触发后加载 · <5K 词 · 核心步骤和约束触发时

Level 3：bundled resources — 脚本 / 引用 / 资产
Claude 按需读取 · 无限制 · 脚本可执行不加载按需

创建 Skill 的六步流程

1

理解

用具体示例明确功能

2

规划

识别可复用资源

3

初始化

init_skill.py 创建模板

4

编辑

实现资源 + 写 SKILL.md

5

打包

package_skill.py 验证

6

迭代

真实使用中改进

写好 description——Skill 的灵魂

description 是 Skill 被自动发现的关键。Claude 做语义匹配时完全依赖它。

BAD

description: "A general-purpose document tool"

太模糊，什么时候触发？
和什么匹配？

GOOD

description: "Use when the user wants to create, read, edit, or convert Word documents (.docx). Covers: (1) Creating new documents, (2) Editing content, (3) Tracked changes, (4) Comments"

动作开头 + 具体场景 + 关键词丰富

写作要诀：以动作开头 · 列出 2-4 个触发场景 · 控制 1-3 句 · 包含语义关键词

测试 Skill：可触发性 & 可复现性

可触发性

可复现性

测试类型	方法	预期
精确匹配	用 description 中的关键词	100% 触发
语义匹配	用同义词、换一种说法	应该触发
负面排除	用不相关的请求	不应触发
多语言	中文和英文分别测试	都应触发

# 正向测试
claude "帮我创建一个 PRD"
# → 预期：bmad-create-prd 激活

# 负向测试
claude "帮我修一个 CSS bug"
# → 预期：bmad-create-prd 不激活

测试维度	标准
输出结构一致	同样请求产出同样的章节/格式
步骤完整性	工作流中的每一步都被执行
脚本可执行	附带的脚本在干净环境中能运行
引用可发现	Claude 能找到并正确使用 reference 文件

# 空白上下文测试
/clear → 触发 Skill → 记录输出

# 有前置上下文测试
先执行其他操作 → 触发 Skill → 对比

# 重复执行测试
三次 /clear + 相同请求 → 结构应一致