@deanpeters/skill-authoring-workflow

---
name: skill-authoring-workflow
description: Turn raw PM content into a compliant, publish-ready skill. Use when creating or updating a repo skill without breaking standards.
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.
type: workflow
best_for:
  - "Creating a new repo skill from notes or source material"
  - "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"
  - "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.

## 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 correct README category table
2. Update skill totals and category counts
3. Verify link paths resolve

### Phase 6: Optional Packaging

If targeting Claude custom skill upload:

```bash
./scripts/zip-a-skill.sh --skill <skill-name>
# or zip one category:
./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
```

## Examples

### Example: Turn Workshop Notes into a 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

### 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.

## References

- `README.md`
- `AGENTS.md`
- `CLAUDE.md`
- `docs/Building PM Skills.md`
- `docs/Add-a-Skill Utility Guide.md`
- Anthropic's [Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)
- `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/check-skill-triggers.py`
- `scripts/zip-a-skill.sh`