# Workflow: Create Skill

**Model tier**: Haiku (research/scaffold), Sonnet (processing/content), Opus (synthesis), Haiku (cleanup)

## When to use

- Creating a new skill for a project or plugin
- The skill doesn't exist yet or needs to be rebuilt from scratch

## Before you start

If concept unclear, brainstorm: `references/brainstorming/workflow.md`

## Inputs required

- **target_location** - `.claude/skills/<skill-name>/` (project) or `<plugin-path>/skills/<skill-name>/` (plugin)
- **skill_name** - kebab-case
- **skill_purpose** - What problem this solves
- **initial_workflows** - At least one task to handle

## Task document

Create: `.claude/plugin-data/skill-architect/tasks/new-skill-<skill-name>-<date>.md`
All subagents append to this.

---

## Pattern consideration

See `references/tool-patterns/catalog.md`.

| Question | If Yes |
|----------|--------|
| Will skill make design decisions? | Include brainstorming triggers |
| Will skill modify files? | Include verification step |
| Will skill create files in user projects? | Follow [plugin-data-convention](../references/conventions/plugin-data-convention.md) |
| Will skill need maintenance/auditing? | Create reversion protection scaffolding |
| Will skill orchestrate 2+ subagent workflows with synthesis? | Use [Role-Workflow pattern](../references/tool-patterns/role-workflow-pattern.md) |

---

## Phases

### Phase 1: Research (Haiku)

**Objective:** Gather requirements, validate inputs, design structure, scaffold files.

**Read:**
- `${CLAUDE_PLUGIN_ROOT}/references/layout/reference.md`
- `references/tool-patterns/deterministic-scripting.md`
- `${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`

**Do:**
1. Clarify with user: skill purpose, major workflows, knowledge domains
2. Map workflows to `workflows/*.md`
3. Map knowledge domains to `references/` subdirs
4. Identify scripting opportunities (mechanical, repeatable, unambiguous?)
5. Identify scripts vs templates vs knowledge docs
6. Write to task doc: `## Domain Understanding`, `## Proposed Structure`, `## Script Candidates`
7. Confirm with user (checkpoint)
8. Scaffold skill directory tree by hand, following
   `${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`:
   - Omit `target-dir` or use "project" for `.claude/skills/<skill-name>/`
   - Create: `SKILL.md` (empty stub), `workflows/`, `references/`, and
     `templates/`/`scripts/` if the skill needs them
   - Create empty `reference.md` in each references subdir
   - Reversion protection: `invariants.md` (stub), `examples/golden/`, `.decisions/`
9. Write to task doc: `## Scaffolded Files`

**Invariants stub:**
```markdown
# Invariants
Behaviors that must not change without explicit human approval.
> TODO: Fill after skill stabilizes (2-3 uses). See `references/tool-patterns/reversion-protection.md`.
## Critical Invariants
- [To be defined]
## Structural Invariants
- [To be defined]
```

**Outputs:** Task document with domain understanding, structure plan, scaffolded files.

---

### Phase 2: Processing (Sonnet)

**Objective:** Write workflows, reference.md files, knowledge docs, scripts, and templates.

**Read:**
- Task document (all sections from Phase 1)
- `${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`
- `references/progressive-disclosure/reference-md-pattern.md`

**Do:**
1. Write workflows:
   - One `workflows/<workflow-name>.md` per workflow
   - Include: when to use, inputs, subtasks with subagent hints, task doc instructions
   - Pattern hooks: brainstorming reference (if design decisions), verification step (if modifies files)
   - Write to task doc: `## Workflows Written`

2. Write reference.md files:
   - For each references subdir: write `reference.md`
   - Include: purpose, what's here, when to read which file, model hints
   - Stub knowledge docs
   - Write to task doc: `## Reference.md Files Created`

3. Fill knowledge docs:
   - Write each knowledge doc, <=150 lines
   - If longer, split and update parent `reference.md`
   - May require user input for domain expertise
   - Write to task doc: `## Knowledge Docs Written`

4. Create scripts and templates:
   - Write scripts for mechanical tasks
   - Write templates for repetitive structures
   - Make scripts executable
   - Write to task doc: `## Scripts and Templates Created`

**Outputs:** Complete workflow files, reference.md navigation, knowledge docs, scripts, templates.

---

### Phase 3: Synthesis (Opus + Haiku cleanup)

**Objective:** Write SKILL.md, validate, generate description, final review.

**Subagent:** Opus for decisions, then Haiku for cleanup.

**Read:**
- Task document (complete)
- `${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`
- All created workflow files (spot-check)

**Do (Opus):**
1. **Inline vs Reference decision:**
   - Count workflow content lines (exclude blanks, frontmatter, headings)
   - Threshold: <=40 (inline full), 41-100 (inline checklist + reference), >100 (reference only)
   - Multiple workflows -> router pattern
2. Generate description via the `generate-description` workflow
   (`${CLAUDE_PLUGIN_ROOT}/workflows/generate-description.md`):
   - Input: type=skill, name, purpose, triggers
3. Write `SKILL.md` with description, applying inline vs reference decision
4. Write to task doc: `## SKILL.md Structure Decision`
5. Validate against `${CLAUDE_PLUGIN_ROOT}/templates/audit-checklist-template.md`
   (Skill-Specific Attributes section)
6. Fix validation errors
7. Verify structure matches plan
8. Verify `reference.md` files accurate
9. Friction? Add to task doc: `## Friction / Improvement Notes`
10. Write final summary

**Do (Haiku cleanup):**
1. Remove task document artifacts
2. Verify all placeholder text filled
3. Final file permissions check (scripts executable)

**Outputs:** Complete, validated skill with SKILL.md, ready for use.