04-Skill 渐进式知识管理

Skill 渐进式知识管理

学习目标

本章将通过 plugin-dev 插件的 7 个 Skill（共 ~11,000 词 SKILL.md + ~10,000 词 references），掌握：

三层渐进式披露结构在 Claude Code 中的具体落地
触发短语设计的最佳实践
SKILL.md、references/ 和 examples/ 的内容边界划分
写作标准：第三人称描述、强触发短语、命令式正文

前置知识

本章涉及 Skill 系统的通用原理，建议先阅读：

Skill 渐进式知识管理

下文假设你已理解 Skill 系统的基础概念，直接聚焦 Claude Code 的具体实现。

项目实践

plugin-dev 的 7 个 Skill 概览

plugin-dev 是 Claude Code 仓库中内容最丰富的插件，包含 7 个专项 Skill：

Skill	SKILL.md 词量	References 数量	核心主题
`plugin-structure`	~1,619	2	插件目录结构、plugin.json 清单、自动发现
`hook-development`	~1,619	3	9 种 Hook 事件、匹配器、安全、调试
`mcp-integration`	~1,666	3	MCP 服务器类型、认证、工具命名
`plugin-settings`	~1,623	2	设置文件模式、YAML frontmatter 解析
`command-development`	~1,535	7	斜杠命令结构、frontmatter 字段、动态参数
`agent-development`	~1,438	3	Agent 文件结构、系统提示设计、AI 辅助生成
`skill-development`	~1,232	1	Skill 创建流程、渐进式披露、写作标准

总内容量：~11,000 词 SKILL.md + ~10,000 词 references + 12+ 工作示例 + 6 个验证脚本。

三层结构落地

每个 Skill 严格遵循三层结构：

skills/hook-development/
├── SKILL.md                           # 核心指令（~1,619 词）
├── references/
│   ├── patterns.md                    # 10 种 Hook 模式（~347 词）
│   ├── migration.md                   # 基础到高级迁移（~370 词）
│   └── advanced.md                    # 多阶段验证等高级主题（~477 词）
├── examples/
│   ├── validate-write.sh              # 验证脚本示例
│   ├── validate-bash.sh
│   └── load-context.sh
└── scripts/
    ├── validate-hook-schema.sh        # 验证工具
    ├── test-hook.sh
    └── hook-linter.sh

SKILL.md 的内容边界

SKILL.md 严格控制在 ~1,500-2,000 词，仅包含：

触发短语：何时激活该 Skill
核心流程：主要工作步骤
关键约束：不可违反的规则
引用 links：指向 references/ 的深度文档

不在 SKILL.md 中的内容：

详细的 API 参数说明 → 放入 references/
完整的代码示例 → 放入 examples/
边缘情况和最佳实践 → 放入 references/

触发短语设计实践

以 hook-development Skill 为例：

## 触发短语

当用户想要：
- 创建或修改 Claude Code Hook
- 理解 PreToolUse、PostToolUse、Stop 等 Hook 事件
- 开发基于 Python 或 Bash 的 Hook 脚本
- 调试 Hook 执行问题

这些触发短语具体、明确，覆盖了用户可能的查询方式，同时又不会过于宽泛导致误触发。

自引用教学：Skill 如何教自己

plugin-dev 的一个独特设计是自引用教学——每个 Skill 将其他兄弟 Skill 作为最佳实践的参考：

在 skill-development/SKILL.md 中：

## 学习示例

本插件中的每个 Skill 都演示了它教授的模式：
- hook-development: 优秀的触发短语、精简的 SKILL.md、3 个 references、3 个示例、3 个脚本
- agent-development: 强触发词、专注的 SKILL.md、references 包含 AI 生成提示
- plugin-settings: 具体触发词、references 展示真实实现、可工作的解析脚本

这种”以身作则”的方式确保学习者看到的示例就是他们应该模仿的模式。

写作标准的一致性

plugin-dev 的 7 个 Skill 在所有内容上强制执行一致的写作标准：

维度	标准	正面示例	反面示例
描述	第三人称	”This skill should be used when…"	"Use this skill to…”
触发短语	具体用户查询	”如何创建 hook"	"hook”
正文	命令式/不定式	”To create X, do Y"	"You might want to…”
示例	可运行的	完整的 `.md` 文件	代码片段

验证工具链

plugin-dev 附带 6 个验证脚本，确保 Skill 内容的正确性：

脚本	功能
`validate-hook-schema.sh`	验证 hooks.json 结构
`test-hook.sh`	用样本输入测试 Hook
`hook-linter.sh`	检查 Hook 脚本最佳实践
`validate-agent.sh`	验证 Agent markdown 文件
`parse-frontmatter.sh`	提取 YAML frontmatter
`validate-settings.sh`	验证设置文件

陷阱与对策

陷阱	表现	对策
SKILL.md 超过 3,000 词	每次触发都浪费大量上下文	将细节迁移到 references/
references/ 与 SKILL.md 不一致	模型收到矛盾指令	修改时同步更新所有相关文件
触发短语遗漏常见变体	用户查询无法激活 Skill	分析用户实际查询模式，补充触发列表
示例过于复杂	示例本身难以理解	每个示例聚焦一个概念，保持精简

设计取舍

为什么 SKILL.md 限制在 ~2,000 词？

上下文窗口是有限资源。如果每个 Skill 都携带大量知识，触发判断会变慢，且容易超出窗口限制。2,000 词足够表达核心指令，又不占用过多上下文。

为什么需要 7 个独立 Skill 而非 1 个大 Skill？

每个组件类型（Hook、Command、Agent、Skill、Settings、MCP、Plugin 结构）都有独立的知识体系。合并为一个大 Skill 会导致 SKILL.md 膨胀到 10,000+ 词，违反渐进式披露原则。独立 Skill 允许按需加载——只需开发 Hook 的用户只加载 hook-development，不需要加载全部内容。

代价：用户可能需要同时加载多个 Skill（如同时开发 Command 和 Hook）。为此，/plugin-dev:create-plugin Command 在不同阶段自动加载相应的 Skill。

参考来源

Claude Code Skills 文档
源码: plugins/plugin-dev/skills/*/SKILL.md
源码: plugins/plugin-dev/skills/*/references/*.md

版本信息

📅 2026-05-24 🏷️ v2.1.150 🔀 39e853e