Skill

Skill Authoring

A meta-capability for writing high-quality SKILL.md files that agents can discover, load, and follow reliably across platforms.

Use case

Use this skill when a task involves:

• Creating a new agent skill from scratch.
• Editing or restructuring an existing SKILL.md.
• Making a skill discoverable (description match) and portable across agents.
• Reviewing skills for missing frontmatter, ambiguous instructions, or platform issues.

Core principle

A skill is a self-contained, discoverable instruction file: a minimal YAML frontmatter that advertises it, and a body that tells the agent exactly what to do.

Structure

---
name: my-skill
description: One sentence on what it does and when to use it.
---

# My Skill

Purpose + use case, then a concrete workflow.

Workflow

1. Name it — One word or hyphenated slug, matching the install folder name.
2. Describe it — A sentence covering what it does AND when the agent should trigger it (keywords help).
3. Write the body — Purpose → Use case → Workflow → Rules → Verification/quality gates.
4. Keep it scannable — Short sections, numbered steps, concrete rules over abstractions.
5. Validate — Check frontmatter keys, description quality, and that instructions are unambiguous.

Rules

• Frontmatter must include name and description; platform extras (allowed-tools, paths, etc.) are optional.
• Keep the description under ~200 characters; it drives auto-discovery.
• Write imperative, testable instructions — "run X", "if Y, do Z" — not essays.
• Avoid vague words ("usually", "maybe", "nice to have") in critical steps.
• Include a use case section so the skill self-advertises when it applies.

Quality gates

• The description alone tells an agent when to load the file.
• A new agent reading only this file could execute the skill without asking questions.
• The skill works across platforms that read the open SKILL.md standard.