Agent Skills Are Now an Open Standard: Write Your First SKILL.md in 15 Minutes

On 22 October, Anthropic donated Agent Skills to the Agentic AI Foundation, the Linux Foundation project that already hosts MCP and AGENTS.md. According to Anthropic's announcement, more than 70 agent platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, have integrated the standard since it was published in December 2025.

For you as a developer, nothing breaks. The format stays the same, the spec still lives at agentskills.io, and you can keep using it without joining anything. What changes is the case for learning it: a skill you write today is no longer tied to one vendor's roadmap.

So let's write one. This article walks through a small, real skill from empty folder to "it fires when I ask for it", using only what the spec and the Claude Code docs actually say.

What a skill is, in one paragraph

A skill is a folder with a SKILL.md file inside. The file has YAML frontmatter (at minimum a name and a description) followed by Markdown instructions. The folder can also hold scripts/, references/ and assets/. Agents load skills through what the spec calls progressive disclosure: at startup they read only the name and description of every skill (the spec estimates about 100 tokens each), they load the full body only when a task matches, and they open bundled files only when the instructions call for them.

That last point is the whole trick. You can keep dozens of skills installed because each one costs you a line in the listing until it's needed. It also means one field does most of the work, and we'll get to it in step 3.

Step 1: Pick a task worth a skill

Good first skills share three traits:

• You do the task often enough that re-explaining it is annoying.
• It has steps or conventions the model can't guess (your team's format, your tools, your order of operations).
• You can tell whether the result is right.

Bad first skills are vague ("be a better coder") or one-off. For this walkthrough we'll build pr-description: a skill that turns the current branch's changes into a pull request description in a fixed format. Most teams have a format, and most agents don't know it.

Step 2: Create the folder and get the name right

mkdir -p ~/.claude/skills/pr-description

That path is Claude Code's personal location, available in all your projects. For a skill your whole team should get, use .claude/skills/pr-description/ inside the repository and commit it. Other agents read skills from their own locations, so check your tool's docs for the exact path; the folder and file format are the same.

The spec is strict about name:

• 1 to 64 characters
• lowercase letters, numbers and hyphens only
• no leading or trailing hyphen, no --
• it must match the folder name

pr-description passes. PR-Description and pr--description don't.

Step 3: Write the description first

The description is what the agent reads when deciding whether your skill is relevant. If it doesn't match how you actually phrase requests, the skill never loads, and the instructions you carefully wrote never get read.

The spec gives a clear contrast. A poor description:

description: Helps with PDFs.

A good one says what the skill does and when to use it, with the keywords a user would say:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

A few rules that come straight from the docs:

• Length. The spec caps description at 1,024 characters. Claude Code also truncates each skill's listing text at 1,536 characters and, when you have many skills, drops descriptions of the least-used ones to fit a budget. Put the main use case first.
• Point of view. Anthropic's skill authoring best practices say to write descriptions in the third person ("Writes...", not "I can help you..."), because the text is injected into the system prompt.
• Real phrases. Think about the three or four ways you'd actually ask: "write the PR description", "summarize this branch for review", "draft a pull request".

Here's ours:

description: Writes a pull request description from the current branch's changes, using the team template (summary, changes, testing, risks). Use when the user asks for a PR description, a pull request summary, or wants to open a PR.

Step 4: Write a short, specific body

The body has no required format. The spec recommends step-by-step instructions, examples of inputs and outputs, and common edge cases, and suggests keeping SKILL.md under 500 lines, moving long reference material into separate files. The Claude Code docs add a practical reason to stay brief: once a skill loads, its content stays in context across turns, so every line is a recurring cost.

The complete file, saved as ~/.claude/skills/pr-description/SKILL.md:

---
name: pr-description
description: "Writes a pull request description from the current branch's changes, using the team template (summary, changes, testing, risks). Use when the user asks for a PR description, a pull request summary, or wants to open a PR."
---

# PR description

## Steps
1. Run `git log --oneline main..HEAD` and `git diff main...HEAD --stat` to see what changed.
2. Read the diff of the files that changed most.
3. Fill in the template below. Keep each section short.
4. If the branch has no commits ahead of main, say so and stop.

## Template
### Summary
One or two sentences: what this PR does and why.

### Changes
- Bullet per meaningful change, grouped by area.

### Testing
How it was tested. If no tests were added, write "No new tests" and say why.

### Risks
Anything a reviewer should look at closely: migrations, config changes, removed code, public API changes. Write "None found" only if you checked.

## Rules
- Do not invent test results. Only report tests you ran or that exist in the diff.
- Do not mention files that did not change.

Notice what's in there: the exact commands, the exact template, the edge case (no commits) and two rules that stop the most common failure (made-up test results). Notice what isn't: background on why PR descriptions matter. The model doesn't need persuading.

Step 5: Test that it fires

Claude Code watches the skills folders, so a new or edited SKILL.md is picked up in the current session without a restart. Then test it two ways, as the docs suggest:

1. Let the agent choose it. In a repo with a feature branch, ask something that matches the description: "Can you write the PR description for this branch?"
2. Call it directly. Type /pr-description.

If the direct call works but the natural request doesn't, the problem is almost always the description. The Claude Code troubleshooting list for a skill that isn't triggering is short and worth following in order:

• Check the description includes keywords you'd naturally say.
• Ask "What skills are available?" and confirm it's listed.
• Rephrase your request closer to the description.
• If the YAML frontmatter is malformed, Claude Code still loads the body but with empty metadata, so /pr-description works while automatic matching can't. Run with --debug to see the parse error.

If it fires too often instead, make the description more specific, or add disable-model-invocation: true to the frontmatter so it only runs when you call it.

To check the file against the spec itself, the Agent Skills project provides a reference validator, skills-ref:

skills-ref validate ~/.claude/skills/pr-description

Before you install someone else's skill

Writing your own skills is the safe part. Installing other people's needs more care, because a skill is instructions plus, often, code your agent will run. Anthropic's Agent Skills overview puts it plainly: use skills only from trusted sources, and audit anything from an unknown source before use. Its checklist, in short:

• Read every file, not just SKILL.md: scripts, images, other resources.
• Look for things that don't match the stated purpose: unexpected network calls, unusual file access.
• Be wary of skills that fetch from external URLs, since fetched content can carry malicious instructions, and a trustworthy skill can change if its dependencies do.
• Remember skills can call tools. Know what your agent is allowed to run before a skill runs it.

Also note that the spec's allowed-tools field, which pre-approves tools for a skill, is marked experimental and support varies between agents. The foundation's proposed roadmap includes security guidance for people who write and install skills, so expect this area to get more formal.

Checklist

1. Pick a repeated task with conventions the model can't guess.
2. Name the folder and the skill identically: lowercase, hyphens, 64 characters max.
3. Write the description first: what it does, then when to use it, in the words you'd actually type.
4. Keep the body to steps, a template or example, edge cases and a few hard rules.
5. Test both ways: a natural request and the direct /name call.
6. If it doesn't trigger, fix the description before touching the body.
7. Audit every file of a third-party skill before installing it.

Where to go next

If you want all of this on a few pages you can keep open while you write, the free AI Agent Skills Quick-Start Cheat Sheet covers the format, a copy-and-adapt SKILL.md template, why most skills never trigger (with a checklist), and how to install and test skills across the major agents, in 6 pages.

When you're ready to go further, AI Agent Skills: The Complete SKILL.md Standard Guide spends 49 pages on the full specification, five build walkthroughs from markdown-only to Python to API-calling skills, ten production-ready templates, a chapter on skills security and a 30-day plan for building a personal skills library.

This article was written with the assistance of AI and reviewed by the author.