Skill Authoring Workflow

1---2name: skill-authoring-workflow3description: Turn raw PM content into a compliant, publish-ready skill. Use when creating or updating a repo skill without breaking standards.4intent: >-5  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.6type: workflow7best_for:8  - "Creating a new repo skill from notes or source material"9  - "Updating an existing skill while keeping standards intact"10  - "Running the full authoring and validation workflow before commit"11scenarios:12  - "Help me turn these workshop notes into a new PM skill"13  - "I need to update an existing skill without breaking the repo standards"14  - "What workflow should I use to author a new skill in this repo?"15---16 17## Purpose18 19Create 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.20 21Use it when you want to ship a new skill without "looks good to me" roulette.22 23## Key Concepts24 25### Dogfood First26 27Use repo-native tools and standards before inventing a custom process:28- `scripts/find-a-skill.sh`29- `scripts/add-a-skill.sh`30- `scripts/build-a-skill.sh`31- `scripts/test-a-skill.sh`32- `scripts/check-skill-metadata.py`33 34### Pick the Right Creation Path35 36- **Guided wizard (`build-a-skill.sh`)**: Best when you have an idea but not final prose.37- **Content-first generator (`add-a-skill.sh`)**: Best when you already have source content.38- **Manual edit + validate**: Best for tightening an existing skill.39 40### Definition of Done (No Exceptions)41 42A skill is done only when:431. Frontmatter is valid (`name`, `description`, `intent`, `type`)442. Section order is compliant453. Metadata limits are respected (`name` <= 64 chars, `description` <= 200 chars)464. Description says both what the skill does and when to use it475. Intent carries the fuller repo-facing summary without replacing the trigger-oriented description486. Cross-references resolve497. README catalog counts and tables are updated (if adding/removing skills)50 51### Facilitation Source of Truth52 53When running this workflow as a guided conversation, use [`workshop-facilitation`](../workshop-facilitation/SKILL.md) as the interaction protocol.54 55It defines:56- session heads-up + entry mode (Guided, Context dump, Best guess)57- one-question turns with plain-language prompts58- progress labels (for example, Context Qx/8 and Scoring Qx/5)59- interruption handling and pause/resume behavior60- numbered recommendations at decision points61- quick-select numbered response options for regular questions (include `Other (specify)` when useful)62 63This file defines the workflow sequence and domain-specific outputs. If there is a conflict, follow this file's workflow logic.64 65## Application66 67### Phase 1: Preflight (Avoid Duplicate Work)68 691. Search for overlapping skills:70 71```bash72./scripts/find-a-skill.sh --keyword "<topic>"73```74 752. Decide type:76- **Component**: one artifact/template77- **Interactive**: 3-5 adaptive questions + numbered options78- **Workflow**: multi-phase orchestration79 80### Phase 2: Generate Draft81 82If you have source material:83 84```bash85./scripts/add-a-skill.sh research/your-framework.md86```87 88If you want guided prompts:89 90```bash91./scripts/build-a-skill.sh92```93 94### Phase 3: Tighten the Skill95 96Manually review for:97- Clear "when to use" guidance98- One concrete example99- One explicit anti-pattern100- No filler or vague consultant-speak101 102### Phase 4: Validate Hard103 104Run strict checks before thinking about commit:105 106```bash107./scripts/test-a-skill.sh --skill <skill-name> --smoke108python3 scripts/check-skill-metadata.py skills/<skill-name>/SKILL.md109python3 scripts/check-skill-triggers.py skills/<skill-name>/SKILL.md --show-cases110```111 112### Phase 5: Integrate with Repo Docs113 114If this is a new skill:1151. Add it to the correct README category table1162. Update skill totals and category counts1173. Verify link paths resolve118 119### Phase 6: Optional Packaging120 121If targeting Claude custom skill upload:122 123```bash124./scripts/zip-a-skill.sh --skill <skill-name>125# or zip one category:126./scripts/zip-a-skill.sh --type component --output dist/skill-zips127# or use a curated starter preset:128./scripts/zip-a-skill.sh --preset core-pm --output dist/skill-zips129```130 131## Examples132 133### Example: Turn Workshop Notes into a Skill134 135Input: `research/pricing-workshop-notes.md`  136Goal: new interactive advisor137 138```bash139./scripts/add-a-skill.sh research/pricing-workshop-notes.md140./scripts/test-a-skill.sh --skill <new-skill-name> --smoke141python3 scripts/check-skill-metadata.py skills/<new-skill-name>/SKILL.md142```143 144Expected result:145- New skill folder exists146- Skill passes structural and metadata checks147- README catalog entry added/updated148 149### Anti-Pattern Example150 151"We wrote a cool skill, skipped validation, forgot README counts, and shipped anyway."152 153Result:154- Broken references155- Inconsistent catalog numbers156- Confusion for contributors and users157 158## Common Pitfalls159 160- Shipping vibes, not standards.161- Choosing `workflow` when the task is really a component template.162- Bloated descriptions that exceed upload limits.163- Descriptions that say what the skill is but not when Claude should trigger it.164- Descriptions that silently hit the 200-char limit and get cut off mid-thought.165- Letting `intent` become a substitute for a weak trigger description.166- Forgetting to update README counts after adding a skill.167- Treating generated output as final without review.168 169## References170 171- `README.md`172- `AGENTS.md`173- `CLAUDE.md`174- `docs/Building PM Skills.md`175- `docs/Add-a-Skill Utility Guide.md`176- Anthropic's [Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)177- `scripts/add-a-skill.sh`178- `scripts/build-a-skill.sh`179- `scripts/find-a-skill.sh`180- `scripts/test-a-skill.sh`181- `scripts/check-skill-metadata.py`182- `scripts/check-skill-triggers.py`183- `scripts/zip-a-skill.sh`