How to write an Agent Skill

Who this is for

This guide is for anyone who runs the same kind of task with an AI agent again and again and wants to package the instructions once. You should know a little Markdown and be able to create a folder. By the end you should be able to write a valid SKILL.md, place it where Claude Code finds it and check it with the reference validator.

What a skill is

Skills are folders of instructions, scripts and resources that Claude loads dynamically to improve its performance on specialised tasks ^[2]. A skill does not run by itself. It gives the agent a recipe for one job, and the agent decides when the recipe applies.

The Agent Skills format is open. The quick start says the same skill works in any compatible agent, including Claude Code and OpenAI Codex ^[10].

Anatomy of a skill

Every skill has a SKILL.md file. It must start with YAML frontmatter and continue with Markdown content ^[3]. The repository's template/SKILL.md gives this minimal template ^[4]:

---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---

# Insert instructions below

Beyond the one required file, a skill directory may contain three optional folders ^[3]. scripts/ holds executable code, references/ holds documentation such as REFERENCE.md, FORMS.md or a domain file like finance.md, and assets/ holds static resources such as document templates, images and data files ^[3]. Scripts should be self-contained or document their dependencies, give helpful error messages and handle edge cases gracefully ^[3].

Keep the main SKILL.md under 500 lines. Move detailed reference material into separate files, and keep those references one level deep from SKILL.md, using paths relative to the skill root ^[3].

Frontmatter rules

The specification defines six fields. name and description are required. license, compatibility, metadata and allowed-tools are optional ^[3].

• **name** must be 1 to 64 characters. It may contain only unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens. It must not start or end with a hyphen, must not contain two hyphens in a row, and must match the name of the parent directory ^[3].
• **description** must be 1 to 1024 characters. It should say both what the skill does and when to use it, and it should include specific keywords that help an agent recognise a relevant task ^[3].
• **license names the licence, or the bundled licence file. compatibility**, if given, must be 1 to 500 characters ^[3].
• **metadata is a map from string keys to string values. allowed-tools** is a space-separated list of pre-approved tools, marked as experimental ^[3].

Claude Code follows the open standard and adds more fields, such as argument-hint, disable-model-invocation, user-invocable, model, effort, context, agent, hooks, paths and when_to_use ^[5]. Two of them are worth knowing early. disable-model-invocation: true stops Claude from loading the skill automatically, and user-invocable: false hides it from the / menu so that only Claude can invoke it ^[5].

A caution: if you upload a skill to claude.ai, or use the Skills API or package_skill.py from anthropics/skills, only the six standard fields are allowed. Any other field causes a hard error ^[5].

How agents load a skill

Agents load skills in three stages, called discovery, activation and execution ^[6]. At startup an agent loads only each skill's name and description. The full SKILL.md body is loaded when the skill is activated, and files in scripts/, references/ or assets/ are loaded only as they are needed ^[3].

This is why the description matters so much. Claude loads the frontmatter at startup, and the description is what a request is matched against ^[7]. In Claude Code the combined description and when_to_use text is cut off at 1,536 characters in the skill listing ^[5].

Where to put it

In Claude Code, a personal skill lives at ~/.claude/skills/<skill-name>/SKILL.md, and a project skill lives at .claude/skills/<skill-name>/SKILL.md. A project skill can be committed, so the team gets it too ^[5]. Nested <subdir>/.claude/skills/<skill-name>/SKILL.md folders, and skills in a directory passed with --add-dir, are also loaded ^[5]. A skill inside a plugin is invoked as /plugin-name:skill-name. For example, skills/review/SKILL.md in a plugin named my-plugin runs as /my-plugin:review ^[8].

The specification does not say where skill directories must live. It only defines what goes inside them ^[9]. A common convention for sharing across clients is <project>/.agents/skills/ and ~/.agents/skills/, and some implementations also scan .claude/skills/ for compatibility ^[9].

To try the public examples in Claude Code, run /plugin marketplace add anthropics/skills, then install one of the bundles with /plugin install document-skills@anthropic-agent-skills or /plugin install example-skills@anthropic-agent-skills ^[2]. The repository includes document skills for docx, pdf, pptx and xlsx ^[2].

With the Claude Agent SDK, skills are SKILL.md files in their own directories, and the SDK loads them from locations controlled by settingSources in TypeScript or setting_sources in Python ^[11].

Validate before you rely on it

The specification recommends the skills-ref reference library to check a skill. The command is skills-ref validate ./my-skill ^[3]. Run it after every change to the frontmatter, because a name that does not match its folder is an easy mistake to miss.

Our practice

TellWorld's news update is a skill. It lives at .claude/skills/news-update/SKILL.md in the project repository, and it is triggered by /news-update, or by asking in plain words to update the news ^[1]. Its description names the trigger phrases in Chinese, such as asking to update or pull the news, so that the agent can match an ordinary request to it ^[1].

We wrote the skill as seven numbered steps. They set the time window and batch name; split the searching across three Haiku sub-agents; run intake and fact checks; write, import and add illustrations; update the pinned list; deploy and keep records; and finish with a short report ^[1].

The time window runs from an until timestamp stored in content/tasks/news-state.json to the current time ^[1]. The skill updates that state file only after a successful import and deployment. A failed run therefore starts again from the old timestamp next time ^[1]. If the window is shorter than one day, the skill asks the user before it continues. If the window is longer than 45 days, the skill warns that small news may be missed ^[1].

The skill also contains the full prompt template for each sub-agent. It covers the sub-agent's scope, a deduplication rule against a list of existing keys, the name of the output file, and an instruction to do nothing else ^[1].

A later edit replaced an external writing model with Claude sub-agents, and an external image API with Codex image generation. The change touched about 30 lines across SKILL.md and CLAUDE.md ^[1].

Limits and common questions

• Agents may not pick the skill. If the skill does not trigger, the description is the first thing to check. Add the words users actually type, and make sure the description says when to use the skill ^[3].
• Upload rules are stricter than the spec. A skill that works in Claude Code may fail a claude.ai upload if it has extra frontmatter fields ^[5].
• Long skills cost context. Move reference material into references/ so that it loads only when needed ^[3].
• Pre-built skills exist for some formats. Anthropic's pre-built Agent Skills cover PowerPoint, Excel, Word and PDF on claude.ai, the Claude API, Claude Platform on AWS and Microsoft Foundry. Custom skills can be created in Claude Code, uploaded through the Claude API, or added in claude.ai settings ^[7].

Next steps

Read the specification for the exact field rules ^[3], then the Claude Code skills page for the extra fields and invocation controls ^[5]. The anthropics/skills repository has examples and the template ^[2][4]. The quick start shows the first steps in a compatible agent ^[10]. The Claude Agent SDK page explains how to load skills in code ^[11].