Write Agent Skills That Match the Open Specification

A skill that works in your session but fails for teammates usually has a spec problem, not a model problem. The Agent Skills open standard (documented in agentskills/agentskills) defines the minimum metadata and folder layout agents expect.

This tutorial shows how to shape a skill so discovery, activation, and execution behave predictably across tools.

Why the Spec Exists

Agents keep dozens of skills on disk but cannot load full instructions for all of them at once. The standard encodes progressive disclosure:

1. Discovery — load only name and description at startup
2. Activation — read full SKILL.md when the task matches the description
3. Execution — follow instructions; optionally run scripts/ or read references/

If your description is vague, step 2 never happens. If your body is huge, step 3 burns context even when the skill activates.

Required Folder Layout

my-skill/
├── SKILL.md          # Required
├── scripts/          # Optional
├── references/       # Optional
└── assets/           # Optional templates, examples

SKILL.md is the contract. Everything else is optional supporting material.

Minimal Valid SKILL.md

---
name: release-notes
description: Generate structured release notes from git history, grouped by conventional commit type
---

## When to activate

The user asks for release notes, a changelog, or "what changed" since a tag or date.

## Instructions

1. Run `git log --oneline` for the requested range.
2. Group commits by prefix (feat, fix, docs, chore).
3. Output Markdown with sections for New Features, Bug Fixes, and Other Changes.
4. Do not invent commits that are not in the log.

Two rules matter most:

• name — stable identifier, kebab-case, no spaces
• description — one sentence a router model can match to user intent

The description is not marketing copy. Write what task triggers the skill, not how amazing it is.

Real Workflow: Fix a Skill That Never Activates

Your code-review skill exists on disk but the agent improvises reviews instead.

Diagnose

Open SKILL.md and check the description:

description: Helps with code

That is too broad. Competing skills and base model behavior will win.

Rewrite for activation

description: Review staged git diff for correctness, security, and test gaps; output findings by severity

Add an explicit activation section in the body:

## When to activate

The user asks for a code review, PR review, or "check my diff" on current changes.
Do NOT activate for writing new features from scratch or generating release notes.

Test

Start a fresh agent session (discovery runs at startup). Ask:

Review my staged changes for security issues before I commit

The agent should name the skill in its reasoning or follow the structured output format you defined.

Real Workflow: Keep Context Small with References

You are documenting a 40-page internal API. Putting it all in SKILL.md slows every activation.

Split the skill:

## Instructions

1. Read references/api-overview.md for authentication rules.
2. Only load references/endpoints/<service>.md when the user names that service.
3. Never guess endpoint paths not present in references/.

my-skill/
├── SKILL.md
└── references/
    ├── api-overview.md
    └── endpoints/
        ├── billing.md
        └── users.md

The spec allows agents to load referenced files during execution, not at discovery. That keeps startup light.

Spec Checklist Before You Share

Validate against the published spec when in doubt: agentskills.io/specification.

Comparison: Spec-Aligned vs Ad Hoc Skills

Agents tolerate ad hoc skills until you add a second skill or a second teammate. Then collisions and context bloat show up.

Tips

• Read Agent Skills 101 for ecosystem basics, then use this guide when authoring for multiple tools.
• Study anthropics/skills examples. They follow the same standard the spec documents.
• Version skills in git. Treat SKILL.md changes like API changes: bump behavior in the instructions, not silent rewrites.
• Install with npx skills once the skill validates locally.

When Not to Use Heavy Spec Structure

A personal one-liner alias ("always use tabs not spaces") does not need references/, scripts, or a marketplace README. Still keep name and description accurate so you can migrate to full spec later without renaming.

Browse spec-aligned skills on the SkillMap leaderboard.