Making Your Own Skill

Snapshot caveat: The SKILL format is stable, but the exact field limits, the plan names, and where skills live keep evolving. Reflects June 2026. Re-verify the volatile specifics on the official Anthropic Skills docs and agents.md.

01. What It Is

A skill is a folder with one plain-text file inside it, called SKILL, that teaches an AI assistant how to do one repeatable task your way. Anthropic, which introduced Skills, describes them as "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks," and the comparison it returns to is an onboarding guide for a new hire. The assistant already knows how to work. The skill hands it your procedure for one job.

The honest entry bar for a non-coder is small. You do not write code, but you do need to be comfortable creating a folder, editing a plain-text file, and saving it (and on claude.ai, zipping the folder). A built-in helper called skill-creator can even do that part for you.
For the concept behind skills, see the agent-skills concept companion. This page is the hands-on how-to.

02. Why It Matters

Most people re-explain the same task to an assistant over and over. A skill saves that work once. You write the procedure down in plain language, and the assistant follows it whenever your request matches.
It is reusable, saved prompting, a step up from everyday-prompting-cookbook, and it is what equips the multi-step assistants in agents-and-agentic-workflows.

The mechanism that makes this scale also shapes how you write the file. At startup the assistant loads only the name and description of each installed skill, roughly 100 tokens apiece, and reads the body only if your request matches a description. Picture it skimming a table of contents and opening only the chapter whose title fits. A vague title is a chapter that never gets opened. Skills are also an open standard, so a skill you write for Claude can travel to other tools that read the same SKILL, such as Cursor and Goose. Write it once and it travels.

03. How It Works

The anatomy of a SKILL.md

A SKILL file has two required parts and one optional one. The smallest valid skill looks like the block below.

---
name: your-skill-name
description: What the skill does and when to use it.
---

# Your skill name

Plain-language instructions the assistant follows when this skill runs.

The block fenced by the two --- lines is the frontmatter, the header that carries the skill's metadata. Two fields are required. name is a short label in lowercase letters, numbers, and hyphens, up to 64 characters, and it cannot contain the words "anthropic" or "claude." description is a sentence or two, up to 1024 characters on the Claude platform, saying what the skill does and when to use it. Everything below the frontmatter is the body, plain Markdown you write the way you would brief a fast new colleague who does not yet know your preferences. The optional third part is bundled files, scripts or templates beside SKILL that open only when the task needs them. Most non-coder skills never use one.

Why the description is the most important line

The description does the most work, because it is how the assistant decides whether to use the skill at all. Anthropic's guidance is blunt that it is "critical for skill selection" and that Claude "uses it to choose the right Skill from potentially 100+ available Skills." Say two things in plain third person, what the skill does and when to use it. A strong example is "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction." A weak one is "Helps with documents." The first names concrete triggers, the words a user would type. The second names nothing, so the assistant never connects a real request to it. Write in third person ("Processes Excel files"), never "I can help you," because the text goes straight into the system prompt where mixed points of view hurt matching. And lean a little forward with trigger words, because assistants tend to under-trigger skills.

Where skills live and who can use them

Where you put the skill decides who can use it.

On claude.ai a custom skill is individual to you, uploaded as a ZIP whose root is the skill folder. In Claude Code a personal skill follows you everywhere, and a project skill lives in the repository so a team shares it. The two surfaces do not sync, so manage each separately. When names collide, enterprise overrides personal overrides project.

Slash commands, the simpler cousin

A slash command is the simplest version of the same idea, a saved instruction you trigger by typing /name. In Claude Code the two have merged, "custom commands have been merged into skills," so deploy and SKILL both create /deploy and run the same way. A skill adds what a bare command lacks, a folder for supporting files and a description that lets it trigger itself. You can always force any skill by typing /skill-name.
Both live inside coding tools like those in ai-coding-assistants.

The Codex equivalent, AGENTS.md

OpenAI's Codex has a close parallel called AGENTS, a plain-Markdown file at a project's root with no required format, "just standard Markdown. Use any headings you like." You put in anything you would tell a new teammate, like build and test commands or code conventions. Codex reads it automatically every session, from the repository root down to your working folder, and the file nearest the work wins. The clean contrast is a picture. AGENTS is the house rules taped to the wall that the agent reads every time. A skill is a tool the agent picks up only when the task calls for it. They stack, and as of 2026 Codex supports both on the same open standard.

04. A Simple Worked Example

Here is a complete, no-code skill you can make in minutes. It rewrites rough notes into a plain, direct voice. Create a folder named writing-voice, and inside it a SKILL file with this text.

---
name: writing-voice
description: Rewrites rough notes or drafts in the user's personal writing voice: plain, direct, no jargon, short sentences. Use whenever the user asks to rewrite, polish, clean up, or "put this in my voice," or pastes notes they want turned into finished writing.
---

# Writing voice

Rewrite the provided text in this voice:
- Plain and direct. Cut filler and hype words.
- Short sentences. One idea per sentence.
- No jargon unless the reader would already know it.
- Keep the original meaning and facts. Do not invent details.

## Example
Input: "We are thrilled to announce the launch of our innovative new solution."
Output: "Our new tool is live."

To use it on claude.ai, zip the writing-voice folder and upload it in Settings under Features with code execution on. In Claude Code, save it at ~/.claude/skills/writing-voice/SKILL.md. Then ask "rewrite this in my voice" and let the description trigger it, or type /writing-voice to run it directly. The description names the exact phrases a user would type, and that is what lets the assistant find it.

05. Tips for a Good Skill

A few habits separate a skill that fires from one that sits unused.

• Make the description discoverable. The make-or-break step. Name what the skill does and the real words and situations that should trigger it, in third person.
• Keep the body concise. Assume the assistant is smart and cut what it does not need. Anthropic keeps bodies under 500 lines and calls the context window "a public good."
• Use progressive disclosure. Push long reference material into a separate file the assistant opens only when it needs it.
• Start prompt-only, add a script only for reliability. Plain instructions suit guidance tasks. Add code only when you need the exact same result every time, like sorting or filling a form. OpenAI's Codex guidance agrees, "prefer instructions over scripts unless you need deterministic behavior or external tooling."
• Test on real tasks and iterate. Run the job, watch where it struggles, and sharpen the file. Anthropic suggests about three realistic test scenarios first, then the minimum instructions to pass them. The skill-creator skill will interview you and build the folder, so "no manual file editing required."

06. Key Terms

07. Common Misconceptions

"Making a skill means writing code."
Most useful skills are pure writing, a name, a description, and plain-English instructions in one text file. You add code only when you need the exact same result every time, like filling a form.

"The instructions matter most, the description is just a label."
It is the reverse. The assistant pre-loads only names and descriptions, and reads the body later only if the description matched. A weak description means a strong body never gets opened.

"More detail makes a skill better."
Shorter usually wins. Assume the model is smart, cut what it does not need, keep the body under 500 lines, and move long reference material into separate files.

"A skill is like a custom GPT or an app from a store."
It is closer to an onboarding note, a folder of instructions you write in an open format. On claude.ai you upload it as a ZIP, and in Claude Code you drop the folder in place.

"Once I write it, the assistant will always use it."
Assistants tend to under-trigger skills. One fires only when the task is substantial and the description clearly matches, so test on real prompts and sharpen the wording. You can force it by typing /skill-name.

"Skills, AGENTS.md, and MCP are rival standards I must pick between."
They solve different problems and they stack. A skill teaches one on-demand task, now on Claude and Codex. AGENTS is always-on project context.
MCP connects an assistant to outside tools and data, see mcp. Codex reads both.