| name | skill-authoring-workflow |
| description | Turn raw PM content into a compliant, publish-ready skill, or design a new skill through guided Q&A that shapes its type, scope, and structure. Enforces THIS repo's conventions and validation gates (generic scaffolding is skill-creator's job). Use when creating or updating a repo skill — even from just an idea or notes. |
| intent | 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. When the user starts from a raw idea rather than finished content, it also runs a guided 5-question design conversation (see references/pm-skill-design.md, absorbed from the retired pm-skill-creator skill) to settle skill type, scope, naming, and structure before drafting. |
| type | workflow |
| best_for | ["Creating a new repo skill from notes or source material","Designing a new skill from a raw idea through guided conversation","Updating an existing skill while keeping standards intact","Running the full authoring and validation workflow before commit"] |
| scenarios | ["Help me turn these workshop notes into a new PM skill","Help me create a new skill — I know the topic but not the structure","I need to update an existing skill without breaking the repo standards","What workflow should I use to author a new skill in this repo?"] |
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.
Where this skill fits: an external plugin already provides a generic skill-creator for scaffolding skills from scratch. This skill's niche is this repo's standards — the PM skill anatomy, metadata limits, catalog integration, and validation gates. For generic skill scaffolding, the skill-creator plugin skill applies; use this skill to meet this repo's conventions and validation gates.
Outputs
Artifact: A compliant, publish-ready skill directory (SKILL.md plus references/) that passes this repo's validation gates
Format: markdown skill files
Location: the skills repo, under the chosen domain directory
Audience: this repo's skill portfolio (Claude Code + Codex consume it via symlinks)
Prerequisites
- Raw source material (notes, prompts, workshop content) or at least an idea to shape
find-skills — check the ecosystem first so you don't author a duplicate
Key Concepts
Dogfood First
Use repo-native tools and standards before inventing a custom process:
scripts/find-a-skill.shscripts/add-a-skill.shscripts/build-a-skill.shscripts/test-a-skill.shscripts/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.
Definition of Done (No Exceptions)
A skill is done only when:
- Frontmatter is valid (
name, description, intent, type)
- Section order is compliant
- Metadata limits are respected (
name <= 64 chars, description <= 200 chars)
- Description says both what the skill does and when to use it
- Intent carries the fuller repo-facing summary without replacing the trigger-oriented description
- Cross-references resolve
- README catalog counts and tables are updated (if adding/removing skills)
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.
Application
Phase 0: Design Through Guided Conversation (When Starting from an Idea)
If the user has a raw idea, framework, or unstructured notes — rather than finished source content — run the guided design session first: read references/pm-skill-design.md. It defines a 5-question adaptive conversation (raw material → skill type → naming/scope → key content → pitfalls) plus the PM skill anatomy and metadata constraints, and ends with a complete SKILL.md draft. Then continue at Phase 1 to check for duplicates and at Phase 4 to validate the draft.
If the user already knows what to build, skip straight to Phase 1.
Phase 1: Preflight (Avoid Duplicate Work)
- Search for overlapping skills:
./scripts/find-a-skill.sh --keyword "<topic>"
- Decide type:
- Component: one artifact/template
- Interactive: 3-5 adaptive questions + numbered options
- Workflow: multi-phase orchestration
Phase 2: Generate Draft
If you have source material:
./scripts/add-a-skill.sh research/your-framework.md
If you want guided prompts:
./scripts/build-a-skill.sh
Phase 3: Tighten the 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
Run strict checks before thinking about commit:
./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
Phase 5: Integrate with Repo Docs
If this is a new skill:
- Add it to the correct README category table
- Update skill totals and category counts
- Verify link paths resolve
Phase 6: Optional Packaging
If targeting Claude custom skill upload:
./scripts/zip-a-skill.sh --skill <skill-name>
./scripts/zip-a-skill.sh --type component --output dist/skill-zips
./scripts/zip-a-skill.sh --preset core-pm --output dist/skill-zips
Examples
Example: Turn Workshop Notes into a Skill
Input: research/pricing-workshop-notes.md
Goal: new interactive advisor
./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
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
Common Pitfalls
- Shipping vibes, not standards.
- Choosing
workflow when the task is really a component template.
- Bloated descriptions that exceed upload limits.
- Descriptions that say what the skill is but not when Claude should trigger it.
- Descriptions that silently hit the 200-char limit and get cut off mid-thought.
- Letting
intent become a substitute for a weak trigger description.
- Forgetting to update README counts after adding a skill.
- Treating generated output as final without review.
Next steps
workshop-facilitation — delegate pacing to it if the new skill is interactive
References
references/pm-skill-design.md — Guided 5-question PM skill-design conversation + PM skill anatomy (absorbed from the retired pm-skill-creator skill)workshop-facilitation — Interaction protocol for the guided phasesREADME.mdAGENTS.mdCLAUDE.mddocs/Building PM Skills.mddocs/Add-a-Skill Utility Guide.md- Anthropic's Complete Guide to Building Skills for Claude
scripts/add-a-skill.shscripts/build-a-skill.shscripts/find-a-skill.shscripts/test-a-skill.shscripts/check-skill-metadata.pyscripts/check-skill-triggers.pyscripts/zip-a-skill.sh
