skill-architect

Skill Architect：权威元技能

创建专家级 Agent Skill 的统一权威指南。它编码了真正的领域专业知识，区分出一种 Skill 究竟只是“存在”，还是能够精准触发、高效传授知识，并让用户立即投入工作。

理念

**优秀的 Skill 是渐进式披露机器。**它们编码的是实际领域专业知识（行家门道），而不是表面指令。它们采用三层架构：用于发现的轻量元数据、用于核心流程的精简 SKILL.md，以及仅在需要时加载的深入参考文件。

---

何时使用此 Skill

✅ 适用于：

• 从零开始，或基于现有专业知识创建 Skill
• 审计／评审 Skill 的质量、触发效果和渐进式披露能力
• 提高触发率并减少误触发
• 编码领域专业知识（行家门道、反模式、时效性知识）
• 设计能让子 Agent 有效使用的 Skill
• 构建独立工具（脚本、MCP、子 Agent）
• 调试 Skill 为何无法触发或触发错误

❌ 不适用于：

• 通用 Claude Code 功能（斜杠命令、MCP 服务实现）
• 与 Skill 无关的编码建议或代码评审
• 调试运行时错误（请使用领域专用 Skill）
• 不包含实际领域专业知识的模板生成

---

快速改进（立即见效）

对于现有 Skill，请按优先级依次执行：

1. 精简描述 → 遵循 [内容] [时机] [关键词]。不适用于[排除项] 公式
2. 检查行数 → SKILL.md 必须少于 500 行；将深入内容移至 /references
3. 添加 NOT 条款 → 明确列出排除项，防止误触发
4. 添加 1-2 个反模式 → 使用行家门道模板（新手／专家／时间线）
5. 移除无用文件 → 删除未引用的脚本／参考文件（不留虚设内容）
6. 测试触发效果 → 编写 5 个应该触发和 5 个不应该触发的查询

---

渐进式披露架构

Skill 采用三层加载机制。运行时会在启动时扫描元数据，在 Skill 触发时加载 SKILL.md，并且仅在 Agent 判断有需要时才加载参考文件。

层级	内容	大小	加载方式
1. 元数据	frontmatter 中的 name + description	约 100 个 token	始终在上下文中（目录扫描）
2. SKILL.md	核心流程、决策树、简要反模式	少于 5k 个 token	Skill 触发时
3. 参考文件	深入解析、示例、模板、规范	不限	按需、逐文件加载，仅在相关时加载

关键规则：

• SKILL.md 保持在 500 行以内。将深入内容移至 /references。
• 参考文件不会自动加载。只有在 Skill 触发时，SKILL.md 才会进入上下文。
• 在 SKILL.md 中，为每个参考文件列出一行说明，注明何时查阅。这样能让 Agent 了解可用内容，而无需加载文件。
• 切勿指示“开始前阅读所有参考文件”。应改为：“仅阅读与当前步骤相关的文件。”
• 如果参考文件较大，Agent 应先浏览标题，再深入阅读相关部分。

---

Frontmatter 规则

必填字段

键	用途	示例
name	小写、以连字符分隔的标识符	react-server-components
description	触发条件：[内容] [时机] [关键词]。不适用于[排除项]	参见描述公式

可选字段

键	用途	示例
allowed-tools	以逗号分隔的工具名称（最小权限）	Read,Write,Grep
argument-hint	在自动补全中显示的预期参数提示	"[path] [format]"
license	许可证标识符	MIT
disable-model-invocation	若为 true，则只能由用户通过 /skill-name 触发	true
user-invocable	控制技能是否显示在 UI 菜单中	true
context	执行上下文；fork 会在隔离的子 Agent 中运行技能	fork
agent	当 context: fork 时使用的子 Agent 类型	code-reviewer
model	覆盖技能激活时使用的模型	sonnet
hooks	作用于此技能生命周期的钩子	参见钩子参考
metadata	供工具和仪表板使用的任意键值映射	author: your-org

自定义键（可安全使用）

category、tags、version 等自定义键会被 Claude Code 忽略，但可安全用于你自己的工具（图库网站、文档生成器、仪表板）。它们不会与运行时解析冲突。

无效键（与有效键相似，容易混淆）

# ❌ These look like valid keys but aren't — use the correct alternatives
tools: Read,Write           # Use 'allowed-tools' instead
integrates_with: [...]      # Use SKILL.md body text instead
triggers: [...]             # Use 'description' keywords instead
outputs: [...]              # Use SKILL.md Output Format section instead
coordinates_with: [...]     # Use SKILL.md body text instead
python_dependencies: [...]  # Use SKILL.md body text instead

---

描述公式

模式：[功能] [使用时机] [触发关键词]。不适用于 [排除项]。

描述是激活技能时最重要的一行。Claude 的运行时会扫描描述，以决定加载哪些技能。描述写得不好，就会导致技能从不激活，或不断误触发。

问题	不佳示例	良好示例
过于笼统	“帮助处理图像”	“用于图像与文本匹配及零样本分类的 CLIP 语义搜索。不适用于计数、空间推理或生成。”
没有排除项	“审查代码更改”	“审查 TypeScript/React 差异和 PR 的正确性。不适用于编写新功能。”
像简短手册	“先研究，再列提纲，然后起草……”	“通过结构化研究生成 1-3 页的综合报告。不适用于快速事实问答。”
包罗万象	“帮助进行产品管理”	“编写和完善产品需求文档（PRD）。不适用于战略演示文稿。”
名称不匹配	name: db-migration / desc: “编写营销邮件”	name: db-migration / desc: “规划数据库架构迁移，并制定回滚策略。”

完整指南及更多示例：参见 references/description-guide.md

---

SKILL.md 模板

---
name: your-skill-name
description: [What] [When] [Keywords]. NOT for [Exclusions].
allowed-tools: Read,Write
---

# Skill Name
[One sentence purpose]

## When to Use
✅ Use for: [A, B, C with specific trigger keywords]
❌ NOT for: [D, E, F — explicit boundaries]

## Core Process
[Mermaid diagrams — 23 types available. See visual-artifacts.md for full catalog]

## Anti-Patterns
### [Pattern Name]
**Novice**: [Wrong assumption]
**Expert**: [Why it's wrong + correct approach]
**Timeline**: [When this changed, if temporal]

## References
- `references/guide.md` — Consult when [specific situation]
- `references/examples.md` — Consult for [worked examples of X]

---

创建技能的 6 个步骤

flowchart LR
  S1[1. Gather Examples] --> S2[2. Plan Contents]
  S2 --> S3[3. Initialize]
  S3 --> S4[4. Write Skill]
  S4 --> S5[5. Validate]
  S5 --> S6{Errors?}
  S6 -->|Yes| S4
  S6 -->|No| S7[6. Ship & Iterate]

第 1 步：收集具体示例

收集 3-5 个应该触发此技能的真实查询，以及 3-5 个不应该触发的查询。

第 2 步：规划可复用内容

针对每个示例，找出哪些脚本、参考资料或素材可以避免重复工作。同时找出专业门槛知识：领域算法、时效性知识、框架演进以及常见陷阱。

第 3 步：初始化

scripts/init_skill.py <skill-name> --path <output-directory>

对于现有技能，跳到第 4 步。

第 4 步：编写技能

实现顺序：

1. 先写脚本（scripts/）——可运行的代码，而非模板
2. 接着写参考资料（references/）——领域知识、架构、指南
3. 演示和素材（demo/、assets/、prompts/、templates/）——对于视觉/设计类技能，提供渲染后的 HTML 演示、注明来源的灵感图片、图像生成提示词和入门模板。参见 references/visual-design-skills.md。
4. 最后编写 SKILL.md——核心流程、反模式、参考资料索引

使用祈使句：“要完成 X，请执行 Y”，而不是“你应该执行 X”。

在 SKILL.md 中回答以下问题：

1. 用途：此技能有什么用途？（1-2 句）
2. 激活：什么会触发它？什么不应该触发？
3. 流程：使用 Mermaid 图表（23 种类型）——决策用流程图，协议用时序图，生命周期用状态图等。
4. 反模式：新手容易犯哪些错误？
5. 可视化产物：用 Mermaid 图表呈现工作流、架构和时间线（参见 references/visual-artifacts.md）
6. 参考资料：有哪些文件，以及何时查阅？

第 5 步：验证

python scripts/validate_skill.py <path>
python scripts/check_self_contained.py <path>

按错误 → 警告 → 建议的顺序修复。

第 6 步：迭代

经过实际使用后：留意遇到的困难，改进 SKILL.md 和资源，并更新 CHANGELOG.md。

---

为子 Agent 使用而设计技能

如果技能将由子 Agent 加载（而非仅由用户直接调用），请采用以下模式：

技能加载的三个层级

1. 预加载（2-5 个核心技能）：注入子 Agent 的系统上下文中。这些是其标准操作流程——始终可用。
2. 动态选择：子 Agent 会收到一个目录（名称 + 一行描述），并在开始前选择 1-3 个匹配的技能。协调器也可以预先筛选。
3. 执行时：子 Agent 阅读每项技能的“适用场景”部分，按顺序遵循编号步骤，遵守输出约定，并执行 QA 检查。

子 Agent 应如何使用技能

教会子 Agent 将每项技能视为一个小型协议：

• 检查“适用场景 / 不适用场景”部分，判断是否适用
• 按顺序遵循编号步骤（仅在任务限制迫使其调整时才做调整）
• 遵守技能的输出约定（模板、JSON 结构、必需章节）
• 最后执行 QA / 验证步骤
• 按编号引用技能步骤：“已完成 refactor-plan-skill 的第 3 步”

子 Agent 提示词结构

子 Agent 的提示词应包含四个部分：

1. 身份：“你是[角色]。你负责[狭窄领域]。如果任务超出范围，请说明。”
2. 技能使用规则：“你的技能定义了你的方法。判断哪些技能适用，并遵循其工作流。”
3. 任务循环：重述 → 选择技能 → 澄清 → 规划 → 逐步执行 → 验证 → 返回（产物 + 已使用的技能 + 剩余风险）。
4. 约束：质量标准、安全规则、冲突时的优先级。

完整模板和编排模式：参见 references/subagent-design.md

---

可视化产物：Mermaid 图表与代码

包含 Mermaid 图表的技能可以同时服务两类受众。对人类而言，图表会渲染为可视化流程图、状态机和时间线，能让人一目了然。对 Agent 而言，Mermaid 是基于文本的图形 DSL——A -->|Yes| B 是明确且无歧义的边，实际上比等效的文字描述更容易推理。Agent 读取文本；人类看到图示。两者都能受益。

规则：如果技能描述了流程、决策树、架构、状态机、时间线或数据关系，请加入 Mermaid 图表。在 SKILL.md 中直接使用原始的 ```mermaid 代码块——不要将其包在外层 Markdown 围栏中。

全部 23 种 Mermaid 图表类型

Mermaid 支持 23 种图表类型。请根据内容选择最具体的类型——对于生命周期，状态图比带有“返回”箭头的流程图更合适。

技能内容	图表类型	语法
决策树／故障排查	流程图	flowchart TD
API／Agent 通信协议	时序图	sequenceDiagram
生命周期／状态转换	状态图	stateDiagram-v2
数据模型／架构	ER 图	erDiagram
类型层级／接口	类图	classDiagram
时间知识／演变	时间线	timeline
领域分类／概念图	思维导图	mindmap
优先级矩阵（双轴）	象限图	quadrantChart
组件布局／模块	块图	block-beta
基础设施／云拓扑	架构图	architecture-beta
多层级系统视图（C4）	C4 图	C4Context / C4Container / C4Component
项目阶段／部署计划	甘特图	gantt
Git 分支／发布策略	Git 图	gitGraph
用户体验流程	旅程图	journey
数量流／预算	桑基图	sankey-beta
指标／基准测试	XY 图表	xychart-beta
比例分布	饼图	pie
层级大小比较	矩形式树状图	treemap
多轴能力比较	雷达图	radar
任务／状态跟踪	看板	kanban
需求可追溯性	需求图	requirementDiagram
网络协议／二进制格式	数据包图	packet-beta
时序图（代码语法）	ZenUML	zenuml（插件）

Mermaid 中的 YAML Frontmatter（可选）

Mermaid 支持可选的 --- frontmatter 块，用于自定义渲染效果（主题、颜色、间距）。此项不是必需的。 Agent 会忽略它。渲染器无需此项也会采用合理的默认值。仅当你需要为已发布的文档设置特定视觉样式时，才添加它。

# Optional — only for render customization
---
title: My Diagram
config:
  theme: neutral
  flowchart:
    curve: basis
---

主题：default、dark、forest、neutral、base。完整配置参考：https://mermaid.ai/open-source/config/configuration.html

完整图表目录及全部 16 种以上类型的示例：参见 references/visual-artifacts.md

---

编码识别标志

区分新手与专家的专业知识。LLM 会因训练数据过时或盲目照搬模式而出错的内容。

识别标志模板

### Anti-Pattern: [Name]
**Novice**: "[Wrong assumption]"
**Expert**: [Why it's wrong, with evidence]
**Timeline**: [Date]: [Old way] → [Date]: [New way]
**LLM mistake**: [Why LLMs suggest the old pattern]
**Detection**: [How to spot this in code/config]

应编码的内容

• 框架演进（React Classes → Hooks → Server Components）
• 模型局限性（CLIP 无法计数；嵌入模型因任务而异）
• 工具架构（脚本 → MCP 的进阶路径）
• API 版本管理（ada-002 → text-embedding-3-large）
• 时效性陷阱（在 2023 年正确、但在 2025 年有害的建议）

完整目录及案例研究：参见 references/antipatterns.md

---

自包含工具与扩展分类

Skills 是 Claude 的七种扩展类型之一：Skills（领域知识）、Plugins（用于分发的打包套件）、MCP Servers（外部 API + 身份验证）、Scripts（本地操作）、Slash Commands（由用户触发的技能）、Hooks（在 17 个以上事件点执行的生命周期自动化）和 Agent SDK（以编程方式访问 Claude Code）。大多数技能都应包含脚本。MCP 仅用于身份验证／状态边界。Plugins 用于在团队／社区间共享技能。

需求	扩展类型	关键要求
领域专长／流程	Skill (SKILL.md)	决策树、反模式、输出约定
打包与分发	Plugin (plugin.json)	捆绑 skills + hooks + MCP + agents
外部 API + 身份验证	MCP Server	可运行的服务 + 设置 README
可重复的本地操作	Script	确实可运行（不是模板），依赖项最少
多步骤编排	Subagent	四部分提示词、skills、工作流
用户触发的操作	Slash Command	带有 user-invocable: true 的 Skill
生命周期自动化	Hook	17 个以上事件：PreToolUse、PostToolUse、Stop 等
编程式访问	Agent SDK	npm/pip 包、CI/CD 管道

演进路径：Skill → Skill + Scripts → Skill + MCP Server → Skill + Subagent → Plugin（用于分发）。只有在复杂度足以支撑时才升级。

完整分类与常见错误示例：参见 references/claude-extension-taxonomy.md 详细工具模式：参见 references/self-contained-tools.md Plugin 的创建与分发：参见 references/plugin-architecture.md

---

工具权限

原则：最小权限——仅授予所需权限。

访问级别	allowed-tools
只读	Read,Grep,Glob
文件修改	Read,Write,Edit
构建集成	Read,Write,Bash(npm:*,git:*)
⚠️ 切勿用于不可信对象	不受限制的 Bash

---

反模式摘要

#	反模式	修正方法
1	文档倾倒	在 SKILL.md 中使用决策树，将深入内容放在 /references
2	缺少 NOT 子句	在描述中始终加入“NOT for X, Y, Z”
3	幻影工具	仅引用确实存在且可用的文件
4	模板大杂烩	提供可运行的代码，否则什么都不提供
5	工具权限过宽	最小权限：指定工具列表、限定范围的 Bash
6	过时的时效性知识	为所有建议标注日期，并按季度更新
7	包罗万象的 Skill	按专长类型拆分，而非按领域拆分
8	描述含糊	使用 [内容] [时机] [关键词]。NOT for [排除项]
9	急于加载	切勿“先读取所有文件”；按需延迟加载参考资料
10	仅用文字描述流程	使用 Mermaid 图表（23 种类型）——流程图、时序图、状态图、ER 图、时间线等
11	仅含文本的可视化 Skill	提供 demo/ HTML、assets/ 截图、prompts/ 和程序化构建指南

完整案例研究：参见 references/antipatterns.md

---

验证清单

□ SKILL.md exists and is <500 lines
□ Frontmatter has name + description (minimum required)
□ Description follows [What][When][Keywords] NOT [Exclusions] formula
□ Description uses keywords users would actually type
□ Name and description are aligned (not contradictory)
□ At least 1 anti-pattern with shibboleth template
□ All referenced files actually exist (no phantoms)
□ Scripts work (not templates), have clear CLI, handle errors
□ Reference files each have a 1-line purpose in SKILL.md
□ Processes/decisions/lifecycles use Mermaid diagrams (23 types), not prose
□ CHANGELOG.md tracks version history
□ If subagent-consumed: output contracts are defined
□ If visual/design skill: demo/, assets/, prompts/, templates/ per visual-design-skills.md

运行自动化检查：python scripts/validate_skill.py <path> 和 python scripts/validate_mermaid.py <path>

---

常见拒绝原因

以下情况会导致 Claude Code 在加载时拒绝或错误处理技能：

原因	症状	修复方法
缺少 name 或 description	技能无法加载	在 frontmatter 中添加这两项
使用 tools: 而不是 allowed-tools:	工具会被静默忽略	使用 allowed-tools:（带连字符）
allowed-tools 使用 YAML 列表	解析错误	使用逗号分隔：Read,Write,Edit
allowed-tools 中使用方括号	解析错误	不要使用 [ ]，直接写 Read,Write,Edit
无效键（triggers、outputs）	被静默忽略或报错	移至 SKILL.md 正文
名称包含空格或大写字母	可能无法匹配	使用小写字母和连字符：my-skill-name
名称与目录名不一致	激活不匹配	确保名称与目录名一致
context: 不是 fork	被忽略	唯一有效值是 fork
disable-model-invocation: 不是布尔值	被忽略	使用 true 或 false
引用了不存在的文件	Agent 浪费工具调用	删除引用或创建文件

完整验证：python scripts/validate_skill.py <path> 可捕获上述所有问题。

---

成功指标

指标	目标	衡量方式
正确激活率	>90%	测试应该触发技能的查询
误报率	<5%	测试不应该触发技能的查询
Token 用量	<5k	SKILL.md 大小 + 典型的参考文件加载量
开始有效工作的时间	<5 min	用户立即开始工作
反模式预防率	>80%	用户避免文档中记录的错误

---

参考文件

需要深入了解时，请查阅以下文件——默认不会加载这些文件：

文件	查阅时机
references/knowledge-engineering.md	使用知识工程方法将专家知识提炼为技能；协议分析、语义差异网格、顿悟时刻
references/description-guide.md	编写或重写技能描述
references/antipatterns.md	查找识别标志、案例研究或时间模式
references/self-contained-tools.md	为技能添加脚本、MCP 服务或子 Agent
references/subagent-design.md	设计供子 Agent 使用或编排的技能
references/claude-extension-taxonomy.md	Skills、Plugins、MCPs、Hooks 与 Agent SDK 的对比——7 类分类法
references/plugin-architecture.md	通过 marketplace 创建、打包和分发插件
references/visual-artifacts.md	添加 Mermaid 图表：全部 23 种类型、YAML 配置和最佳实践
references/visual-design-skills.md	设计与创意类技能的要求：演示、资源、截图、提示词、程序化构建、署名
references/mcp-template.md	为技能构建 MCP 服务
references/subagent-template.md	定义子 Agent 提示词和多 Agent 管线
scripts/validate_mermaid.py	验证任意文件中的 Mermaid 语法——检查图表类型、代码块是否配对及结构正确性