Teach your AI agent new skills — in one minute

Your first skill — turn a repeated request into one

A good first skill is something you have already explained to the AI three times or more: how to write commit messages, your test steps, your report format. Put that explanation in a SKILL.md once, and the agent finds and follows it every time.

1. Pick one job you keep explaining and give it a short name of lowercase letters, numbers and hyphens (commit-message).
2. Make a folder with that name in your agent's skills folder. npx skills init <name> makes the folder and a SKILL.md template.
3. At the top, fill in name (the same as the folder) and description. Below them, write the steps.
4. Start a new session and ask for that job in plain words. If the agent uses the skill, it works.

# in your project folder
mkdir -p .agents/skills && cd .agents/skills
npx skills init commit-message      # makes commit-message/SKILL.md

# Codex · Gemini CLI · Copilot CLI read   .agents/skills/commit-message/SKILL.md
# Claude Code reads                       .claude/skills/commit-message/SKILL.md

You can also ask the agent: "Turn what we just did into a skill." Claude Code and Codex know the format (Codex has a built-in $skill-creator).

The description — the only clue the agent has

At the start the agent reads only the name and description of every skill. From those few lines it decides which skill fits your request. A vague description means the skill is never used, or is used at the wrong time.

• Say what it does and when to use it — both, in one or two sentences.
• Write in the third person ("Writes commit messages …"), not "I can help you …".
• Include the words people really type: "commit message", "commit this", "staged changes".
• Rules: the description is up to 1,024 characters; the name is up to 64 lowercase letters, numbers and hyphens, the same as the folder name.

# ✗ too vague — the agent cannot tell when to use it
description: Helps with commits.

# ✓ what it does + when to use it + the words people really say
description: Writes a git commit message from the staged changes in the Conventional Commits style. Use when the user asks for a commit message, says "commit this", or wants to describe staged changes.

Claude Code shows at most 1,536 characters of a description in its skill list, so put the main use first.

The instructions — short, in order, with an example

Below the frontmatter is what the agent reads when it uses the skill. The agent is already smart, so write only what it does not know: your rules, your order of steps, your format.

• Leave out what the agent already knows (what git is, how to write Markdown).
• When order matters, number the steps, and say what to do when something goes wrong ("If nothing is staged, say so and stop").
• Show the result you want with one or two examples — an example says more than a description.
• Give one default instead of a list of choices ("Use pdfplumber; for scanned PDFs use OCR").
• Keep SKILL.md under 500 lines. When it grows, split it into files (the [Advanced] tab).

---
name: commit-message
description: Writes a git commit message from the staged changes in the Conventional Commits style. Use when the user asks for a commit message or says "commit this".
---

1. Run `git diff --staged`. If nothing is staged, say so and stop.
2. Pick one type: feat, fix, docs, refactor, test or chore.
3. Write a subject of 50 characters or less, then a blank line,
   then why the change was made in one or two short lines.

Example:
fix(cart): keep the coupon after a page reload

The coupon code was stored only in memory.

Calling a skill and checking it

A skill is used in two ways: the agent picks it by itself when your request matches the description, or you call it by name.

• Automatic: just ask in plain words ("write a commit message"). The agent reads the description and loads the skill.
• Claude Code: /skills shows the list and /<skill-name> calls one. Words after the name go into $ARGUMENTS.
• Codex: /skills shows the list, and $<skill-name> in your message calls one.
• Claude Code picks up edits to SKILL.md at once. If you made a new skills folder, run /reload-skills. In other tools, start a new session.

# Claude Code
/skills                 # list the skills it found
/commit-message         # call one yourself
/fix-issue 123          # "123" goes into $ARGUMENTS in SKILL.md

# Codex
/skills                 # list and pick
$commit-message         # mention one in your message

If the skill is not used when it should be, fix the description first — that is the cause most of the time.

Where to keep it — just for you, or for the team

The same skill can live in your home folder (for all your projects) or in the project (for everyone who works on it).

• Personal skills: ~/.claude/skills/ for Claude Code, ~/.agents/skills/ for Codex, Gemini CLI and Copilot CLI.
• Project skills: .claude/skills/ or .agents/skills/ in the project. Commit them and the whole team gets the same skill.
• If two skills have the same name, Claude Code uses the personal one before the project one.
• Never put passwords or API keys in a skill — its files are read and often shared.

# only me, every project
~/.claude/skills/commit-message/      # Claude Code
~/.agents/skills/commit-message/      # Codex · Gemini CLI · Copilot CLI

# this project — commit it and the whole team gets it
.claude/skills/commit-message/
.agents/skills/commit-message/

git add .agents/skills/commit-message
git commit -m "Add the commit-message skill"

Intermediate practice — make one in your project

1. Write down one request you have made to the AI three times or more.
2. Make that skill folder with npx skills init and write the name and description.
3. Write the steps in five lines or fewer, with one example of the result.
4. In a new session, ask for it in plain words and check that the skill is used. Then call it by name.
5. Ask for something unrelated and check that the skill is not used.

When all five work, move on to the [Advanced] tab.

Official documentation

• Agent Skills — Quickstart
• Agent Skills — Specification
• Claude Code — Skills
• Codex — Skills

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.

Split it into files — read only what is needed

The agent reads a skill in three steps: the name and description at the start, SKILL.md when it uses the skill, and other files only when needed. So big material goes into separate files, and SKILL.md becomes the map that says which file to read for which question.

• SKILL.md holds the overview and "for this, read that file".
• Link files only from SKILL.md, one level deep. Chains like file → file → file are often read only in part.
• Put a table of contents at the top of reference files longer than 100 lines.
• Name files by their content (finance.md, not doc2.md) and always write paths with / .

sql-report/
├── SKILL.md              ← the map: what to read for which question
├── references/
│   ├── finance.md        ← read only for revenue questions
│   └── sales.md          ← read only for sales questions
└── scripts/
    └── check_query.py    ← run it, do not read it

## Which file to read
- Revenue, billing → read [references/finance.md](references/finance.md)
- Deals, pipeline → read [references/sales.md](references/sales.md)

Scripts — put work that must be the same every time in code

A ready-made script is more reliable than code the agent writes each time, and when it runs, only its output enters the context, not the code. Put checks, conversions and other work that must be exact in scripts/.

• Say clearly whether to run it ("Run scripts/check_query.py") or to read it ("See scripts/check_query.py for the rules").
• Handle errors inside the script, and print messages that say what is wrong and what to do.
• Write down the packages and versions it needs, and put real requirements in compatibility.
• Build a loop: check → fix → check again, and go on only after the check passes.
• Explain fixed values with a comment (why a 30-second timeout?).

## Check the query before you run it

Run:
    python3 scripts/check_query.py query.sql

It prints OK, or one problem per line.
If it is not OK, fix the query and run the check again.
Run the query only after you see OK.

Which languages can run depends on the agent. Python, Bash and JavaScript are the common choices.

Frontmatter options — the standard and each tool's extras

Besides name and description, the standard has a few optional fields, and each tool adds its own. Tools ignore fields they do not know, so make the skill work with the standard fields first.

• Standard: license, compatibility (needed programs and network, up to 500 characters), metadata (author and so on), allowed-tools (pre-approved tools — experimental).
• Claude Code disable-model-invocation: true — only you can call it. Use it for jobs with side effects, such as deploying or sending messages.
• Claude Code user-invocable: false — only the AI uses it, and it is hidden from the / menu. context: fork runs the skill in a subagent.
• Claude Code !`command` — runs the command before the skill is read and puts the output in its place (for example !`git diff HEAD`).
• Codex: policy → allow_implicit_invocation: false in agents/openai.yaml — the skill is used only when you call $<skill-name>.

---
name: deploy
description: Deploys the app to staging or production. Use when the user says deploy, release or ship.
license: MIT
compatibility: Requires git, docker and network access
metadata:
  author: my-team
allowed-tools: Bash(git status) Bash(./scripts/deploy.sh *)
# Claude Code only — other tools ignore these
disable-model-invocation: true
argument-hint: "[staging|production]"
---

Current branch: !`git branch --show-current`

Deploy to $ARGUMENTS with `./scripts/deploy.sh $ARGUMENTS`.

Give allowed-tools only the commands the skill really needs. Wide permissions make a mistake more costly.

Testing — write the tests before you write a lot

You only know whether a skill works by trying it. First see what the agent gets wrong without the skill, then write just enough to fix that.

1. Give the agent the job without the skill and note what it gets wrong or misses.
2. Make at least three test requests for those gaps — including one where the skill must not be used.
3. Write only enough instructions to fill the gaps.
4. In a new session, try the same requests with and without the skill and compare.
5. Test with every model you will use — a small model may need more detail.

# checks the frontmatter and the naming rules
skills-ref validate ./commit-message

[
  {"query": "write a commit message for what I staged", "use_skill": true},
  {"query": "commit this, it fixes the login bug",      "use_skill": true},
  {"query": "explain what git rebase does",             "use_skill": false}
]

skills-ref is the reference tool in the agentskills repository (for demonstration) — clone it and install it with pip install -e . In Claude Code, /skill-doctor shows each skill's context cost and use.

Safety — read other people's skills like code

A skill is a set of instructions the agent follows, and its scripts run on your computer. A bad skill makes the agent follow bad instructions, so check before you install.

• Install only from places you trust. With -l you see the list without installing.
• Before you install, read SKILL.md and every file in scripts/.
• Watch for commands that send files or keys somewhere else, or that delete things.
• Do not put passwords or keys in a skill. Read them from environment variables.
• Claude Code: block a skill with a permission rule such as Skill(deploy *), and turn off !`command` with the disableSkillShellExecution setting.

# see what is inside before you install
npx skills add my-name/my-skills -l

# read the instructions and every script
cat .agents/skills/<name>/SKILL.md
ls .agents/skills/<name>/scripts/

Your own skills too: read the changes once more before you commit or share them.

Advanced practice — grow your skill

1. Move the long part of your intermediate skill into references/ and link it from SKILL.md.
2. Write one check in scripts/ and add the "check → fix → check again" steps to SKILL.md.
3. Run skills-ref validate on the skill folder and fix what it reports.
4. Make three test requests (one where the skill must not be used) and compare with and without the skill.
5. Read one skill made by someone else from start to end before you install it.

When you have done all five, move on to the [Master] tab.

Official documentation

• Skill authoring best practices
• Agent Skills — Specification
• skills-ref — GitHub
• Claude Code — Skills

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.

Share your skills — one GitHub repository

Put your skills in a public GitHub repository and anyone can install them with npx skills add <owner>/<repo>. One repository can hold many skills.

• Put each skill in its own folder under skills/. The installer finds them.
• Add a LICENSE and a README with what each skill does and the install command.
• Users can take one skill with -s and install it for all their projects with -g.
• When you fix a skill and push, users get it with npx skills update.

my-skills/                     # a public GitHub repository
├── README.md                  ← what each skill does + the install command
├── LICENSE
└── skills/
    ├── commit-message/SKILL.md
    └── sql-report/SKILL.md

# anyone can install it
npx skills add my-name/my-skills
npx skills add my-name/my-skills -s commit-message -g
npx skills update              # gets your new commits

Share from your own website — like SONUB

You can also share skills from your own website. SONUB does: npx skills add https://sonub.com reads the list at /.well-known/agent-skills/index.json and downloads each skill as an archive.

• The list has each skill's name, description and archive address, with the sha256 digest of the archive.
• When a digest changes, npx skills update downloads that skill again — only changed skills are updated.
• If name or description breaks the rules (a lowercase name the same as the folder, a description up to 1,024 characters), the installer silently skips the skill.
• SONUB builds the list and archives from the skill folders on each request, so a deployed fix is the new version.

# the list the installer reads
https://sonub.com/.well-known/agent-skills/index.json

# one archive per skill, with the sha256 digest of its bytes in the list
https://sonub.com/.well-known/agent-skills/gp.tar.gz

npx skills add https://sonub.com

• SONUB skills and the install command

One skill for every tool

Agent Skills is an open standard, so one folder works in Claude Code, Codex, Gemini CLI, GitHub Copilot and more. Only the folder each tool reads is different.

• Make it work with the standard fields (name, description) and plain instructions. Tool-only options are extras.
• Avoid words tied to one tool ("the Bash tool"). Write "run this in the terminal".
• Keep one real folder in .agents/skills/ and link it into .claude/skills/. npx skills add can do this for you (recommended), or make copies with --copy.
• In Claude Code you can also bundle skills with subagents, hooks and MCP into a plugin and share it through a marketplace.

# one real folder for every tool
.agents/skills/commit-message/

# a link so Claude Code finds the same folder
mkdir -p .claude/skills
ln -s ../../.agents/skills/commit-message .claude/skills/commit-message

If a skill uses MCP tools, write the full name with the server (ServerName:tool_name). Without it the agent may not find the tool.

• Claude Code master — plugins

Design — when a skill, and when something else

Agents learn in several ways. Use a skill where a skill fits, and the work gets simpler.

• Rules to follow in every conversation → AGENTS.md (or CLAUDE.md).
• A procedure or knowledge needed now and then → a skill.
• A big job handed off, with only the result coming back → a subagent.
• Connecting to outside services and data → MCP. A skill can teach how to use those tools.
• Something that must happen every time (formatting after each edit) → a hook.

One skill, one job. When a skill does too much, split it.

• Claude Code advanced — skills, subagents, hooks, MCP
• Codex advanced — config, MCP, skills, hooks

Look after your skills — improve them as you use them

A skill gets better from watching it work, not from guessing. Use it on real tasks and fix it where the agent struggles.

• Watch how the agent uses it: files it never reads, files it reads again and again, rules it misses.
• Improve the skill in one AI session and test it in a new one — the fresh session shows what is missing.
• Instead of dates ("before August …"), write the current way and fold the old way into an "Old way" section.
• Delete skills nobody uses — every description takes up context in every session.
• Ask your team: Did it start when expected? Were the instructions clear? What was missing?

Master checklist

• The description says what it does, when to use it, and the words people really use
• SKILL.md is under 500 lines, and other files are linked one level deep
• Scripts handle their own errors, and it is clear whether to run or read them
• At least three tests, including one where the skill must not be used
• No secrets inside, and other people's skills are read before they are installed
• Checked in the agents and models you will use, and shared with an install command

When every box is checked, publish one of your skills on GitHub and share it with npx skills add.

Official documentation

• skills CLI (npx skills) — GitHub
• Agent Skills
• Claude Code — Plugins
• Skill authoring best practices

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.