authoring-skills_skill

Overview

This skill explains how to create and maintain agent skills in the .agents/skills/ directory. It helps you decide when to split content out of the always-loaded agent file into on-demand skills and how to structure metadata, naming, and supplementary files for reliable auto-loading and discoverability.

How this skill works

It inspects and prescribes the required frontmatter fields and values the agent runtime recognizes and shows how description text drives auto-activation. It guides how to organize content into a short hub file plus optional detail pages, what belongs in the always-loaded agent file versus an on-demand skill, and how to reference skills from the main agent surface.

When to use it

• When content is too detailed for the always-loaded agent surface (multi-step workflows or code templates).
• When information applies only to specific tasks and should load on demand.
• When you need a self-contained troubleshooting or diagnostic procedure.
• When adding step-by-step verification commands and examples for a pattern.
• When you want to keep short guardrails in the always-loaded file but expand details separately.

Best practices

• Make the description the primary matching surface: state what it covers, when to use it, key file names, and matching keywords.
• Lead with 'Use this skill when...' and include concrete, numbered steps and verification commands.
• Use only the supported frontmatter fields and avoid unknown fields to ensure runtime compatibility.
• Name skills short and topic-scoped with hyphens for multi-word names (no repo prefixes).
• Add a one-line summary in the always-loaded agent file that references the skill by name.

Example use cases

• Documenting an end-to-end feature flag change with file list, code snippets, and verification commands.
• Providing a DCE pattern with full code examples, edge cases, and CI checks separate from guardrails.
• Creating a triage hub that links to workflows, repro steps, and prioritization guidance.
• Packaging a local reproduction guide for flaky CI that includes environment setup and debug commands.