Skill Authoring Workflow
Turn raw PM content into a compliant, publish-ready Claude skill via 6 phases (preflight → generate → tighten → validate → integrate → package) using repo-native scripts.
You wrote a great skill, skipped validation, forgot to update the README counts, and shipped anyway. Now references are broken, catalog numbers are inconsistent, and contributors don't trust the system. The fix isn't more discipline — it's a workflow that bakes in `find-a-skill.sh`, `add-a-skill.sh`, `test-a-skill.sh`, metadata checks, and README updates as steps you can't skip.
Who it's for: Skill contributors to deanpeters/Product-Manager-Skills, plugin authors, repo maintainers, anyone authoring Claude custom skills with strict standards
Example
"Turn workshop notes into a new interactive PM skill" → Phase 1 search for duplicates → Phase 2 `add-a-skill.sh research/notes.md` → Phase 3 manual tighten → Phase 4 `test-a-skill.sh --smoke` + metadata + trigger checks → Phase 5 README catalog update → Phase 6 optional zip for upload
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
npx ccplaybooks add skill-authoring-workflow# Skill Authoring Workflow
Turn raw PM content (workshop notes, half-baked prompts, research dumps) into compliant, publish-ready skills that pass validation. Six-phase workflow for creating or updating skills without breaking standards.
Use it when you want to ship a skill without "looks good to me" roulette.
## Dogfood First
Repo-native tools before custom processes:
- `scripts/find-a-skill.sh` — search existing
- `scripts/add-a-skill.sh` — content-first generator
- `scripts/build-a-skill.sh` — guided wizardGet new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
Six-phase workflow with explicit Definition of Done (frontmatter valid, metadata within limits, cross-references resolve, README counts updated). Uses repo-native scripts at every step instead of inventing custom validation.
Specific to the deanpeters/Product-Manager-Skills repo, but the pattern applies to any structured Claude Skills repo.
Quick Start
mkdir -p ~/Documents/SkillAuthoring
mv ~/Downloads/CLAUDE.md ~/Documents/SkillAuthoring/
cd ~/Documents/SkillAuthoring
claude
Provide source material (workshop notes, prompt drafts, research file path) and target skill type. Claude orchestrates the 6 phases including tool invocations.
The 6 Phases
| Phase | Tool/Action | Output |
|---|---|---|
| 1. Preflight | find-a-skill.sh --keyword |
No duplicate; type chosen |
| 2. Generate Draft | add-a-skill.sh or build-a-skill.sh |
Skill folder created |
| 3. Tighten | Manual review | Clear when-to-use + example + anti-pattern |
| 4. Validate | test-a-skill.sh --smoke + metadata + triggers |
All checks pass |
| 5. Integrate | Update README catalog + counts | Catalog reflects new skill |
| 6. Package | zip-a-skill.sh (optional) |
Upload-ready zip |
Tips & Best Practices
- Search before authoring.
find-a-skill.shsaves you from rebuilding what exists. - Pick
componentfirst.workflowis for true multi-phase orchestration, not "I have several sections." - Description = trigger, not description. Say when Claude should use it, not just what it is.
- 200 chars is hard. Drafts that hit 200 mid-sentence get truncated by uploaders.
- Always run
--smoke. It's the difference between "I think it works" and "the structural checks pass."
Common Pitfalls
- Skipping
find-a-skill.shand duplicating an existing skill - Choosing
workflowfor what's really acomponent - Writing 250-char descriptions that fail upload validation
- Forgetting to update README counts after adding a skill
- Treating
add-a-skill.shoutput as final without manual review