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: 

Only use fields from this list. Unknown fields are silently ignored.

Writing Descriptions

The description is the primary matching surface for auto-activation. Include:

1. What the skill covers (topic)
2. When to use it (trigger scenario)
3. Key file names the skill references (e.g. config-shared.ts)
4. Keywords a user or agent might mention (e.g. "feature flag", "DCE")

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

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: