Free SONUB skills for , and other . Install them with one command and ask in plain words, then make your own in the next tabs.
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 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. , and other agents support the open 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, 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.
first created the format and released it as an . 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
& Codex
Factory
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 : 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 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 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 header between two --- lines, followed by the instructions in .
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.
, compatibility, , (optional): the license, the environment it needs (at most 500 characters), extra details such as author and , 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 . 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).
Make a habit of building your own skills
For the things you know well, it is very important to build the habit of making your own skills and using them. Nobody knows your way of working, your standards and your tricks better than you. Put them in a skill, and the AI works your way every time — your knowledge becomes a tool you can use again and again.
You do not have to write it perfectly from the start. Follow the basic skill format (one folder with a SKILL.md), write down your idea, and rules in a few short lines, and ask the AI to update it. Shaping the format and filling in missing steps is something the AI does well.
Make the frame: create the skill folder and SKILL.md in the basic format, and write the name and description at the top.
Write it briefly: in the body, write the idea (what the skill does), the logic (in what order) and the rules (what to always do and never do) in a few lines (box below).
Ask for an update: tell the AI "Polish this skill to the standard skill format. Keep my idea, logic and rules, and fill in the missing steps, examples and how to check the result." Then read what it changed and check that it matches what you meant.
---
name: weekly-report
description: Writes my team's weekly report. Use when asked for a weekly report or "this week's summary".
---
Idea: turn this week's commits and issues into a one-page report.
Logic: read the last 7 days of git log → group by feature → write the report.
Rules: plain words, 10 bullets at most, never include passwords or customer names.
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 , and common exceptions.
Move long explanations to references/ and repeated commands or calculations to scripts/. Scripts should state what they need and give clear .
Check the header rules with validate ./my-skill, keep the skill in , 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 inside your project folder. It reads the list from sonub.com, asks which skills and which you want, and copies the skill folders where each agent looks for them.
npx skills add https://sonub.com
This is a practice Linux running inside your browser (home folder /home/you), so nothing is installed on your own computer. Press Enter to run the command. What you do stays in this browser, even if you close the drawer, reload or come back later; press Start fresh to clear it.
Downloading Linux %Starting Linux…Could not start Linux. Check your connection and press the button again.
Needs 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 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
The (npx skills) also lists the skills you installed, shows their , updates and removes them. In the commands below -g means (every project on this computer); without -g the command works on this project ().
Global and local (project)
Global and local (project)
Global (-g)
Local (no -g)
Used in
Global (-g)
Every project on this computer
Local (no -g)
Only inside that project folder
Real files
Global (-g)~/.agents/skills/<name>
Local (no -g).agents/skills/<name>
Where reads it
Global (-g)~/.claude/skills/<name>
Local (no -g).claude/skills/<name>
Version and date record
Global (-g)~/.agents/.skill-lock.json
Local (no -g)skills-lock.json
No dates — only the version ()
Run local commands inside the project folder. If the same is installed both globally and locally, Claude Code uses the global (personal) one.
Claude Code does not read ~/.agents/skills
Claude Code reads only .claude/skills folders (~/.claude/skills and the project’s .claude/skills), never ~/.agents/skills or the project’s .agents/skills. , and read .agents/skills. The skills CLI keeps the real files in .agents/skills and makes a link for Claude Code in .claude/skills. If you copy a skill folder by hand into ~/.agents/skills only, Claude Code will not see it — put it (or a link) in ~/.claude/skills, start a new session and check with /skills in Claude Code.
List installed skills
Global skills — name, path, agents, Source
npx skills ls -g
Skills of this project (local)
npx skills ls
Only the ones linked for Claude Code
npx skills ls -g -a claude-code
As JSON — with scope and download address
npx skills ls -g --json
If the Source is sonub.com or a , the skill was installed with the skills CLI and can be updated and removed with it. local means someone put the folder there by hand — the skills CLI does not update it.
Check the version and install date
Skills have no version number. The version is the first 12 characters of the digest (the of the ) that the source publishes. When it installs a skill, the skills CLI writes this value with the install and update dates into the record file (the local record has no dates). We made this into a sh script, skill-versions.sh: download it once and reuse it in any project — it shows global and local skills in one table and compares them with the newest version at the source.
With claude-skill installed globally, run it without downloading
sh ~/.claude/skills/claude-skill/scripts/skill-versions.sh
SKILL SCOPE VERSION INSTALLED (UTC) UPDATED (UTC) SOURCE NEWEST
gp global 8188561e0e0f 2026-10-18 03:47 2026-10-19 01:32 sonub.com update → 2c1de455707c
popup global de0138a39fa1 2026-10-18 03:47 2026-10-19 01:32 sonub.com latest
popup project de0138a39fa1 2026-10-19 01:36* 2026-10-19 01:36* sonub.com latest
In the NEWEST column, latest means up to date and update → … means a newer version is out — update it. ? means the source did not answer. For local skills the date is when was written, marked with *. The script only reads and changes nothing; it runs on (the skills CLI needs it too).
Show skill-versions.sh
#!/bin/sh
# skill-versions.sh — the version, install date and update date of every agent skill installed with
# the skills CLI (npx skills), and whether a newer version is out. Skills have no version number:
# the version is the first 12 characters of the digest (sha256) the source published.
#
# sh skill-versions.sh # global (~/.agents/.skill-lock.json) and this project (./skills-lock.json)
# sh skill-versions.sh -g # global only
# sh skill-versions.sh -p # this project only — run it in the project folder
# sh skill-versions.sh --offline # do not ask the sources for the newest version
#
# Reads only the lock files and the sources' /.well-known/agent-skills/index.json; changes nothing.
# Needs Node.js, which the skills CLI needs anyway. Newer version → npx skills update <name> [-g].
scope=all
online=1
for arg in "$@"; do
case "$arg" in
-g|--global) scope=global ;;
-p|--project) scope=project ;;
--offline) online=0 ;;
-h|--help) sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
*) echo "unknown option: $arg (try -h)" >&2; exit 2 ;;
esac
done
command -v node >/dev/null 2>&1 || { echo "Node.js is needed (the skills CLI needs it too)" >&2; exit 1; }
SCOPE="$scope" ONLINE="$online" node - <<'JS'
const fs = require('fs'), os = require('os'), path = require('path');
const { SCOPE, ONLINE } = process.env;
const lists = [];
if (SCOPE !== 'project') lists.push(['global', path.join(os.homedir(), '.agents', '.skill-lock.json'), os.homedir()]);
if (SCOPE !== 'global') lists.push(['project', path.resolve('skills-lock.json'), process.cwd()]);
const short = (d) => (d || '').replace(/^sha256:/, '').slice(0, 12);
const day = (t) => (t ? t.slice(0, 16).replace('T', ' ') : '');
// The project lock file has no dates — fall back to when SKILL.md was written (marked with *).
function fileDate(base, name) {
for (const dir of ['.agents/skills', '.claude/skills']) {
try { return fs.statSync(path.join(base, dir, name, 'SKILL.md')).mtime.toISOString(); } catch {}
}
return '';
}
async function newest(base, cache) {
if (!(base in cache)) {
cache[base] = fetch(new URL('/.well-known/agent-skills/index.json', base), { signal: AbortSignal.timeout(10000) })
.then((r) => (r.ok ? r.json() : null))
.then((j) => Object.fromEntries((j?.skills || []).map((s) => [s.name, short(s.digest)])))
.catch(() => null);
}
return cache[base];
}
(async () => {
const rows = [], cache = {};
for (const [scope, file, base] of lists) {
let skills;
try { skills = JSON.parse(fs.readFileSync(file, 'utf8')).skills || {}; } catch { continue; }
for (const [name, s] of Object.entries(skills)) {
const version = short(s.wellKnownDigest || s.computedHash || s.skillFolderHash) || '-';
let installed = day(s.installedAt), updated = day(s.updatedAt);
if (!installed) installed = updated = day(fileDate(base, name)) + '*';
let status = '';
if (ONLINE === '1') {
const site = s.sourceType === 'well-known' && (s.sourceBaseUrl || s.sourceUrl);
const index = site ? await newest(site, cache) : null;
const latest = index?.[name];
status = !site ? '-' : !latest ? '?' : latest === short(s.wellKnownDigest) ? 'latest' : `update → ${latest}`;
}
rows.push([name, scope, version, installed, updated, s.source || '-', status]);
}
}
if (!rows.length) { console.log('No skills installed with the skills CLI here (no lock file).'); return; }
const head = ['SKILL', 'SCOPE', 'VERSION', 'INSTALLED (UTC)', 'UPDATED (UTC)', 'SOURCE', ONLINE === '1' ? 'NEWEST' : ''];
const all = [head, ...rows];
const width = head.map((_, i) => Math.max(...all.map((r) => r[i].length)));
for (const r of all) console.log(r.map((c, i) => c.padEnd(width[i])).join(' ').trimEnd());
if (rows.some((r) => r[3].endsWith('*'))) console.log('* the project lock file keeps no dates — this is when SKILL.md was written');
if (rows.some((r) => r[6].startsWith('update'))) console.log('Newer version out → npx skills update <skill> (-g for global)');
})();
JS
Paths — installed, downloaded from, original
Installed at — the path shown by npx skills ls (e.g. ~/.agents/skills/gp)
Downloaded from — sourceUrl in the record file (e.g. https://sonub.com/.well-known/agent-skills/gp.tar.gz)
Original — where the skill is made (for SONUB skills, the original that sonub.com serves). Changes to the installed folder are overwritten by the next update, so change the original instead.
Update and remove
Only gp, to the newest version (global)
npx skills update gp -g
Every global skill to the newest version
npx skills update -g
Every skill of this project to the newest version
npx skills update -p
Remove gp (global; it asks first — add -y to skip the question)
npx skills rm gp -g
Remove gp from this project
npx skills rm gp
Only unlink it from Claude Code (other agents keep it)
npx skills rm gp -g -a claude-code
An update downloads only the skills whose digest changed. Afterwards start a new session and run skill-versions.sh again — VERSION should equal NEWEST. Install a removed skill again with npx skills add https://sonub.com -s gp -g.
The skills
Each is a standard folder with a — the instructions an reads — plus a small tool. Nothing to sign up for, .
gp
All your work on a board
Talk to your in plain words and it manages your GitHub Project board with the — then reads the result back to confirm.
Issues: create, edit, move between columns, close, reopen, comment
Assign people; invite, list and remove board members
A board per project with /gp init <board >
Try saying
“What’s on my plate?”
“Move #12 to Review”
“Add ‘update the docs’ to its TODO”
“Add a column Urgent at the front”
Try it: manage your work with the gp skill
gp is a made by SONUB that keeps all your work on a board. Ask for these things in plain words, and the does them with the (gh) and reads the result back to confirm:
create, edit or close issues, and attach images
keep checklists
add or rename columns
assign people
Its folder has exactly the parts described above: , a script that does the work (scripts/gp.py) and reference files that are when needed.
Get ready: create a free 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 (it needs ). It puts gp into the agents on your computer — , , 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 ", "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?"
Claude Code ships a new almost every day. This 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 feature, summarized by topic
A setup doctor for settings, CLAUDE.md, skills, plugins and
/claude-skill update pulls newly released features into the skill
Try saying
“Next lesson”
“How do I run after every edit with a hook?”
“Check my setup”
“Give me a quiz”
Needs 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, and a “learn more” link.
One glossary is the source of every explanation, in every language you ship
A drop-in popup.js and popup.css — no , no
Finds terms in by itself; phrases, “?” buttons and link previews by hand
Keyboard, phones (bottom sheet), right-to-left languages and
An audit that finds jargon in your docs with no explanation yet
For READMEs on : a GLOSSARY.md and links that show the meaning on hover
Try saying
“Add glossary popups to the getting-started page”
“Explain , and on hover”
“Make the beginner-friendly”
“Which words in the docs still need an explanation?”
Needs 3.8+ for the tool. The popups run in any modern .
Ask every on your computer at once, then check the answers
cowork finds the AI command-line tools you have installed — , , , , , , , — sends the same question to every one that really works, , and your checks the evidence before writing one report.
/cowork init scans your AI tools and tests that each one really answers
Keeps the list in .cowork/.cowork-agents.json — run init again after you install or sign in to a tool
Every AI runs read-only, locked by its own sandbox or the sandbox
Remembers failures — sign-in, plan, usage limit, timeout — and works around them next time
One final-report.md: agreements, disagreements and claims proven wrong
If you asked for a fix, it applies the checked recommendations right after the report
Try saying
“/cowork init”
“/cowork login-timeout Why does login sometimes drop?”
“ this: is the chapter order of my workbook right?”
“Which AIs can cowork use right now?”
Works best on macOS, whose sandbox locks every AI read-only (elsewhere only Claude Code, Codex and Copilot run). Needs Perl and at least one AI you are signed in to; each AI uses your own account and plan.
infographics turns documents, reports and pages into pictures of the information. It analyses the source and picks the facts, then draws them — a hero picture and one matching picture per item (), and lines (curve, straight, diagonal, elbow) for relations and order — and reviews the result before it is done.
Starts from the source: reader, purpose, one core message and a fact list — numbers it cannot find stay gaps, never invented
A reading order: claim headline → summary → 3–5 key blocks → conclusion, with one hero instead of equal cards
Pictures and lines are required — curves for forks, routes for order, connection maps for shared parts, solid for required and dotted for optional. Tables and lists alone fail
Fixed type sizes, grid, spacing and one accent color
A poor, a text-only and a good result from the same source, side by side
5-second, blur and 30-second tests, plus a check that counts pictures and lines and finds clipped, overlapping or tiny text
Try saying
“Make this report into an infographic”
“Turn our guide page into a one-glance comparison”
“12 application images from this business plan”
“This infographic looks empty — fix it”
Requires the webmovie — install it first ( add https://sonub.com -s webmovie). The browser check needs 22+ and . Images need the Codex CLI () with its image .
linkify makes every chapter, heading and paragraph of your site linkable. Click a heading and the address changes to page#section and is copied to the — whoever opens that link lands right on that section.
Click a heading or its link button — the address becomes …#section and is copied, with a “Link copied” message
Opening the link scrolls to the section, below the sticky header, and briefly highlights it
Opens closed details boxes and hidden tabs on the way
A drop-in linkify.js and linkify.css — no , no
An audit that finds headings without a fixed id, duplicate ids and broken #links
A check that clicks, copies and opens every link at wide and narrow widths
Try saying
“Add copy-link buttons to every heading of the docs”
“Make each FAQ answer linkable”
“Clicking a chapter title should copy its address”
“Which sections still have no fixed id?”
The links work in any modern browser. The audit needs 3.8+; the browser check needs 22+ and .
webmovie plays a promo, intro or explainer like a short video — but every scene is real HTML. Headlines, numbers, charts, images and buttons move with and a little , so read every word, the movie is translated with the rest of the page and you fix it like any other text.
A player that plays HTML scenes like a clip — transitions, a slow camera push, ambient light, play/pause, scene buttons and a stop at the end
More than 30 shots with one attribute — mask, blur, letters, words and lines, typewriter, flip, slam, bounce, highlight, counters, bars, rings, pies and line drawing
Without JavaScript or with reduced motion the movie is simply the page, scene after scene — a storyboard anyone can read
Safe in every language — Arabic and Indic letters are never torn apart, CJK are kept, RTL is mirrored and long translations take the same time
A drop-in webmovie.css and webmovie.js — no , no , no — and the same shots for any page section, button or hover
A check that finds hidden or changed text and endless motion, and saves still frames of every scene
Try saying
“Make a 30-second intro movie for our home page — in HTML, not a video”
“Turn this report into a story that plays scene by scene”
“Count up these numbers and grow the bars when they come into view”
“Add a hover effect to the start button”
The movies play in any modern browser. The check needs 22+ and .
A folder with a file that tells an when and how to do a task, plus the scripts and notes it needs. It is an (agentskills.io), so the same folder works in many agents.
Every project or this project only?
Without -g the goes into the project you are in (for example and .agents/skills/), and you can 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?
, , , , 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 . The skills run on your computer with your own tools: gp talks only to through your login, claude-skill reads the public Claude Code docs, popup works on your files, cowork runs only the AI tools already installed and signed in on your computer. 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 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. init <name> makes the folder and a SKILL.md .
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.
# 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
mkdir -p .agents/skills && cd .agents/skills
npx skills init commit-message
You can also ask the agent: "Turn what we just did into a skill." and know the format (Codex has a built-in ).
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 is, how to write ).
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 ; for scanned PDFs use ").
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 (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, and .
Project 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 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"
npx skills add <source> reads the list of skills at that source (a or a website) and installs them. With no options it asks you, one by one, which skills, for which agents and where; each option answers one of those questions ahead of time.
-s <skill> (--skill): picks the skills to install by name. For several, repeat it (-s gp -s cowork) or list them after one -s (-s gp cowork). Without it you get the list to choose from.
-g (--global): installs once in your home folder, for every project on this computer. Without it the skill goes into the current project only.
-a <agent> (--agent): picks the agents to install to, for example -a claude-code or -a codex. Claude Code reads only .claude/skills, so choose claude-code if you use it.
-l (--list): only shows the skills at that source and installs nothing — look before you install.
-y (--yes): skips the confirmation questions — useful when a or an agent installs for you.
Terminal
# see what is there first — installs nothing
npx skills add https://sonub.com -l
# one skill, only for this project
npx skills add https://sonub.com -s cowork
# one skill, for every project on this computer
npx skills add https://sonub.com -g -s cowork
# several skills — repeat -s, or list them after one -s
npx skills add https://sonub.com -s gp -s cowork
npx skills add https://sonub.com -s gp cowork
# choose the agent too, and skip the questions
npx skills add https://sonub.com -g -s cowork -a claude-code -y
npx skills add https://sonub.com -l
npx skills add https://sonub.com -s cowork
npx skills add https://sonub.com -g -s cowork
npx skills add https://sonub.com -s gp -s cowork
npx skills add https://sonub.com -s gp cowork
npx skills add https://sonub.com -g -s cowork -a claude-code -y
Read the from left to right: npx skills add https://sonub.com -g -s cowork means "from sonub.com, for every project, install only cowork".
Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.
Advanced — big skills: files, scripts, tests, safety
When one 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 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 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 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 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. , and 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: , compatibility (needed and , up to 500 characters), (author and so on), (pre-approved tools — experimental).
disable-model-invocation: true — only you can call it. Use it for jobs with side effects, such as or sending messages.
Claude Code user-invocable: false — only the uses it, and it is hidden from the / menu. context: fork runs the skill in a .
Claude Code !`` — runs the command before the skill is read and puts the output in its place (for example !` HEAD`).
: 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 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 you will use — a small model may need more detail.
# 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}
]
is the reference tool in the agentskills (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 .
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 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, use across tools, design, maintain
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 add <owner>/<repo>. One repository can hold many skills.
Put each skill in its own folder under skills/. The installer finds them.
Add a and a with what each skill does and the install .
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 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 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 fix is the new .
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
is an , so one folder works in , , , 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 tool"). Write "run this in the ".
Keep one real folder in .agents/skills/ and link it into . npx skills add can do this for you (recommended), or make copies with --copy.
In Claude Code you can also bundle skills with , hooks and into a plugin and share it through a .
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 (ServerName:tool_name). Without it the agent may not find the tool.
