# Skill Best Practices

Based on official Claude Code documentation and SmartStack conventions.

## Design Principles

### 1. Keep SKILL.md Under 500 Lines
- Move detailed content to `references/` directory
- Move code templates to `templates/` directory
- Use progressive step loading for complex workflows
- Each step file should also be focused (< 200 lines ideal)

### 2. Write Clear Descriptions
- Use natural language keywords Claude can match against
- Include "Use this skill when:" trigger list
- Be specific about what the skill does AND does not do

```yaml
# Good
description: |
  Generate API controllers following REST conventions.
  Use this skill when:
  - Creating new API endpoints
  - Adding CRUD operations to a module
  - Generating controller tests

# Bad
description: Controller generation
```

### 3. Set Invocation Mode Correctly

| Scenario | Setting |
|----------|---------|
| Research, analysis, exploration | `disable-model-invocation: false` |
| Code generation, scaffolding | `disable-model-invocation: false` |
| Deployment, publishing | `disable-model-invocation: true` |
| Git operations (commit, push) | `disable-model-invocation: true` |
| Database operations (reset, seed) | `disable-model-invocation: true` |
| Destructive operations | `disable-model-invocation: true` |

**Rule of thumb:** If the skill has side effects that can't be easily undone, set `disable-model-invocation: true`.

### 4. Use Progressive Step Loading for Complex Workflows
- Minimizes context usage (only current step loaded)
- State persists across steps via conversation
- Each step is self-contained and testable
- Easier to maintain and debug

### 5. Prefer Forked Context for Research
- Clean context = no interference from previous conversation
- Ideal for exploration, search, analysis
- Fast agents (haiku) for simple searches
- Full agents (sonnet/opus) for complex reasoning

## Structural Best Practices

### Directory Organization
```
my-skill/
├── SKILL.md           # Main definition (< 500 lines)
├── steps/             # Progressive step files
│   ├── step-00-init.md
│   └── step-01-*.md
├── templates/         # Code templates for generation
├── references/        # Documentation and checklists
├── scripts/           # Executable scripts
└── examples/          # Example outputs
```

### Step File Convention
- Always start with `step-00-init.md` for initialization
- Number sequentially: step-00, step-01, step-02, ...
- Use descriptive names: step-01-analyze, step-02-generate
- Each step defines `next_step` in frontmatter (except last)
- Last step handles completion summary

### Frontmatter Minimalism
Only include fields that differ from defaults:
```yaml
# Good - minimal, clear
---
name: my-skill
description: What it does
disable-model-invocation: true
---

# Bad - redundant defaults
---
name: my-skill
description: What it does
disable-model-invocation: true
user-invocable: true        # This is the default
model: inherit              # This is the default
context:                    # Empty, not needed
---
```

## Content Best Practices

### 1. Use XML Sections Consistently
Standard order: objective → quick_start → parameters → workflow → state_variables → entry_point → step_files → execution_rules → success_criteria

### 2. Provide Usage Examples
Always include `<quick_start>` with realistic examples:
```xml
<quick_start>
` ` `bash
/my-skill basic-usage
/my-skill --flag advanced-usage
/my-skill subcommand arg1 arg2
` ` `
</quick_start>
```

### 3. Document State Variables
For progressive skills, always document what persists:
```xml
<state_variables>
| Variable | Type | Description |
|----------|------|-------------|
| `{name}` | string | Required - item name |
| `{auto}` | boolean | Optional - skip prompts |
</state_variables>
```

### 4. Define Clear Success Criteria
What does "done" look like?
```xml
<success_criteria>
- Files generated at correct paths
- No validation errors
- Build passes (if applicable)
- User informed of next steps
</success_criteria>
```

### 5. Use Compact Output
Prefer tables over prose for summaries:
```markdown
| Metric | Value |
|--------|-------|
| Files created | 5 |
| Lines generated | 342 |
| Warnings | 0 |
| Status | Complete |
```

## Anti-Patterns to Avoid

| Anti-Pattern | Why | Better |
|-------------|-----|--------|
| Huge SKILL.md (> 500 lines) | Wastes context | Split into steps + references |
| Vague description | Claude can't auto-invoke | Use trigger keywords |
| Missing entry_point | Steps won't load | Always define entry_point |
| Circular step refs | Infinite loop | Linear step chain |
| Hardcoded paths | Not portable | Use relative paths |
| No success criteria | Unclear completion | Define measurable criteria |
| Skipping validation step | Quality issues | Always validate at end |

## Testing Your Skill

1. **Manual test:** Run `/my-skill` with various arguments
2. **Edge cases:** Test with missing args, invalid input, empty state
3. **Audit:** Run `/cc-audit` to validate structure
4. **Step chain:** Verify each step loads the next correctly
5. **Cross-project:** Test in different project contexts if applicable
