Authoring Skills

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.