How to build an AI agent skill

1. What a skill is

A skill is a Markdown file with a little frontmatter and a set of instructions. Agent runtimes like Claude Code load it automatically and follow it when the task matches. Think of it as a checklist your agent internalises — turning "please review this PR" into a consistent, high-quality review every time.

2. The SKILL.md structure

A minimal skill looks like this:

---
name: commit-message
description: Write a clear Conventional Commits message from a staged diff.
allowed-tools: [Bash(git diff:*), Read]
---

# Commit message writer

## Musts
- Read the staged diff before writing anything.
- Use Conventional Commits: type(scope): summary (<=72 chars).
- Body explains WHY, not what; wrap at 72 columns.

## Guidelines
- Prefer feat / fix / docs / refactor / test / chore.
- Never invent changes not present in the diff.

3. Write instructions an agent can actually follow

• Be specific and testable. "Summary ≤72 chars" beats "keep it short".
• Separate Musts from Guidelines. Hard rules vs. preferences — the agent treats them differently.
• Say what NOT to do. "Never invent changes not in the diff" prevents the most common failure.
• Give one worked example. A single input→output example locks the format better than a paragraph describing it.

These are the same principles from our prompt engineering playbook — a skill is a reusable, version-controlled prompt.

4. Constrain the tools (allowed-tools)

The allowed-tools field limits what the skill can do. Grant the minimum — a commit-message skill needs to read a diff, not delete files. This is least-privilege, and it's the single most important safety habit; read the LLM security playbook before shipping a skill that touches real systems.

5. Test it before you trust it

• Run it on a few real, varied inputs — including a tricky edge case.
• Check it obeys its Musts and stays inside its allowed tools.
• Try to break it: give it something off-topic and confirm it declines gracefully.

6. Share it

Happy with your skill? Submit it to our catalog so others can find and reuse it. We review each submission for clarity and safety, then publish it with credit to you.