Agent Skills Guide: Write a SKILL.md That Works Everywhere

Agent skills are the simplest way I've found to stop pasting the same instructions into a coding agent every day. An agent skill is a folder with a SKILL.md file that teaches an agent one job, such as drafting release notes or following your deploy checklist. Anthropic published the format as an open standard in December 2025, and on 22 October 2026 it donated Agent Skills to the Agentic AI Foundation. This guide covers what a skill is, how to write one that loads in Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI and OpenCode, how npx skills and gh skill install them, how skills differ from MCP servers, and what to check before you install someone else's skill. It ends with a small skill you can copy into your repo today.

What are agent skills?

The specification defines a skill as a directory that contains at least a SKILL.md file. That file starts with YAML frontmatter and is followed by Markdown instructions. Everything else is optional:

• scripts/ for code the agent can run
• references/ for longer documentation the agent reads only when needed
• assets/ for templates, schemas and other static files

Only two frontmatter fields are required:

The description matters more than anything else in the file. It's the only part the agent sees before it decides to use the skill, so write it like a search query: what the skill does, plus the words a user would actually type when they need it.

How AI agent skills load: progressive disclosure

Skills stay cheap because agents load them in stages. The spec and Anthropic's Agent Skills overview describe three levels:

1. Metadata. At startup the agent loads only the name and description of every installed skill, roughly 100 tokens each.
2. Instructions. When your request matches a description, the agent reads the whole SKILL.md body. The spec suggests keeping it under 5,000 tokens and 500 lines.
3. Resources. Scripts and reference files are touched only when the instructions call for them. Anthropic's docs note that when Claude runs a script, only its output enters the context, not the code.

So you can keep a dozen skills in a repo without paying for all of them on every turn. Level 1 still costs tokens, so keep descriptions short and specific.

A working example: a release-notes skill

Here's a skill I'd give any small team. It drafts release notes from the real git history since the last tag, so the agent can't invent changes. Put it in .agents/skills/release-notes/:

.agents/skills/release-notes/
├── SKILL.md
└── scripts/
    └── collect_changes.py

SKILL.md:

---
name: release-notes
description: Drafts release notes from the git history since the last tag, grouped into features, fixes and other changes. Use when the user asks for release notes, a changelog entry, "what changed since the last release", or is preparing a version tag.
license: MIT
compatibility: Requires git and Python 3.9+. No network access needed.
metadata:
  author: nx-dev-solutions
  version: "1.0"
---

# Release notes

Draft release notes for this repository from real commit data. Never invent changes.

## Steps

1. From the repository root, run the collector script:
   `python3 scripts/collect_changes.py`
   To compare against a specific tag or commit, pass it: `python3 scripts/collect_changes.py v1.4.0`
2. The script prints JSON with `since`, `count` and `groups` (`features`, `fixes`, `breaking`, `other`).
   If `count` is 0, tell the user there is nothing to release and stop.
3. Write the notes in this order, skipping empty sections:
   - **Breaking changes** first, each with one line on what users must do.
   - **New features**
   - **Fixes**
   - **Other changes** (only if they matter to users; skip chores, CI and formatting).
4. Rewrite each commit subject as a plain sentence a customer would understand. Keep the short hash in brackets, for example `(a1b2c3d)`.
5. Suggest the next version number using semver: breaking changes bump major, features bump minor, otherwise patch.

## Rules

- Only use commits the script returned. If something looks important but is unclear, ask the user instead of guessing.
- Do not create tags, push, or publish anything. Output the notes as Markdown for the user to review.

scripts/collect_changes.py (standard library only):

#!/usr/bin/env python3
"""Collect commits since the last git tag and group them by Conventional Commit type.

Usage: python3 scripts/collect_changes.py [since-ref]
Prints JSON to stdout. Standard library only.
"""
import json
import re
import subprocess
import sys

PATTERN = re.compile(r"^(?P<type>\w+)(?:\([^)]*\))?(?P<bang>!)?:\s*(?P<subject>.+)$")


def git(*args):
    result = subprocess.run(["git", *args], capture_output=True, text=True)
    if result.returncode != 0:
        raise RuntimeError(result.stderr.strip() or f"git {' '.join(args)} failed")
    return result.stdout.strip()


def main():
    try:
        git("rev-parse", "--is-inside-work-tree")
    except RuntimeError:
        sys.exit("error: run this from inside a git repository")

    since = sys.argv[1] if len(sys.argv) > 1 else None
    if since is None:
        try:
            since = git("describe", "--tags", "--abbrev=0")
        except RuntimeError:
            since = None  # no tags yet: use the whole history

    rev_range = f"{since}..HEAD" if since else "HEAD"
    log = git("log", rev_range, "--no-merges", "--format=%h%x09%s%x09%b%x1e")

    groups = {"breaking": [], "features": [], "fixes": [], "other": []}
    count = 0
    for record in filter(None, (r.strip() for r in log.split("\x1e"))):
        short_hash, subject, body = (record.split("\t", 2) + ["", ""])[:3]
        count += 1
        match = PATTERN.match(subject)
        kind = match.group("type").lower() if match else "other"
        text = match.group("subject") if match else subject
        entry = {"hash": short_hash, "type": kind, "subject": text}
        if (match and match.group("bang")) or "BREAKING CHANGE" in body:
            groups["breaking"].append(entry)
        elif kind == "feat":
            groups["features"].append(entry)
        elif kind == "fix":
            groups["fixes"].append(entry)
        else:
            groups["other"].append(entry)

    print(json.dumps({"since": since or "(first commit)", "count": count, "groups": groups}, indent=2))


if __name__ == "__main__":
    main()

I tested this on a throwaway repo with a v1.0.0 tag and five Conventional Commits. The script put feat(api)!: and a BREAKING CHANGE: footer under breaking, and chore: under other. Outside a git repo it exits with a clear error. The folder also passes the reference validator from the agentskills GitHub repo:

skills-ref validate .agents/skills/release-notes
# Valid skill: .agents/skills/release-notes

The script does the deterministic work (reading git) and the instructions handle judgment (wording, version bump). The rules also say what the skill must not do, which matters because most tools load skills automatically.

Do agent skills work outside Claude? Where each tool looks

Yes. The same folder works across tools, but each one scans different directories. Here is what each tool's docs said on 24 October 2026:

My setup is .agents/skills/ as the real location, because every tool except Claude Code reads it, plus a symlink for Claude Code. Its docs say a project skill entry can be a symlink to a folder elsewhere:

mkdir -p .claude/skills
ln -s ../../.agents/skills/release-notes .claude/skills/release-notes

A few behaviours differ even when the file is identical. Gemini CLI asks for your consent before it activates a skill. Codex caps the initial skill list at about 2% of the context window by default and shortens descriptions when you have many. Claude Code adds its own extensions, such as disable-model-invocation and context: fork, which other tools may ignore. For the Claude API, custom skills are uploaded through the Skills API, need the code execution tool, and run in a container with no network access, according to the Agent Skills overview.

Installing skills: npx skills, skills.sh and gh skill

You can always copy a folder by hand. Two CLIs make it easier.

`npx skills` is the open source `skills` CLI from Vercel Labs (MIT licensed, npm version 1.7.4 when I checked). skills.sh is the directory and install leaderboard that goes with it. It installs from a GitHub repo, a URL or a local path, and symlinks each skill into the folder of each agent you pick:

npx skills add vercel-labs/agent-skills --list        # see what's in a repo
npx skills add ./my-local-skills -a claude-code       # local folder, one agent
npx skills check && npx skills update                 # keep installs current

`gh skill` is GitHub CLI's version, in public preview from GitHub CLI 2.90.0. According to GitHub's guide, it can search, preview, install with --pin to a tag or commit, update, and publish. It also writes the source repo and commit into the installed skill's frontmatter so updates can be checked.

Where to find agent skills on GitHub

Good starting points are anthropics/skills for Anthropic's reference skills, github/awesome-copilot for community skills, and the skills.sh leaderboard to see what other developers install. Popularity tells you a skill gets used. It doesn't tell you the skill is safe.

Agent skills vs MCP servers vs plain prompts

Skills don't replace MCP. They solve different problems and work well together.

A skill can tell the agent which MCP tools to use and in what order. GitHub's own example skill walks Copilot through debugging failed Actions runs using tools from the GitHub MCP server. If you are building the server side, my post on the MCP 2026-07-28 stateless spec covers what changed there.

Are agent skills safe? What to check first

A skill is instructions plus code that your agent may run with your permissions. Anthropic's security guidance says to use skills only from trusted sources and to audit everything bundled with one. GitHub warns that skills "are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts".

My checklist before installing a third-party skill:

• Read SKILL.md and every script. Look for network calls, reads of ~/.ssh or .env, and steps that don't match the description.
• Be wary of skills that fetch instructions from a URL at runtime. Those can change after you review them.
• Remove or narrow allowed-tools, especially shell access.
• Pin to a tag or commit (gh skill install ... --pin) instead of tracking a branch.
• Preview before installing (gh skill preview, npx skills add ... --list).
• Give side-effect skills like deploys disable-model-invocation: true where the tool supports it, so they only run when you call them.

What the AAIF donation changes

The Agentic AI Foundation sits under the Linux Foundation and already hosts MCP and AGENTS.md. Per Anthropic's announcement and the Linux Foundation press release, here is what moved:

• Ownership: the Agent Skills name and logo, the agentskills GitHub organization and the agentskills.io domain now belong to AAIF.
• Maintainers: engineers from Anthropic, Google, OpenAI and other companies maintain it as individuals, with David Soria Parra and Mahesh Murag as lead maintainers. The AAIF blog says a multi-company Technical Steering Committee will guide it.
• Roadmap: the first proposals are versioned releases, a formal proposal process and security guidance for people who write and install skills.
• Scale: Anthropic says more than 70 agent platforms support the format, with about 1 million skills published and nearly 280 million installs.

For your existing skills, nothing changes today. The format is the same and you don't have to join AAIF to use or contribute to it. The gain is that a versioned spec should make "works in every tool" easier to check over time. If you're deciding where skills fit next to workflow tools, my n8n agents vs classic workflows comparison uses the same rule: put steps that must run the same way every time somewhere deterministic.

Quick start checklist

• Create .agents/skills/<name>/SKILL.md with name matching the folder.
• Write a description that says what it does and when to use it, using your users' words.
• Keep the body short. Move long reference material to references/.
• Put deterministic steps in scripts/ and test them outside the agent first.
• Validate with skills-ref validate, then symlink into .claude/skills/ if your team uses Claude Code.
• Commit it, and review third-party skills like any other dependency.