skill-authoring-workflow

目的

创建或更新 PM 技能，避免混乱。此工作流会将粗略笔记、研讨会内容或不成熟的提示词整理成符合要求的 skills/<skill-name>/SKILL.md 资源，使其通过验证并适用于此仓库。

如果你想发布新技能，又不想靠“我觉得没问题”的运气来决定是否合格，就使用此工作流。

输入

提供原始材料和意图即可——内容粗略也没关系；此工作流会帮你完善：

• **最适合提供：**源内容（笔记、转录稿、框架、提示词序列），或你想更新的现有技能
• **也有帮助：**预期技能类型（component/interactive/workflow）、目标受众，以及命名偏好

如果你在请求中直接提供这些信息（例如，“将 research/pricing-workshop-notes.md 转换为交互式定价顾问”），工作流会结合这些上下文从阶段 1 开始——不会再次询问你已经提供的信息。如果你什么都没提供，工作流会先询问你想将什么内容转换为技能，并根据引导流程提供可选的切入方式。

示例：Use skill-authoring-workflow: convert research/pricing-workshop-notes.md into an interactive pricing advisor.

关键概念

优先使用仓库现有工具

优先使用仓库原生工具和标准，不要另创流程：

• scripts/find-a-skill.sh
• scripts/add-a-skill.sh
• scripts/build-a-skill.sh
• scripts/test-a-skill.sh
• scripts/check-skill-metadata.py

选择合适的创建路径

• 引导式向导（build-a-skill.sh）：适合已有想法但尚未准备好最终文案的情况。
• 内容优先生成器（add-a-skill.sh）：适合已经有源内容的情况。
• 手动编辑 + 验证：适合完善现有技能。

完成标准（没有例外）

只有满足以下所有条件，技能才算完成：

1. Frontmatter 有效（name、description、intent、type）
2. 章节顺序符合要求（Purpose、Input、Key Concepts、Application、Examples、Common Pitfalls、References）
3. 符合元数据长度限制（name 最多 64 个字符，description 最多 200 个字符）
4. Description 同时说明技能的功能和适用时机
5. Input 章节说明用户可以提供什么，展示调用示例，告诉 Agent 使用行内输入而不是重新询问，并明确说明用户只提供部分信息或完全不提供信息也没关系——使用通俗语言，绝不要使用 $ARGUMENTS 这类运行时模板语法（理由：CONTRIBUTING.md，“Why We Don't Use $ARGUMENTS”）
6. Intent 提供更完整的面向仓库的摘要，且不能取代以触发条件为导向的 description
7. 交叉引用有效
8. 如果添加或移除技能，则更新 README 目录中的数量和表格

引导流程的权威规范

将此工作流作为引导式对话运行时，请使用 workshop-facilitation 作为交互协议。

它规定了：

• 会话预告 + 切入方式（Guided、Context dump、Best guess）
• 每轮一个问题，并使用通俗易懂的提示
• 进度标签（例如 Context Qx/8 和 Scoring Qx/5）
• 中断处理及暂停/恢复行为
• 在决策点提供编号建议
• 常规问题提供编号快速选择项（适用时包含 Other (specify)）

此文件规定工作流顺序和特定领域的输出。如有冲突，遵循此文件的工作流逻辑。

应用

阶段 1：预检（避免重复劳动）

1. 搜索是否存在重叠技能：

./scripts/find-a-skill.sh --keyword "<topic>"

2. 确定类型：

• Component：单个资源/模板
• Interactive：3-5 个自适应问题 + 编号选项
• Workflow：多阶段编排

阶段 2：生成草稿

如果你有源材料：

./scripts/add-a-skill.sh research/your-framework.md

如果你希望获得引导式提示：

./scripts/build-a-skill.sh

第 3 阶段：打磨技能

手动检查以下内容：

• 明确的“何时使用”指导
• 一个具体示例——最好有两个，且来自不同业务领域（一个 SaaS，一个工业/非 SaaS），以清楚展示框架的通用性；复用仓库中的虚构世界（SaaS 使用 Fieldlight/Wrenchline，工业使用 Helix/Northfield/Corvid），并为第二个文件添加领域后缀（sample-industrial.md）
• 如果技能会生成成品，则提供 template.md——可复制粘贴并填写的输出架构，附带质量检查项
• 一个明确的反模式
• 不要填充无关内容或使用含糊的顾问式行话

第 4 阶段：严格验证

在考虑提交之前，先运行严格检查：

./scripts/test-a-skill.sh --skill <skill-name> --smoke
python3 scripts/check-skill-metadata.py skills/<skill-name>/SKILL.md
python3 scripts/check-skill-triggers.py skills/<skill-name>/SKILL.md --show-cases

第 5 阶段：整合到仓库文档中

如果这是一个新技能：

1. 将其添加到 README 的正确分类表中
2. 更新技能总数和分类数量
3. 验证链接路径有效

第 6 阶段：可选打包

如果目标是上传到 Claude 自定义技能：

./scripts/zip-a-skill.sh --skill <skill-name>
# or zip one category:
./scripts/zip-a-skill.sh --type component --output dist/skill-zips
# or use a curated starter preset:
./scripts/zip-a-skill.sh --preset core-pm --output dist/skill-zips

示例

示例：将研讨会笔记转化为技能

输入：research/pricing-workshop-notes.md
目标：新的交互式顾问

./scripts/add-a-skill.sh research/pricing-workshop-notes.md
./scripts/test-a-skill.sh --skill <new-skill-name> --smoke
python3 scripts/check-skill-metadata.py skills/<new-skill-name>/SKILL.md

预期结果：

• 新技能文件夹已创建
• 技能通过结构和元数据检查
• README 目录条目已添加/更新

反模式示例

“我们写了个很棒的技能，跳过了验证，忘了更新 README 计数，还是直接发布了。”

结果：

• 引用失效
• 目录数字不一致
• 贡献者和用户困惑

常见问题

• 只追求感觉，不遵循标准。
• 任务实际需要的是组件模板，却选择了 workflow。
• 描述过于冗长，超过上传限制。
• 描述说明了技能是什么，却没说明 Claude 应在何时触发它。
• 描述悄然达到 200 个字符的限制，导致内容被截断在句中。
• 让 intent 取代薄弱的触发描述。
• 添加技能后忘记更新 README 计数。
• 未经审核就将生成的输出当作最终结果。

参考资料

• README.md
• AGENTS.md
• CLAUDE.md
• docs/Building PM Skills.md
• docs/Add-a-Skill Utility Guide.md
• Anthropic 的Claude 技能构建完整指南
• scripts/add-a-skill.sh
• scripts/build-a-skill.sh
• scripts/find-a-skill.sh
• scripts/test-a-skill.sh
• scripts/check-skill-metadata.py
• scripts/check-skill-triggers.py
• scripts/zip-a-skill.sh