Recommended Skill Structure

The optimal structure for complex skills separates routing, workflows, and knowledge.

``` skill-name/ ├── SKILL.md # Router + essential principles (unavoidable) ├── workflows/ # Step-by-step procedures (how) │ ├── workflow-a.md │ ├── workflow-b.md │ └── ... └── references/ # Domain knowledge (what) ├── reference-a.md ├── reference-b.md └── ... ```

<why_this_works>

Problems This Solves

Problem 1: Context gets skipped When important principles are in a separate file, Claude may not read them. Solution: Put essential principles directly in SKILL.md. They load automatically.

Problem 2: Wrong context loaded A "build" task loads debugging references. A "debug" task loads build references. Solution: Intake question determines intent → routes to specific workflow → workflow specifies which references to read.

Problem 3: Monolithic skills are overwhelming 500+ lines of mixed content makes it hard to find relevant parts. Solution: Small router (SKILL.md) + focused workflows + reference library.

Problem 4: Procedures mixed with knowledge "How to do X" mixed with "What X means" creates confusion. Solution: Workflows are procedures (steps). References are knowledge (patterns, examples). </why_this_works>

<skill_md_template>

SKILL.md Template

---
name: skill-name
description: What it does and when to use it.
---

<essential_principles>
## How This Skill Works

[Inline principles that apply to ALL workflows. Cannot be skipped.]

### Principle 1: [Name]
[Brief explanation]

### Principle 2: [Name]
[Brief explanation]
</essential_principles>

<intake>
**Ask the user:**

What would you like to do?
1. [Option A]
2. [Option B]
3. [Option C]
4. Something else

**Wait for response before proceeding.**
</intake>

<routing>
| Response | Workflow |
|----------|----------|
| 1, "keyword", "keyword" | `workflows/option-a.md` |
| 2, "keyword", "keyword" | `workflows/option-b.md` |
| 3, "keyword", "keyword" | `workflows/option-c.md` |
| 4, other | Clarify, then select |

**After reading the workflow, follow it exactly.**
</routing>

<reference_index>
All domain knowledge in `references/`:

**Category A:** file-a.md, file-b.md
**Category B:** file-c.md, file-d.md
</reference_index>

<workflows_index>
| Workflow | Purpose |
|----------|---------|
| option-a.md | [What it does] |
| option-b.md | [What it does] |
| option-c.md | [What it does] |
</workflows_index>

</skill_md_template>

<workflow_template>

Workflow Template

# Workflow: [Name]

<required_reading>
**Read these reference files NOW:**
1. references/relevant-file.md
2. references/another-file.md
</required_reading>

<process>
## Step 1: [Name]
[What to do]

## Step 2: [Name]
[What to do]

## Step 3: [Name]
[What to do]
</process>

<success_criteria>
This workflow is complete when:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
</success_criteria>

</workflow_template>

<when_to_use_this_pattern>

When to Use This Pattern

Use router + workflows + references when:

Multiple distinct workflows (build vs debug vs ship)
Different workflows need different references
Essential principles must not be skipped
Skill has grown beyond 200 lines

Use simple single-file skill when:

One workflow
Small reference set
Under 200 lines total
No essential principles to enforce </when_to_use_this_pattern>

<key_insight>

The Key Insight

SKILL.md is always loaded. Use this guarantee.

Put unavoidable content in SKILL.md:

Essential principles
Intake question
Routing logic

Put workflow-specific content in workflows/:

Step-by-step procedures
Required references for that workflow
Success criteria for that workflow

Put reusable knowledge in references/:

Patterns and examples
Technical details
Domain expertise </key_insight>

3.9 KiB Raw Blame History