Back to Details

skill-authoring-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Purpose

目的

Create or update PM skills without chaos. This workflow turns rough notes, workshop content, or half-baked prompt dumps into compliant 
skills/<skill-name>/SKILL.md
assets that actually pass validation and belong in this repo.
Use it when you want to ship a new skill without "looks good to me" roulette.
创建或更新PM Skill，避免混乱。该工作流可将粗略笔记、研讨会内容或半成品提示内容转换为合规的
skills/<skill-name>/SKILL.md
资产，确保其能通过验证并纳入本仓库。
当你希望发布新Skill，而不想靠“我看着没问题”碰运气时，即可使用此工作流。

Key Concepts

核心概念

Dogfood First

优先自用（Dogfood First）

Use repo-native tools and standards before inventing a custom process:
  • 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
在自定义流程之前，优先使用仓库原生工具和标准：
  • 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

Pick the Right Creation Path

选择合适的创建路径

  • Guided wizard (
    build-a-skill.sh
    )    : Best when you have an idea but not final prose.
  • Content-first generator (
    add-a-skill.sh
    )    : Best when you already have source content.
  • Manual edit + validate: Best for tightening an existing skill.
  • 引导式向导（
    build-a-skill.sh
    ）    ：适合已有想法但尚未敲定文案的场景。
  • 内容优先生成器（
    add-a-skill.sh
    ）    ：适合已有源内容的场景。
  • 手动编辑+验证：适合优化现有Skill的场景。

Definition of Done (No Exceptions)

完成标准（无例外）

A skill is done only when:
  1. Frontmatter is valid (
    name
    , 
    description
    , 
    type
    )
  2. Section order is compliant
  3. Metadata limits are respected (
    name
    <= 64 chars, 
    description
    <= 200 chars)
  4. Cross-references resolve
  5. README catalog counts and tables are updated (if adding/removing skills)
只有满足以下所有条件，Skill才算完成：
  1. 前端元数据（
    name
    、
    description
    、
    type
    ）有效
  2. 章节顺序合规
  3. 遵守元数据限制（
    name
    ≤64字符，
    description
    ≤200字符）
  4. 交叉引用可正常解析
  5. README目录的计数和表格已更新（若添加/移除Skill）

Facilitation Source of Truth

研讨会协作的事实标准

When running this workflow as a guided conversation, use 
workshop-facilitation
 as the interaction protocol.
It defines:
  • session heads-up + entry mode (Guided, Context dump, Best guess)
  • one-question turns with plain-language prompts
  • progress labels (for example, Context Qx/8 and Scoring Qx/5)
  • interruption handling and pause/resume behavior
  • numbered recommendations at decision points
  • quick-select numbered response options for regular questions (include 
    Other (specify)
    when useful)
This file defines the workflow sequence and domain-specific outputs. If there is a conflict, follow this file's workflow logic.
当以引导式对话形式运行此工作流时，请将
workshop-facilitation
作为交互协议。
它定义了：
  • 会话提醒+进入模式（引导式、上下文导入、最佳猜测）
  • 采用平实语言的单问题轮询
  • 进度标签（例如，Context Qx/8 和 Scoring Qx/5）
  • 中断处理与暂停/恢复机制
  • 决策点的编号建议
  • 常规问题的快速选择编号响应选项（必要时包含“其他（请说明）”）
本文件定义了工作流序列和特定领域的输出。若存在冲突，请遵循本文件的工作流逻辑。

Application

应用步骤

Phase 1: Preflight (Avoid Duplicate Work)

阶段1：预检（避免重复工作）

  1. Search for overlapping skills:
bash
./scripts/find-a-skill.sh --keyword "<topic>"
  1. Decide type:
  • Component: one artifact/template
  • Interactive: 3-5 adaptive questions + numbered options
  • Workflow: multi-phase orchestration
  1. 搜索是否存在相似Skill：
bash
./scripts/find-a-skill.sh --keyword "<topic>"
  1. 确定Skill类型：
  • Component（组件型）：单个工件/模板
  • Interactive（交互型）：3-5个自适应问题+编号选项
  • Workflow（工作流型）：多阶段编排

Phase 2: Generate Draft

阶段2：生成草稿

If you have source material:
bash
./scripts/add-a-skill.sh research/your-framework.md
If you want guided prompts:
bash
./scripts/build-a-skill.sh
若已有源材料：
bash
./scripts/add-a-skill.sh research/your-framework.md
若需要引导式提示：
bash
./scripts/build-a-skill.sh

Phase 3: Tighten the Skill

阶段3：优化Skill

Manually review for:
  • Clear "when to use" guidance
  • One concrete example
  • One explicit anti-pattern
  • No filler or vague consultant-speak
手动检查以下内容：
  • 清晰的“使用场景”指南
  • 一个具体示例
  • 一个明确的反模式
  • 无冗余内容或模糊的顾问式套话

Phase 4: Validate Hard

阶段4：严格验证

Run strict checks before thinking about commit:
bash
./scripts/test-a-skill.sh --skill <skill-name> --smoke
python3 scripts/check-skill-metadata.py skills/<skill-name>/SKILL.md
在考虑提交前，运行严格检查：
bash
./scripts/test-a-skill.sh --skill <skill-name> --smoke
python3 scripts/check-skill-metadata.py skills/<skill-name>/SKILL.md

Phase 5: Integrate with Repo Docs

阶段5：与仓库文档集成

If this is a new skill:
  1. Add it to the correct README category table
  2. Update skill totals and category counts
  3. Verify link paths resolve
若为新Skill：
  1. 将其添加到README的对应分类表格中
  2. 更新Skill总数和分类计数
  3. 验证链接路径可正常解析

Phase 6: Optional Packaging

阶段6：可选打包

If targeting Claude custom skill upload:
bash
./scripts/zip-a-skill.sh --skill <skill-name>
若目标是上传至Claude自定义Skill：
bash
./scripts/zip-a-skill.sh --skill <skill-name>

or zip one category:

或打包整个分类：

./scripts/zip-a-skill.sh --type component --output dist/skill-zips
./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
undefined
./scripts/zip-a-skill.sh --preset core-pm --output dist/skill-zips
undefined

Examples

示例

Example: Turn Workshop Notes into a Skill

示例：将研讨会笔记转换为Skill

Input: 
research/pricing-workshop-notes.md

Goal: new interactive advisor
bash
./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
Expected result:
  • New skill folder exists
  • Skill passes structural and metadata checks
  • README catalog entry added/updated
输入：
research/pricing-workshop-notes.md

目标：新的交互式顾问Skill
bash
./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
预期结果：
  • 新Skill文件夹已创建
  • Skill通过结构和元数据检查
  • README目录条目已添加/更新

Anti-Pattern Example

反模式示例

"We wrote a cool skill, skipped validation, forgot README counts, and shipped anyway."
Result:
  • Broken references
  • Inconsistent catalog numbers
  • Confusion for contributors and users
“我们写了一个很棒的Skill，跳过了验证，忘记更新README计数，直接发布了。”
结果：
  • 引用失效
  • 目录编号不一致
  • 给贡献者和用户造成困惑

Common Pitfalls

常见陷阱

  • Shipping vibes, not standards.
  • Choosing 
    workflow
    when the task is really a component template.
  • Bloated descriptions that exceed upload limits.
  • Forgetting to update README counts after adding a skill.
  • Treating generated output as final without review.
  • 只追求感觉，不遵守标准。
  • 当任务实际是组件模板时，却选择了
    workflow
    类型。
  • 描述过于冗长，超出上传限制。
  • 添加Skill后忘记更新README计数。
  • 直接将生成的输出作为最终版本，未进行审核。

References

参考资料

  • README.md
  • AGENTS.md
  • CLAUDE.md
  • docs/Building PM Skills.md
  • docs/Add-a-Skill Utility Guide.md
  • 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/zip-a-skill.sh
  • README.md
  • AGENTS.md
  • CLAUDE.md
  • docs/Building PM Skills.md
  • docs/Add-a-Skill Utility Guide.md
  • 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/zip-a-skill.sh