# 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
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
---
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).
更新を頼む: AI に「このスキルを基本のスキル形式に合わせて整えて。私のアイデア・ロジック・ルールはそのままにして、足りない手順・例・確認方法を補って」と頼み、直した内容を読んで自分の意図と合っているか確かめます。
---
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.
#!/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
パス — インストール先・ダウンロード元・オリジナル
インストール先 — npx skills ls に表示されるパス(例: ~/.agents/skills/gp)
# 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?"
# ✗ 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 はスキル一覧で説明を 1,536 文字までしか表示しないので、いちばん大事な使い道を先頭に書きましょう。
---
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.
Claude Code は SKILL.md の変更をすぐ反映します。スキルフォルダーを新しく作ったときは /reload-skills を実行します。ほかのツールでは新しいセッションを始めます。
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
# 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"
# 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
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)
## 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.
どの言語を実行できるかはエージェントによってちがいます。よく使われるのは ・・ です。
frontmatter のオプション — 標準と、ツールごとのおまけ
name と description のほかに、標準にはいくつかの任意フィールドがあり、ツールごとに独自のフィールドも追加されます。ツールは知らないフィールドを無視するので、まず標準フィールドだけで動くようにしましょう。
---
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`.
# 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}
]
Claude Code：Skill(deploy *) のような権限ルールでスキルをブロックし、disableSkillShellExecution 設定で !`command` をオフにします。
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/
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
# 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
Claude Code では、スキルを・フック・ といっしょにプラグインにまとめ、で共有することもできます。
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
