How to Create Your Own AI Agent Skill (Step by Step)

Installing other people's skills is useful. Writing your own is where skills really pay off, because nobody else knows your project's rules, your checklist or the mistakes you keep fixing by hand.

A skill is just a folder with a SKILL.md file, so you can write one in ten minutes. This guide walks through when a skill is worth it, how to write one the agent will actually use, a complete example, and how to apply it in Claude Code, Codex and Cursor.

When a skill is worth writing

Write a skill when you notice you've given the agent the same instructions three times. Good candidates:

• A checklist you run before finishing something (publishing, releasing, opening a pull request).
• A process with steps in a fixed order (setting up a new page, creating a component, writing a migration).
• Knowledge the agent doesn't have: your team's conventions, an internal tool, a framework's quirks.

If the information is true for every task in the project, like "we use TypeScript and pnpm", it belongs in a rules file (CLAUDE.md or AGENTS.md) instead. Skills are for how to do one kind of task.

The anatomy of a skill

article-checklist/
├── SKILL.md          the instructions (required)
├── reference.md      longer details, read only when needed (optional)
└── scripts/
    └── check.sh      something the agent can run (optional)

SKILL.md starts with a header between --- lines. Two fields matter most:

• name: the skill's name, in lowercase with dashes. It's what you type to call it.
• description: what the skill does and when to use it. The agent reads only this until it decides the skill is relevant, so it's the most important line you'll write.

Claude Code treats both as optional and falls back to the folder name, but Codex expects them, so always include both if you want the skill to work everywhere.

Step 1: write a description that triggers

The agent picks a skill by matching your request against its description. Write it with the words you actually use when you ask:

# ❌ Too vague: the agent can't tell when to use it
description: Helps with articles.

# ✅ Says what it does and when, with the words you'd use
description: Review a blog article before publishing. Use when the user asks to check, review, finish or publish an article, or before marking an article as done.

Step 2: write instructions the agent can follow

Write the body like a checklist for a capable new teammate:

• Use numbered steps when the order matters.
• Be specific and checkable. "Title under 60 characters" beats "a good title".
• Say what to do when something fails. "If the build fails, fix the error and run it again."
• Keep it short. Move long material into a separate file and link to it. Claude Code recommends keeping SKILL.md under 500 lines.

A complete example

---
name: article-checklist
description: Review a blog article before publishing. Use when the user asks to check, review, finish or publish an article, or before marking an article as done.
---

# Article checklist

Run these checks on the article, fix what you can, and report what's left.

1. The `title` is 60 characters or fewer and starts with the main keyword.
2. The `description` is 140 to 160 characters and promises a concrete result.
3. There are 2 to 4 links to related articles on this site, and they all exist.
4. Every command and code block has a language and has been run or checked.
5. There is a FAQ section with 3 to 5 real questions.
6. The build passes: run `npm run build` and fix any error before continuing.

When you finish, list each check as passed or fixed, and anything that needs the author.

Step 3: put it where your agent looks

Save the folder in the project so it travels with the repository:

Cursor also reads the Claude Code and Codex folders, so if your team uses several tools, keeping the skill in .agents/skills/ covers Codex and Cursor in one place. For skills only you need, use your personal folder instead; how to install skills lists them for each tool.

Step 4: test it and improve the description

1. Call it by name to check that the instructions work: /article-checklist in Claude Code, $article-checklist in Codex.
2. Ask naturally without naming it, for example "can you check this article before I publish it?", and see whether the agent picks the skill on its own.
3. If it doesn't, add the words you used to the description and try again.
4. When the agent does something wrong, fix the instruction, not the result. Every fix to the skill improves all future runs.

Sharing a skill

• With your team: commit the folder to the repository.
• With everyone: publish the folder on GitHub so people can install it, or bundle several skills into a Claude Code plugin with a marketplace so they install in one command.

FAQ

What's the difference between a skill and a CLAUDE.md or AGENTS.md file?

Rules files load in every session and should hold facts about the project. Skills load only when a task needs them and hold instructions for that task. Long, task-specific instructions in a rules file cost context in every conversation; in a skill they cost nothing until they're used.

Can a skill run code?

Yes. Put scripts in the skill folder and tell the agent when to run them. The agent still runs them through its normal permissions, so you stay in control of what executes.

Can I stop the agent from using a skill automatically?

In Claude Code, add disable-model-invocation: true to the header and the skill runs only when you call it with /skill-name. That's useful for skills with side effects, like deploying.

How long should a skill be?

As short as it can be while still being complete. Most good skills fit on one screen. If yours keeps growing, split the reference material into separate files that the skill links to.

Further reading

• Previous: How to install skills in Claude Code, Codex and Cursor
• Start of the series: What are AI agent skills?
• Related: How to write a good README
• Claude Code skills documentation