# Workflow: Add Skill to Plugin

Add a new skill to an existing plugin.

## Who should do this work

| Phase | Model | Why |
|-------|-------|-----|
| Research | Haiku | File gathering, scaffolding |
| Processing | Sonnet | Content drafting, analysis |
| Synthesis | Opus | Quality review, final decisions |
| Cleanup | Haiku | Mechanical file operations |

## When to use

- Adding skill to existing plugin
- Skill doesn't exist or needs rebuild

## Before you start

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

## Inputs required

- **plugin_path** - Where plugin lives (or "create new plugin first")
- **skill_name** - kebab-case
- **skill_purpose** - Problem this solves
- **initial_workflows** - At least one task to handle

For descriptions: Read `references/layout/descriptions.md` - "when/why" formula, not implementation.

## Task document

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

---

## Phase 1: Research (Haiku)

**Inputs:** User requirements, plugin path
**Outputs:** Task doc with domain analysis and validated structure plan

### Actions

1. **Understand the domain** (interactive with user)
   - Clarify skill purpose and scope
   - Identify major workflows (new X, update X, debug X)
   - Identify knowledge domains needed
   - Write to task doc: `## Domain Understanding`

2. **Design the structure**
   - Read: `${CLAUDE_PLUGIN_ROOT}/references/layout/reference.md`
   - Map workflows -> `workflows/*.md` files needed
   - Map knowledge domains -> `references/` subdirs
   - Identify scripts vs templates vs knowledge docs
   - Write to task doc: `## Proposed Structure`

3. **Validate with user**
   - Present structure plan
   - Get confirmation or adjust
   - Write to task doc: `## Structure Approved`

4. **Scaffold workspace**
   - Follow `${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`
   - Create `skills/<skill-name>/` directory tree
   - Create empty: `SKILL.md`, `workflows/`, `references/`, `templates/`, `scripts/`
   - Create empty `reference.md` in each references subdir
   - Write to task doc: `## Scaffolded Files`

---

## Phase 2: Processing (Sonnet)

**Inputs:** Task doc from Phase 1
**Outputs:** Complete skill structure with all content

### Actions

1. **Write SKILL.md**
   - Read: Task doc, `${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`
   - Write `SKILL.md` with workflow routing only
   - Just "when to use" and "read: workflows/X.md"
   - Write to task doc: `## SKILL.md Written`

2. **Write workflow files**
   - Read: Task doc, `${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`, `workflows/plugin-add-skill.md`
   - For each workflow from structure plan:
     - Write `workflows/<workflow-name>.md`
     - Include: when to use, inputs, subtasks with subagent hints, task doc instructions
   - Write to task doc: `## Workflows Written`

3. **Write reference.md files**
   - Read: Task doc, `references/progressive-disclosure/reference-md-pattern.md`, `${CLAUDE_PLUGIN_ROOT}/references/layout/reference.md`
   - For each references subdir:
     - Write `reference.md` with purpose, what's here, when to read which file
     - Include model hints
     - Stub knowledge docs
   - Write to task doc: `## Reference Indices Written`

4. **Fill knowledge docs**
   - Read: Task doc, relevant `reference.md` files
   - 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`

5. **Create scripts and templates**
   - Read: Task doc (scripts/templates from Phase 1 plan)
   - Write scripts for mechanical tasks
   - Write templates for repetitive structures
   - Make scripts executable
   - Write to task doc: `## Scripts and Templates Created`

---

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

**Inputs:** Task doc, all created files
**Outputs:** Verified skill, reflection notes, clean workspace

### Actions (Opus)

1. **Comprehensive review**
   - Read: Full task doc, `SKILL.md`, all workflows, spot-check references
   - Verify structure matches approved plan
   - Verify `reference.md` files accurate and navigable
   - Check workflow quality: clear subagent hints, proper inputs/outputs
   - Check consistency: naming, formatting, cross-references
   - Write to task doc: `## Quality Review`

2. **Friction reflection**
   - Read: `references/self-improvement/friction-reflection.md`
   - Identify friction points during creation:
     - Docs hard to find?
     - Too many file reads?
     - Work that should've been scripted?
     - Structure unclear?
   - Write to task doc: `## Friction / Improvement Notes`

3. **Final summary**
   - Summarize what was created
   - Note any limitations or future work
   - Write to task doc: `## Final Summary`

### Actions (Haiku cleanup)

4. **Workspace cleanup**
   - Remove any temporary files
   - Verify task doc is complete and well-organized
   - Confirm all files in correct locations