back
loading skill details...
>
Authoring Skills
Use this skill when creating or modifying agent skills in .agents/skills/.
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 needed every session)
Self-contained enough to load independently
Keep in AGENTS.md instead when:
It's a one-liner rule or guardrail every session needs
It's a general-purpose gotcha any agent could hit
File Structure
.agents/skills/
└── my-skill/
├── SKILL.md # Required: frontmatter + content
├── workflow.md # Optional: supplementary detail
└── examples.md # Optional: referenced from SKILL.md
Supported Frontmatter Fields
---
name: my-skill # Required. Used for $name references and /name commands.
description: > # Required. How Claude decides to auto-load the skill.
What this covers and when to use it. Include file names and keywords.
argument-hint: '<pr-number>' # Optional. Hint for expected arguments.
user-invocable: false # Optional. Set false to hide from / menu.
disable-model-invocation: true # Optional. Set true to prevent auto-triggering.
allowed-tools: [Bash, Read] # Optional. Tools allowed without permission.
model: opus # Optional. Model override.
context: fork # Optional. Isolated subagent execution.
agent: Explore # Optional. Subagent type (with context: fork).
---
Only use fields from this list. Unknown fields are silently ignored.
Writing Descriptions
The description is the primary matching surface for auto-activation. Include:
What the skill covers (topic)
When to use it (trigger scenario)
Key file names the skill references (e.g. config-shared.ts)
Keywords a user or agent might mention (e.g. "feature flag", "DCE")
# Too vague - won't auto-trigger reliably
description: Helps with flags.
# Good - specific files and concepts for matching
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.
Content Conventions
Structure for Action
Skills should tell the agent what to do, not just what to know:
Lead with "Use this skill when..."
Include step-by-step procedures
Add code templates ready to adapt
End with verification commands
Cross-reference related skills in a "Related Skills" section
Relationship to AGENTS.md
AGENTS.md (always loaded)
Skills (on demand)
One-liner guardrails
Step-by-step workflows
"Keep require() behind if/else for DCE"
Full DCE pattern with code examples, verification commands, edge cases
Points to skills via $name
Expands on AGENTS.md rules
When adding a skill, also add a one-liner summary to the relevant AGENTS.md section with a $skill-name reference.
Naming
Short, descriptive, topic-scoped: flags, dce-edge, react-vendoring
No repo prefix (already scoped by .agents/skills/)
Hyphens for multi-word names
Supplementary Files
For complex skills, use a hub + detail pattern:
pr-status-triage/
├── SKILL.md # Overview, quick commands, links to details
├── workflow.md # Prioritization and patterns
└── local-repro.md # CI env matchingdon't have the plugin yet? install it then click "run inline in claude" again.