基于 Anthropic 官方最佳实践和 product-requirement-craft 项目实战经验，总结创建高质量 Claude Skill 的核心技巧。
基于 Anthropic 官方最佳实践和 product-requirement-craft 项目实战经验总结。
Anthropic 最强调的原则。Skill 内容分三层加载：
第一层：元数据（始终在 context 中，~100 tokens）
只有 name + description
Claude 用它判断是否激活这个 skill 第二层：SKILL.md** body**（触发后加载）
保持在 500 行以内，理想 150-200 行
只放工作流程、决策逻辑、文件加载规则 第三层：references/ 文件（按需加载）
模板、示例、详细指南放在独立文件中
Claude 只读当前任务需要的文件
引用保持一层深度，不嵌套
实战： product-requirement-craft 有 3 个模板文件，用户选生成 PRD 时 Claude 只加载 prd-template.md，不浪费 token 去读另外两个。
Claude 倾向于 undertrigger（该用的时候不用），所以 description 要偏 aggressive。
规则：
description: >
Guides users through structured requirements gathering to generate
Problem Framing, SRD, and PRD documents. Use when users mention:
PRD, SRD, problem framing, requirement doc. Also triggers for
"new feature idea" or "define the problem".
差的例子：
description: Helps with documents
官方原则："Claude is already very smart"。每写一句话都问自己：Claude 需要我告诉它这个吗？
要写的：
你的框架特有的结构和字段定义
特定的评分标准、决策逻辑
文档间的递进关系 不要写的：
"用自然的对话语气提问" — Claude 默认就会
"每轮不超过 2 个问题" — Claude 默认就会控制
"PDF 是一种常见的文件格式" — Claude 当然知道
实战： 初版 SKILL.md 有 400 行，review 后砍到 130 行，砍掉的全是 Claude 已知的通用指导。
用祈使句下达指令，解释为什么重要（而非堆砌 MUST）。
❌ 描述性：
"通过多轮对话收集信息。每轮聚焦 1-2 个主题，
避免一次性抛出过多问题让用户疲劳。"
✅ 祈使句 + why：
"Collect information through layered questioning —
this prevents overwhelm and produces higher quality inputs:
1. Start with problem essence
2. Narrow to solution direction
3. Close with success definition"
根据任务脆弱性调整指令精确度：
| 自由度 | 适用场景 | 示例 |
|---|---|---|
| 高（文字指引） | 多种方式都对的任务 | 代码分析、需求提问 |
| 中（模板+参数） | 有首选方式但允许变化 | 文档模板结构 |
| 低（精确脚本） | 出错后果严重 | 数据库迁移、文件格式输出 |
实战： 提问过程用高自由度，模板结构用中等自由度，文档输出格式用低自由度。
官方最推荐的质量提升模式。
收集信息 → 完整度评分 → 有红灯？→ 追问 → 重新评分 → 生成
↑________________|
实战： 红绿灯评分系统 — 🔴 强制追问、🟡 提示可选补充、🟢 直接生成。
交互式 skill（多轮对话）的隐藏问题：对话变长后 SKILL.md 指令会被推远，Claude 可能遗忘模板结构。
解决方案： 关键步骤前加"重新读取"指令：
## Phase 5: Generate document
Critical: Before generating, re-read the relevant template file.
复杂任务用 checklist 追踪进度：
- [ ] Phase 1: Confirm document type
- [ ] Phase 2: Layered questioning
- [ ] Phase 3: Identify project type
- [ ] Phase 4: Completeness scoring
- [ ] Phase 5: Generate document
- [ ] Phase 6: Review + retrospective
注意不要过多 — 6 个 phase 比 8 个更好。循环步骤（迭代修改）放在 checklist 外面。
同一个 skill 在不同环境下行为需要微调：
| 环境 | 特点 | 适配 |
|---|---|---|
| Claude.ai | 有文件系统，无持久化 | 输出在对话中展示 |
| Claude Code | 有文件系统 + 持久化 | 可写入文件持久保存 |
| Cursor | 类似 Claude Code | 同上 |
在 agents.md 或 CLAUDE.md 中加入两条全局行为规则，可以显著提升所有 skill 的效果：
规则 1：模棱两可时列出所有可能性
每一次指令你觉得模棱两可，你都要指出来所有的可能性，并且让我做选择以后再开始行动。
规则 2：复盘时自我提升
每一次说复盘，你都要调用自我提升 skill，并且把 review 记录到对应的记忆文档里面。
这两条放在 agents.md 里作为全局规则，对所有 skill 生效。单个 skill 内部可以加轻量版的复盘机制（如 product-requirement-craft 的 Phase 6），但全局的 self-improving 逻辑不应该塞进某一个 skill。
不要一上来就写 SKILL.md。先和用户（或自己）充分讨论：
实战： product-requirement-craft 在动手写代码之前，经历了框架定义 → 三份文档对比 → 遗漏分析 → 项目类型适配 → 优化方案 → review 优化方案，6 轮讨论后才开始实施。
上传团队实际使用的 PRD/SRD 文档，让 Claude 分析其结构，提取通用模式。比自己凭空想模板质量高得多。
写完初版后，用官方最佳实践逐项审查：
如果 skill 需要处理多种场景，用明确的决策树而不是靠感觉判断：
用户描述 → 提到多页面？→ 跨页面流程
→ 提到多用户群？→ 分群差异化
→ 提到改版/分期？→ 整体优化
→ 都不是？→ 标准模式
.skill 文件（zip 格式），上传到 Settings → Customize → Skills~/.claude/skills/ 或 .claude/skills/写完一个 skill 后逐项检查：