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

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

.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

---
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.
---

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

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")

# 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.

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

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

• 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

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.