# Skills Authoring Guide

Skills are on-demand context files that Claude loads when relevant. They extend `AGENTS.md` with deep-dive workflows, code templates, and verification steps.

## When to Create a Skill

Create a skill when content is:
- **Too detailed for AGENTS.md** (code templates, multi-step workflows, diagnostic procedures)
- **Only relevant for specific tasks** (not every session needs it)
- **Self-contained enough to load independently**

Do NOT create a skill for:
- One-liner rules or guardrails (keep those in AGENTS.md)
- Content every agent session needs (that's what AGENTS.md is for)
- Simple facts without actionable steps

## File Structure

```
.agents/skills/
├── my-skill/
│   └── SKILL.md          # Required: frontmatter + content
│   └── workflow.md        # Optional: supplementary files
│   └── examples.md        # Optional: referenced from SKILL.md
└── README.md              # This file
```

## SKILL.md Format

```yaml
---
name: my-skill
description: >
  What this skill covers and when to use it. Include key file names,
  concepts, and trigger phrases so Claude can match user intent to this
  skill. This is the primary field Claude uses for auto-activation.
---
```

### Supported Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Skill name, used for `$name` references and `/name` slash commands |
| `description` | Yes | What the skill does and when to use it. **This is how Claude decides to auto-load the skill.** Include file names, concepts, and keywords. |
| `argument-hint` | No | Hint for expected arguments in autocomplete |
| `user-invocable` | No | Set to `false` to hide from `/` slash command menu |
| `disable-model-invocation` | No | Set to `true` to prevent Claude from auto-triggering this skill |
| `allowed-tools` | No | Tools Claude can use without permission when this skill is active |
| `model` | No | Model override for this skill |
| `context` | No | Set to `fork` for isolated subagent execution |
| `agent` | No | Subagent type to use with `context: fork` |
| `hooks` | No | Hooks scoped to this skill's lifecycle |

Only use fields from this table. Unknown fields are ignored by Claude Code.

### Writing Good Descriptions

The `description` is the single most important field. Claude uses it to decide when to auto-load the skill. Include:

- **What the skill covers** (the topic)
- **When to use it** (the trigger scenario)
- **Key file names** mentioned in the skill (e.g. `config-shared.ts`, `entry-base.ts`)
- **Key concepts/keywords** a user or agent might mention (e.g. "DCE", "feature flag", "vendored React")

```yaml
# Bad: too vague, won't match well
description: Helps with flags.

# Good: specific, includes file names and keywords
description: >
  How to add or modify Next.js experimental feature flags end-to-end.
  Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts,
  next-server.ts, export/worker.ts, or module.compiled.js.
```

## Content Guidelines

### Relationship to AGENTS.md

AGENTS.md holds **always-loaded guardrails** (one-liner rules every session needs). Skills hold **deep-dive content** loaded on demand.

- AGENTS.md should have a one-liner version of any critical rule
- Skills expand on those rules with verification steps, code examples, and context
- AGENTS.md points to skills via `$skill-name` references
- Skills should not duplicate AGENTS.md content; they should go deeper

### Structure a Skill for Action

Skills should tell the agent what to **do**, not just what to **know**:

- Lead with a clear "Use this skill when..." statement
- Include step-by-step procedures where applicable
- Add code templates ready to adapt
- End with verification commands
- Cross-reference related skills with a "Related Skills" section

### Naming

- Use short, descriptive names scoped to the topic: `flags`, `dce-edge`, `react-vendoring`
- No repo-name prefix (skills are already scoped to this repo by being in `.agents/skills/`)
- Use hyphens for multi-word names

### Supplementary Files

For complex skills, split into a hub SKILL.md + detail files:

```
pr-status-triage/
├── SKILL.md         # Overview + quick commands
├── workflow.md      # Detailed prioritization and patterns
└── local-repro.md   # CI env matching guide
```

Reference detail files from SKILL.md with relative links. Keep SKILL.md scannable as an entry point.