claude-code-skills-reference/skill-creator/references/skill-development-methodology.md

Skill Development Methodology

综合 Anthropic 官方最佳实践、skill-creator 工作流、社区经验和实战教训的完整方法论。

本文档只包含 SKILL.md 中没有覆盖的内容。SKILL.md 已经详细描述的流程（Prior Art 8 渠道表、决策矩阵、Inline vs Fork、测试用例格式、描述优化循环等）不在此重复——请直接参考 SKILL.md 对应章节。

Phase 1: 先手动解决问题，不要上来就建 skill

SKILL.md 的 "Capture Intent" 章节覆盖了意图收集的 4 个问题和 skill 类型分类。本节补充一个被忽略的前置步骤：

不要一开始就写 skill。 先用 Claude Code 正常解决用户的问题，在过程中积累经验——哪些方案有效、哪些失败、最终的 working solution 是什么。如果你没有亲自失败过，你写不出能防止别人失败的 skill。

很多 skill 都是从"把我们刚做的变成一个 skill"中诞生的。先从对话历史中提取已验证的模式（SKILL.md "Capture Intent" 第三段已提及），然后才开始规划 skill 结构。

Phase 2: 用 Agent Team 做并行调研

SKILL.md 的 "Prior Art Research" 章节覆盖了 8 个搜索渠道、clone-and-verify 检查清单、和 Adopt/Extend/Build 决策矩阵。本节补充 SKILL.md 未提及的并行调研模式：

遇到不确定的技术方案时，不要串行尝试（太慢），也不要凭经验猜（太危险）。同时启动 3+ 个研究 agent，每个负责一个调研方向：

Agent	职责	搜索范围
工具调研	找已有成熟工具	GitHub stars、npm/PyPI、社区 skill 注册表
API 调研	找可用 API 端点	官方文档、逆向工程、移动端 API
约束调研	理解技术限制	反爬机制、认证要求、平台限制

每个 agent 必须独立验证（读源码、确认 API 可达、检查最近提交日期），不能只看 README。

案例：开发一个数据导出 skill 时，3 个 agent 并行跑了 5-20 分钟，分别发现：一个关键工具当前版本 broken（605 stars 但 PR 待合并）、一个未公开的移动端 API（唯一可行方案）、目标平台升级了 PoW 反爬（所有 HTTP 抓取失效）。没有并行研究，这些信息需要串行试错 3+ 小时才能获得。

Phase 3: 用真实数据验证原型

SKILL.md 的 Evaluation-Driven Development 流程覆盖了"先跑 baseline → 建 eval → 迭代"的过程。本节补充两个 SKILL.md 未强调的验证原则：

3.1 数据完整性验证

"it runs without errors" ≠ "it exported all items correctly"。必须：

• 对比 API 报告的 total 和实际导出行数
• 检查字段格式（评分、日期、编码是否符合预期）
• 用不同规模的数据测试（0 条、100 条、1000+ 条）

常见静默 bug：

• 分页逻辑：某些页面返回的数据量少于请求值（如请求 50 条返回 48 条），被误判为最后一页导致提前终止。修复：检查 total 而非 page_size
• 数据转换：API 返回 {value: 2, max: 5} 表示 2/5 星，但代码按 max: 10 处理后变成 1 星。修复：检查 max 字段确定 scale

3.2 记录失败

详细记录每个失败方案的方法、失败模式、根因。这些将成为 skill 中 "Do NOT attempt" 部分的内容——这是 skill 最独特的价值，防止未来的 agent 重走弯路。

失败记录的结构：

方案	结果	根因
方案名称	具体失败表现（HTTP 状态码、错误信息）	架构层面的原因分析

Phase 4: Skill 写作补充原则

SKILL.md 的 "Skill Writing Guide" 已覆盖 frontmatter、progressive disclosure、bundled resources、命名规范等。本节补充 SKILL.md 未提及的内容层面原则：

4.1 写清楚 skill 不能做什么

防止 agent 尝试不可能的操作。例如：

• "Cannot export reviews (长评) — different API endpoint, not implemented"
• "Cannot filter by single category — exports all 4 types together"

4.2 写清楚失败过什么

在 SKILL.md 或 references 中保留失败方案的摘要（详见 Phase 3.2），加上明确的"Do NOT attempt"警告。这比正面指令更有效——agent 看到 7 种方案的失败记录后，不会尝试第 8 种类似方案。

4.3 安全说明

如果脚本包含 API key、HMAC 密钥或其他凭据，必须解释来源和安全性。例如："These are the app's public credentials extracted from the APK, shared by all users. No personal credentials are used."

4.4 Console output 示例

展示一次成功运行的完整控制台输出。让 agent 知道"正确运行"长什么样，方便验证（SKILL.md Phase 5 的 self-verification）。

4.5 脚本健壮性

SKILL.md 的 "Solve, don't punt" 覆盖了基本错误处理。补充实战中发现的常见遗漏：

• 只捕获 HTTPError，遗漏 URLError / socket.timeout / JSONDecodeError
• 无限分页循环（API 异常时）——需要 max-page 安全阀
• CSV 中的换行符/回车符——csvEscape 必须处理 \r
• 用户输入是完整 URL 而非 ID——脚本应自动提取

Phase 5: 测试迭代补充

SKILL.md 的测试流程非常详细（A/B 测试、断言、评分、viewer）。本节补充两个 SKILL.md 未覆盖的实操教训：

5.1 删除竞争的旧 skill

如果系统中存在旧版 skill（关键词冲突），eval agent 会被旧 skill 截胡，导致测试结果完全无效。必须在测试前删除旧 skill。

信号：eval agent 使用了不同于预期的脚本或方法 → 检查是否有同名/同领域的旧 skill 被加载。

5.2 量化迭代对比

SKILL.md 提到 timing.json 和 benchmark，但未给出具体应跟踪哪些指标。推荐：

指标	为什么重要
数据完整性（实际/预期）	核心正确性
执行时间	用户体验
Token 消耗	成本
工具调用次数	skill 引导效率——次数越少说明 skill 的指令越清晰
错误数	必须为 0

案例对比：某 skill 迭代后，工具调用从 31 次降到 8 次（74% 减少）、Token 从 72K 降到 41K（43% 减少），说明 skill 的指令让 agent 不再需要自己摸索。

Phase 6: Counter Review — 用 Agent Team 做对抗性审查

这是 SKILL.md 未覆盖的独立环节。SKILL.md 的 "Improving the skill" 章节关注用户反馈驱动的迭代，但没有系统化的多视角审查流程。

6.1 第一轮：3 个视角并行

用 Task 工具同时启动 3 个 review agent：

Reviewer	视角	关注点
Skill 质量	对标 Anthropic 最佳实践	描述质量、简洁性、progressive disclosure、可操作性、错误预防、示例、术语一致性
代码健壮性	高级工程师找 bug	错误处理、安全性、跨平台、边界情况、依赖、幂等性
用户视角	首次使用者体验	首次成功率、输入容错、输出预期、隐私顾虑、失败恢复

6.2 修复后 Final Gate

修复所有 Critical 和 HIGH 问题后，再启动 final gate reviewers 验证修复正确性。评分 >= 8 才放行。

6.3 常见发现模式

根据实战经验，reviewer 经常发现的问题类型：

• SKILL.md 和 references 内容重复（每次都会犯，包括本文档自己）
• 异常类型遗漏（只捕获 HTTPError，漏掉 URLError/socket.timeout）
• substring 误匹配（content.includes(url) 导致 /1234/ 匹配 /12345/）
• docstring 与实际行为不一致（写了 "4.5 → 5" 但实际行为是 "4.5 → 4"）
• 误导性注释（注释说"每个分类写入后立即保存"但代码在最后才写入）
• 时间敏感数据（特定日期的测试结果、版本号——下周就过时了）

Phase 7 & 8: Description Optimization + Packaging

SKILL.md 已完整覆盖描述优化循环（20 个 eval query、60/40 train/test split、5 轮迭代）和打包流程（prerequisites、security scan、marketplace.json）。无补充。

来源

来源	本文档引用的独有贡献
Anthropic Official	Evaluation-driven development、conciseness imperative（已由 SKILL.md 覆盖，本文不重复）
skill-creator SKILL.md	完整工作流和工具链（本文引用但不复制，请直接参考 SKILL.md）
社区经验	激活率数据（20%→90%）、Encoded Preference > Capability Uplift
实战教训	并行研究 agent、失败记录的价值、竞争 skill 删除、量化迭代对比、Counter Review 流程