---
name: skill-structure-guide
description: |
  Complete reference for creating SKILL.md files with proper structure and frontmatter.
  Use this skill when creating new skills, when understanding skill file format,
  or when debugging why a skill isn't triggering. Triggers: "create skill",
  "SKILL.md format", "skill frontmatter", "skill structure", "skill not triggering",
  "skill directory", "skill template".
---

# Skill Structure Guide

Complete reference for creating and structuring Claude Code skills.

## Directory Structure

### Skill Location
```
.claude/skills/[skill-name]/
└── SKILL.md              # Required - main instructions
└── scripts/              # Optional - executable code
└── references/           # Optional - documentation for context
└── assets/               # Optional - files for output
```

### Priority Order
1. Enterprise (managed settings)
2. Personal (`~/.claude/skills/`)
3. Project (`.claude/skills/`)
4. Plugin (`<plugin>/skills/`)

## SKILL.md Template

```yaml
---
name: skill-name
description: |
  What this skill does and when to use it. Include specific trigger
  phrases users would naturally say. Be comprehensive - this is the
  ONLY thing Claude sees to decide whether to load the skill.
  Triggers: "phrase 1", "phrase 2", "phrase 3".
---

# Skill Title

[Main instructions Claude follows when skill is active]

## Quick Start
[Essential usage steps]

## Guidelines
- Guideline 1
- Guideline 2

## Examples
[Concrete examples showing expected behavior]

## Additional Resources
- For advanced features, see [reference.md](reference.md)
```

## Frontmatter Reference

### Required/Recommended

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Recommended | Display name (uses directory name if omitted). Lowercase, hyphens, max 64 chars. |
| `description` | **Critical** | What skill does + when to use it. Include trigger phrases. |

### Optional Fields

| Field | Default | Description |
|-------|---------|-------------|
| `argument-hint` | none | Hint for autocomplete (e.g., `[issue-number]`) |
| `disable-model-invocation` | false | Prevent auto-loading, manual `/skill` only |
| `user-invocable` | true | Show in `/` menu |
| `allowed-tools` | all | Tools usable without permission prompts |
| `model` | inherited | Model to use (sonnet/opus/haiku) |
| `context` | main | Set to `fork` for subagent execution |
| `agent` | none | Subagent type when `context: fork` |

## Description Best Practices

The description is **critical** - it's the only information Claude sees to decide whether to load the skill.

### Good Descriptions

```yaml
# Good: Comprehensive with triggers
description: |
  Patterns for spawning and using agents via the Task tool. Use when
  spawning Explore, Plan, or general-purpose agents, when writing
  agent prompts, or when using parallel/background agents.
  Triggers: "spawn agent", "Task tool", "subagent patterns".

# Good: Action-oriented with context
description: Create production-grade frontend interfaces. Use when
  building web components, pages, or applications.
```

### Bad Descriptions

```yaml
# Bad: Too vague
description: Helps with agents

# Bad: No trigger context
description: A tool for working with subagents
```

### Description Formula

```
[What it does] + [When to use it] + [Trigger phrases]
```

## Invocation Control

| Settings | You Can Invoke | Claude Can Invoke |
|----------|----------------|-------------------|
| (default) | Yes (`/skill`) | Yes (auto) |
| `disable-model-invocation: true` | Yes | No |
| `user-invocable: false` | No | Yes |

## String Substitutions

| Variable | Description |
|----------|-------------|
| `$ARGUMENTS` | All arguments passed to skill |
| `$ARGUMENTS[N]` | Specific argument by index |
| `$0`, `$1`, etc. | Shorthand for arguments |
| `` !`command` `` | Shell command output (preprocessed) |

### Example with Arguments

```yaml
---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
---

Fix GitHub issue #$ARGUMENTS following our coding standards.
```

Usage: `/fix-issue 123` → "Fix GitHub issue #123..."

## Naming Conventions

### Rules
- Lowercase letters, numbers, hyphens only
- Maximum 64 characters
- Hyphens separate words

### Good Names
- `task-agent-patterns`
- `skill-structure-guide`
- `frontend-design`
- `pr-summary`

### Bad Names
- `TaskAgentPatterns` (no camelCase)
- `skill_structure` (no underscores)
- `guide` (too generic)

## Supporting Files

### scripts/
- Executable code (Python, Bash, etc.)
- Token efficient, deterministic
- Claude executes without loading into context

### references/
- Documentation loaded as needed
- API specs, schemas, policies
- For large files (>10k words), include grep patterns in SKILL.md

### assets/
- Files for output, not loaded into context
- Templates, images, boilerplate

## Skills vs Commands vs Agents

| Aspect | Skills | Commands | Agents |
|--------|--------|----------|--------|
| Location | `.claude/skills/` | `.claude/commands/` | `.claude/agents/` |
| Invocation | Auto or `/skill` | Manual `/cmd` only | Via Task tool |
| Context | Main conversation | Main conversation | Isolated |
| Purpose | Knowledge/guidance | Execute steps | Complex parallel work |

**Note:** Commands and skills with same name share `/name` invocation.

## Troubleshooting

### Skill Not Triggering
1. Check description includes natural trigger phrases
2. Verify skill shows in `What skills are available?`
3. Try rephrasing to match description keywords
4. Invoke directly with `/skill-name`

### Skill Triggers Too Often
1. Make description more specific
2. Add `disable-model-invocation: true`

### Skill Not Visible
- May exceed character budget (default 15,000)
- Run `/context` to check for warnings
- Increase `SLASH_COMMAND_TOOL_CHAR_BUDGET`

## Content Guidelines

### Do Include
- Clear instructions Claude can follow
- Concrete examples of expected behavior
- Decision criteria and edge cases
- References to supporting files

### Don't Include
- README.md or installation guides
- Changelog or version history
- Redundant explanations (Claude is smart)
- Excessive documentation (keep <500 lines)

## Quick Checklist

- [ ] Directory: `.claude/skills/[name]/SKILL.md`
- [ ] Name: kebab-case, descriptive, <64 chars
- [ ] Description: What + When + Triggers
- [ ] Content: <500 lines, actionable
- [ ] Examples: Concrete, not abstract
- [ ] References: Linked from SKILL.md body