Skill Authoring Workflow
Run the repo’s end-to-end workflow to turn rough PM notes into a validated, standards-compliant SKILL.md without breaking metadata rules.
Overview
Skill Authoring Workflow is an agent skill most often used in Build (also Ship review prep) that turns PM source material into validated, repo-compliant SKILL.md files using native authoring scripts.
Install
npx skills add https://github.com/deanpeters/product-manager-skills --skill skill-authoring-workflowWhat is this skill?
- Full workflow from raw notes, workshops, or prompt dumps to compliant `skills/<skill-name>/SKILL.md`
- Dogfoods repo scripts: find-a-skill, add-a-skill, build-a-skill, test-a-skill, check-skill-metadata.py
- Supports both creating new skills and updating existing ones while keeping validation standards intact
- Explicit intent to avoid ship-by-gut validation before commit
- Guided vs wizard creation paths referenced via build-a-skill tooling
- 5 named repo scripts in the dogfood toolchain (find, add, build, test, check-skill-metadata)
Adoption & trust: 1.1k installs on skills.sh; 5k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have PM notes or an old prompt dump but no reliable path to a SKILL.md that passes repo validation without breaking standards on update.
Who is it for?
Maintainers of the product-manager-skills repo—or similar skill monorepos—who add or revise skills regularly and want a scripted gate before merge.
Skip if: Builders who only need a one-off chat prompt with no SKILL.md structure, validation scripts, or long-lived repo conventions.
When should I use this skill?
Creating or updating a repo skill from raw PM content and you need the full authoring and validation workflow before commit.
What do I get? / Deliverables
You produce a tested, metadata-compliant skill folder ready to commit, after running the repo’s find, build, test, and check scripts.
- Validated SKILL.md under skills/<skill-name>/
- Test run output from repo skill scripts
- Metadata check pass for frontmatter rules
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build/agent-tooling is the canonical shelf because the output is a publish-ready agent skill asset in `skills/<skill-name>/SKILL.md`, not a shipped customer feature. Agent-tooling reflects authoring procedural knowledge for Claude-style agents using native repo scripts rather than generic documentation only.
Where it fits
Turn workshop notes into a new `skills/<name>/SKILL.md` using add-a-skill and build-a-skill scripts.
Refresh an existing skill’s description and frontmatter while re-running check-skill-metadata.py.
Run test-a-skill and metadata checks so a PR reviewer sees compliance evidence, not ad-hoc formatting fixes.
How it compares
Repo-native skill factory workflow—not a generic markdown linter or marketplace packaging skill.
Common Questions / FAQ
Who is skill-authoring-workflow for?
PMs and repo maintainers authoring agent skills who must match this repository’s SKILL.md layout and pass automated metadata checks.
When should I use skill-authoring-workflow?
Use it in Build/agent-tooling when creating or updating a skill from notes, and in Ship/review when you need validation evidence before opening a PR for a new skill.
Is skill-authoring-workflow safe to install?
Review the Security Audits panel on this Prism page; local scripts may run shell and Python checks—inspect script behavior in your fork before executing in CI.
SKILL.md
READMESKILL.md - Skill Authoring Workflow
## 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. ## Key Concepts ### 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` ### 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: 1. Frontmatter is valid (`name`, `description`, `intent`, `type`) 2. Section order is compliant 3. Metadata limits are respected (`name` <= 64 chars, `description` <= 200 chars) 4. Description says both what the skill does and when to use it 5. Intent carries the fuller repo-facing summary without replacing the trigger-oriented description 6. Cross-references resolve 7. 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`](../workshop-facilitation/SKILL.md) 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 1: Preflight (Avoid Duplicate Work) 1. Search for overlapping skills: ```bash ./scripts/find-a-skill.sh --keyword "<topic>" ``` 2. 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: ```bash ./scripts/add-a-skill.sh research/your-framework.md ``` If you want guided prompts: ```bash ./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: ```bash ./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: 1. Add it to the