Agent skill · writing content · vercel
authoring-skills
How to create and maintain agent skills in .agents/skills/. Use when creating a new SKILL.md, writing skill descriptions, choosing frontmatter fields, or deciding what content belongs in a skill vs AGENTS.md. Covers the supported spec fields, description writing, naming conventions, and the relationship between always-loaded AGENTS.md and on-demand skills.
Why this skill is useful
Provides detailed guidelines for creating agent skills, including naming conventions and file structures that the AI wouldn't reliably generate on its own.
What it needs
About 2k tokens when loaded. Last updated 2026-08-07. 141,663 stars on the source repository.
What this skill does
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 Supported Frontmatter Fields 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 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:
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills vercel/authoring-skills