Free skills made by SONUB for Claude Code, Codex, Gemini CLI, GitHub Copilot CLI and other AI agents. Install them with one command, then just ask in plain words.
Basics — what skills are and how to install them
New to skills? Start here. Learn what an is and how it works, then install one with a single command and try it. When you are done, move on to the [Intermediate] tab above to make your own.
Learn about agent skills
An is a folder with a SKILL.md file that teaches an agent how to do one kind of task: the steps, the rules and the checks, and optionally scripts and reference files. Claude Code, Codex and other agents support the open Agent Skills format.
The top of SKILL.md holds a name and a description. The agent reads only these at first, and loads the full instructions when a request matches the description. That keeps many skills available without filling up the conversation.
Understand it the easy way
Think of it like this
A skill is like a binder of instructions on a shelf. The agent first reads only the covers — the name and a one-line description of every binder. When your request matches a cover, it takes that binder down and follows the steps inside. That is why many skills do not crowd the conversation.
Example
A “roll-dice” skill: a folder with SKILL.md whose cover says “Roll dice when the user asks for a random number”, and inside, the steps and a small script. Ask “Roll two dice for me” and the agent opens that binder.
Common mistake
A vague description like “useful helper”. The agent decides from the cover alone, so say exactly when the skill should be used.
The agent reads only the covers (name and description), then opens the one binder that matches the request.
What is an agent skill?
Agent Skills are a lightweight, open format for giving an AI agent new abilities and expert knowledge. One skill is one folder with a SKILL.md file in it. SKILL.md holds a name and a description, plus instructions that tell the agent how to do one kind of task. You can also put scripts, reference documents, templates and other files in the folder.
Agents keep getting smarter, but to do real work reliably they need your company's, your team's and your own way of doing things. A skill packs that know-how into a folder the agent loads only when it needs it. It turns expert knowledge into something reusable, and a task with many steps into the same procedure every time.
Anthropic first created the format and released it as an open standard. Today anyone can join in and help it grow (agentskills.io).
Where it helps — things a team repeats, such as steps, review rules and document formats. The way of working stays even when people change.
Learn it once, use it in many AI tools
Agent Skills are not a feature of one company; they are an open standard. So once you learn how to make a skill, you can use it everywhere. The same SKILL.md folder works in Claude Code and Codex, and in the many AI tools that support the format.
Installing is the same everywhere too: put the skill folder in the folder where the tool looks for skills. Only that location differs a little from tool to tool, as the box below shows.
Claude Code
Claude
ChatGPT & Codex
Gemini CLI
GitHub Copilot
VS Code
Cursor
OpenCode
Goose
Kiro
Junie
Roo Code
Amp
OpenHands
Factory
Laravel Boost
Some of the tools listed on agentskills.io (checked 2026-10-16). The list keeps growing.
# where each tool looks for skills all projects this project
Claude Code ~/.claude/skills .claude/skills
Codex · Gemini CLI · Copilot CLI ~/.agents/skills .agents/skills
VS Code (GitHub Copilot) .agents/skills
# put the whole skill folder there: .agents/skills/roll-dice/SKILL.md
How it works: three steps, reading only what is needed
An agent reads skills by progressive disclosure: a little at first, more only when a task calls for it.
Discovery: at startup the agent reads only the name and description of every skill, about 100 tokens each, so installing many skills keeps it light.
Activation: when a request matches a skill's description, the agent reads that skill's whole SKILL.md body. Keep the body under about 5,000 tokens and 500 lines.
Execution: the agent follows the instructions, running code in scripts/ or reading documents in references/ only when needed.
The folder and the rules of SKILL.md
The only file a skill must have is SKILL.md. It starts with a YAML header between two --- lines, followed by the instructions in Markdown.
name (required): at most 64 characters, only lowercase letters, numbers and hyphens. It must not start or end with a hyphen or have two hyphens in a row, and it must match the folder name.
description (required): at most 1,024 characters. Say what the skill does and when to use it, with the words people really say. The agent reads this to decide whether to use the skill.
license, compatibility, metadata, allowed-tools (optional): the license, the environment it needs (at most 500 characters), extra details such as author and version, and tools approved in advance (experimental). Most skills need none of them.
scripts/, references/, assets/ (optional): code to run, documents to read when needed, and templates, images or data. Point to files with paths relative to the skill folder, and link them only one level deep from SKILL.md.
my-skill/ # folder name = the skill's name
├── SKILL.md # required: name + description + instructions
├── scripts/ # optional: code the agent can run
├── references/ # optional: documents read only when needed
└── assets/ # optional: templates, images, data
Make one: a single file in five minutes
The simplest skill is just one SKILL.md file. Let's make the dice-rolling skill from the agentskills.io quickstart.
Make the folder: in your project, create .agents/skills/roll-dice/ (for Claude Code, .claude/skills/roll-dice/). The folder name is the skill name.
Write SKILL.md as in the box below: a name, a description, and a few lines saying what to do.
Check it: open the agent again and type /skills to see that roll-dice is in the list.
Test it: ask "Roll a d20" and see the skill turn on; then ask something unrelated and see that it stays off. If it does not turn on, improve the description.
---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---
To roll a die, use the following command that generates a random number from 1
to the given number of sides:
```bash
echo $((RANDOM % <sides> + 1))
```
Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
die, 20 for a d20).
Tips for good skills
The description matters most: say what it does, when to use it and what it is not for. A vague one such as "Helps with PDFs" is rarely used.
Keep one kind of task per skill. Fill the body with short steps, examples of input and output, and common exceptions.
Move long explanations to references/ and repeated commands or calculations to scripts/. Scripts should state what they need and give clear error messages.
Check the header rules with skills-ref validate ./my-skill, keep the skill in git, and share it with your team.
Skills made by others can run scripts, so read a skill before you install it.
Before you use one — read the instructions and scripts of a skill someone else made, and test it on a small task you can undo. The Agent Skills website only defines the format; it does not promise a skill is safe.
A closer look
The description decides when a skill is used, so write it with the words people really say and state what it is not for. Keep the instructions short and concrete, move long details into separate reference files, and test the skill with requests that should and should not use it. Skills can run scripts, so install skills only from sources you trust, and read them first. SONUB itself is built with several skills — one of them writes the beginner pop-ups for terms you see on this site.
Install with one command
Run this in a terminal inside your project folder. It reads the skill list from sonub.com, asks which skills and which agents you want, and copies the skill folders where each agent looks for them.
npx skills add https://sonub.com
Needs Node.js 18 or later (it comes with npx). Start a new session of your agent afterwards so it reads the new skills.
No need to know the command — just ask the AI to install it
To install a skill, simply ask the AI to install the skill you want. AI is smart: tell it where the skill is — for example, “Install the gp skill from https://sonub.com” — and it installs it for you. Even if you don’t know the install command, the AI installs the skill and uses it. Copy the sentence below and send it to your agent.
Install the SONUB skills: run npx skills add https://sonub.com -y, then tell me which skills were installed and what I can say to start using them.
But if you only give orders to the AI while knowing nothing at all, in the end it is the AI that did the work, not you.
That is why you should learn about AI first: then you can give the AI better instructions, and when the AI gets something wrong, you can analyze what it did, find what went wrong and ask again.
Useful options
For every project on this computer (without it, only this project)
npx skills add https://sonub.com -g
Only one skill
npx skills add https://sonub.com -s gp
Only for one agent
npx skills add https://sonub.com -a claude-code
Just list the skills, install nothing
npx skills add https://sonub.com -l
No questions — all skills for the agents found on this computer
npx skills add https://sonub.com -y
Update and remove
Get the newest version of every skill installed from here
npx skills update
Remove a skill
npx skills remove gp
The skills
Each skill is a standard folder with a SKILL.md — the instructions an agent reads — plus a small tool. Nothing to sign up for, MIT license.
gp
All your work on a GitHub Project board
Talk to your agent in plain words and it manages your GitHub Project board with the gh CLI — then reads the result back to confirm.
Issues: create, edit, move between columns, close, reopen, comment
gp is a made by SONUB that keeps all your work on a Project board. Ask for these things in plain words, and the does them with the GitHub (gh) and reads the result back to confirm:
create, edit or close issues, and attach images
keep TODO checklists
add or rename kanban columns
assign people
Its folder has exactly the parts described above: SKILL.md, a script that does the work (scripts/gp.py) and reference files that are read only when needed.
Get ready: create a free GitHub account at github.com/signup and install gh. The agent can help you log in with gh auth login.
Install: type the line below in a terminal (it needs Node.js). It puts gp into the agents on your computer — Claude Code, Codex, Gemini CLI and more.
First time: say "Set up gp". The agent checks everything with the gp doctor command, then picks one of your boards or creates a new one.
Use it in your own words: "Make an issue: the login button does nothing, attach this screenshot", "Move it to Done", "Add a Review column", "What's on my plate?"
# 1) install the gp skill — Claude Code, Codex, Gemini CLI, Copilot CLI ...
npx skills add https://sonub.com -s gp -g
# -g: for every project (leave it out for this project only)
# 2) once: log in to GitHub with the board permissions
gh auth login
gh auth refresh -s project,repo
# 3) then just ask the agent:
# "Set up gp and show my GitHub projects."
# "Make an issue: the login button does nothing. Attach shot.png. TODO: reproduce, fix, test."
# "Move it to In Progress." "Add a Review column." "Done!" "What's on my plate?"
Needs a free GitHub account, the gh CLI and Python 3.8+.
Claude Code ships a new version almost every day. This skill teaches it in order, answers from the current official docs, checks your setup and summarizes every new feature.
14 lessons with an exercise in your own project and check questions
Quizzes, with your progress saved
Answers checked against the official docs, with the link
Every new CHANGELOG feature, summarized by topic
A setup doctor for settings, CLAUDE.md, skills, plugins and MCP
/claude-skill update pulls newly released features into the skill
Try saying
“Next lesson”
“How do I run prettier after every edit with a hook?”
“Check my setup”
“Give me a quiz”
Needs Python 3.8+ and internet access (it reads the official docs).
Hover a technical word on any page or document of your project — or tap it on a phone — and a small card explains it: meaning, plain words, examples, source code and a “learn more” link.
One glossary JSON is the source of every explanation, in every language you ship
A drop-in popup.js and popup.css — no framework, no build step
Finds terms in plain text by itself; phrases, “?” buttons and link previews by hand
Keyboard, phones (bottom sheet), right-to-left languages and dark mode
An audit that finds jargon in your docs with no explanation yet
For READMEs on GitHub: a GLOSSARY.md and links that show the meaning on hover
Try saying
“Add glossary popups to the getting-started page”
“Explain token, sampling and temperature on hover”
“Make the README beginner-friendly”
“Which words in the docs still need an explanation?”
Needs Python 3.8+ for the tool. The popups run in any modern browser.
A folder with a SKILL.md file that tells an AI agent when and how to do a task, plus the scripts and notes it needs. It is an open standard (agentskills.io), so the same folder works in many agents.
Every project or this project only?
Without -g the skill goes into the project you are in (for example .claude/skills/ and .agents/skills/), and you can commit it so your team gets it too. With -g it is installed once in your home folder for every project.
Which agents does it work with?
Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Cursor and the other agents the skills tool knows. It asks which agents to install for, or use -a to name one.
Is it free? Where does my data go?
Free and MIT-licensed. The skills run on your computer with your own tools: gp talks only to GitHub through your gh login, claude-skill reads the public Claude Code docs, popup works on your files. sonub.com only hands out the skill files.
It doesn’t show up after installing. What now?
Start a new session of your agent — it reads the skill folders when it starts. In Claude Code you can also type the skill name with a slash, for example /gp.
Turn a request you keep repeating into a . Make the folder, write a description the can find, write short step-by-step instructions, call it and check it, then decide where it lives — just for you or for the whole team.
Your first skill — turn a repeated request into one
A good first skill is something you have already explained to the three times or more: how to write messages, your test steps, your report format. Put that explanation in a SKILL.md once, and the agent finds and follows it every time.
Pick one job you keep explaining and give it a short name of lowercase letters, numbers and hyphens (commit-message).
Make a folder with that name in your agent's skills folder. npx skills init <name> makes the folder and a SKILL.md template.
At the top, fill in name (the same as the folder) and description. Below them, write the steps.
Start a new session and ask for that job in plain words. If the agent uses the skill, it works.
Terminal
# 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.
SKILL.md
# ✗ 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).
.agents/skills/commit-message/SKILL.md
---
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 · Codex
# 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.
Where
# 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
Write down one request you have made to the AI three times or more.
Make that skill folder with npx skills init and write the name and description.
Write the steps in five lines or fewer, with one example of the result.
In a new session, ask for it in plain words and check that the skill is used. Then call it by name.
Ask for something unrelated and check that the skill is not used.
When all five work, move on to the [Advanced] tab.
Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.
Advanced — bigger skills: files, scripts, options, tests and safety
When one SKILL.md is not enough: split it into files the reads only when needed, hand fixed jobs to scripts, use frontmatter options, test the before you trust it, and check other people's skills before you install them.
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/
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
SKILL.md
## 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 the agent writes each time, and when it runs, only its output enters the , 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?).
SKILL.md
## 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>.
.claude/skills/deploy/SKILL.md
---
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.
Give the agent the job without the skill and note what it gets wrong or misses.
Make at least three test requests for those gaps — including one where the skill must not be used.
Write only enough instructions to fill the gaps.
In a new session, try the same requests with and without the skill and compare.
Test with every model you will use — a small model may need more detail.
Terminal
# checks the frontmatter and the naming rules
skills-ref validate ./commit-message
evals.json (your own format)
[
{"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.
Terminal
# 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
Move the long part of your intermediate skill into references/ and link it from SKILL.md.
Write one check in scripts/ and add the "check → fix → check again" steps to SKILL.md.
Run skills-ref validate on the skill folder and fix what it reports.
Make three test requests (one where the skill must not be used) and compare with and without the skill.
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.
Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.
Master — share, work across tools, design and look after skills
Share your skills so anyone can install them with one command, make one work in every , decide when a skill is the right tool, and keep your skills good as you use them.
Share your skills — one GitHub repository
Put your skills in a public 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/
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 ://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.
sonub.com
# 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
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.
Terminal
# 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.
