| name | write-a-skill |
| description | Agent Skill 编写技能。从需求到完成的标准化工作流：结构设计、frontmatter 配置、references 编写、审查清单。 |
| metadata | {"filePattern":["**/SKILL.md","**/skills/**/*"],"bashPattern":["skill|SKILL|技能"],"priority":7} |
Write-a-Skill
就像写菜谱一样——先确定这道菜解决什么问题（饿了？宴客？减脂？），再列食材清单（references），最后写步骤（workflow）。好菜谱让任何厨师都能复现，好 skill 让任何 agent 都能执行。
When to Activate
以下场景自动激活本技能：
- 用户要创建新的 agent skill
- 用户要修改现有 skill 的结构
- 用户说"写一个技能"、"新建 skill"、"添加技能"
- 编辑
SKILL.md 文件时
Workflow
Phase 1: 需求定义
1.1 明确技能定位
- 这个技能解决什么问题？（一句话）
- 目标用户是谁？（初级/中级/高级开发者）
- 触发场景是什么？（文件操作/bash 命令/用户指令）
1.2 检查重叠
- 查看 Ownership Matrix 确认无重复
- 如果与现有技能有交叉，确定 owner vs reference 关系
- 原则：每个关注点只有一个 owner，其他技能引用
1.3 确定优先级
| 优先级 | 适用场景 | 示例 |
|---|
| 8-9 | 流程入口、架构决策 | prd, planning, auth |
| 6-7 | 核心开发活动 | api-design, database, code-review |
| 4-5 | 实现模式、运维 | backend-patterns, ci-cd, git-workflow |
| 2-3 | 辅助、文档 | documentation, tutorial |
Phase 2: 结构设计
2.1 编写 Frontmatter
---
name: {kebab-case 名称}
description: "{一句话描述，中文}"
metadata:
filePattern:
- "{glob 模式，匹配触发文件}"
bashPattern:
- "{正则模式，匹配触发命令}"
priority: {2-9}
---
规则：
name: kebab-case，与目录名一致description: 用引号包裹，中文，说明技能做什么filePattern: glob 语法（*, **, ?），匹配文件路径触发bashPattern: 正则语法，匹配 bash 命令触发priority: 数字越大越优先注入（最多同时注入 3 个 skill）- 纯对话型技能（如 grill-me、tutorial）可省略 filePattern/bashPattern
2.2 设计 SKILL.md 主体
必须包含的章节（按顺序）：
- 标题 + 类比开头 — 用日常比喻解释技能用途（1-2 句）
- When to Activate — 触发条件列表
- Workflow — 分阶段工作流（Phase 1/2/3...）
- 审查清单 — 质量门禁 checklist
- References 链接 — 指向 references/ 下的文件
2.3 设计 References
- 每个技能 2-4 个 reference 文件
- 文件命名：
{主题}-{类型}.md（如 schema-design.md、review-checklist.md）
- 每个文件 100-300 行，聚焦单一主题
- 包含可直接使用的模板、代码示例、检查清单
Phase 3: 编写内容
3.1 SKILL.md 编写规范
- 类比开头：第一段用日常比喻，让非专家也能理解
- 结论先行：每个章节先给结论，再展开细节
- 中文为主：说明文字用中文，代码/命令用英文
- Workflow 结构：
- 大阶段用
### Phase N: 名称
- 子步骤用
N.1、N.2 编号
- 每步有明确的输入和输出
- 审查清单：用
- [ ] checkbox 格式，覆盖完整性、正确性、一致性
3.2 References 编写规范
- 模板文件用
{占位符} 标记可替换内容
- 代码示例用 TypeScript（除非技能特定于其他语言）
- 表格用于对比和决策矩阵
- 避免重复其他技能已定义的内容，用交叉引用代替
3.3 交叉引用模式
<!-- 引用其他技能的内容 -->
> 统一响应信封格式参见 [api-design](../api-design/SKILL.md)
> 结构化日志标准参见 [observability](../observability/SKILL.md)
Phase 4: 集成
4.1 目录结构
{skill-name}/
├── SKILL.md # 主文件（200-400 行）
└── references/
├── {topic-a}.md # 参考文档 1（100-300 行）
├── {topic-b}.md # 参考文档 2（100-300 行）
└── {topic-c}.md # 参考文档 3（100-300 行）
4.2 更新 README.md
- 在
## Skills (N) 中更新数字
- 按优先级顺序添加技能描述段落
- 如有新的 ownership 关系，更新 Ownership Matrix
4.3 安装验证
head -15 {skill-name}/SKILL.md
cat {skill-name}/references/*.md | wc -l
ls -la ~/.claude/skills/{skill-name}
审查清单
结构审查
内容审查
元数据审查
集成审查
快速参考
现有技能层级
Tier 1 — 发现与规划 (priority 8-9)
prd → planning → grill-me
Tier 2 — 架构与设计 (priority 7-8)
api-design, database, auth, security-review
Tier 3 — 实现 (priority 5-6)
backend-patterns, frontend-patterns, error-handling
code-review, tdd-workflow, e2e-testing
Tier 4 — 运维与横切 (priority 4-5)
git-workflow, ci-cd, coding-standards, observability, performance
Tier 5 — 辅助 (priority 2-3)
documentation, tutorial, write-a-skill
新技能定位决策树
需要新技能吗？
├── 现有技能能覆盖吗？ → 不需要新技能，扩展现有 references
├── 与现有技能 >60% 重叠？ → 合并到现有技能
├── 是全新领域？ → 创建新技能
└── 是现有技能的子领域？ → 作为 reference 文件添加到现有技能
References
