Skills

On-demand instructions, invoked with /name or automatically when the model decides they apply — zero context cost until they run.

Overview

A skill is a single SKILL.md file: frontmatter for configuration, markdown for the instructions. It only enters the model's context when invoked — either by the user typing /<name>, or by the model itself, if the skill's description matches what's being asked. Reference files sitting next to SKILL.md (scripts, longer docs) aren't auto-loaded either — the skill body reads them on demand, so a skill with a lot of supporting material still costs nothing until the part it needs is actually read.

Directories

Location	Path
Project	`.claudin/skills/<name>/SKILL.md`
Personal	`~/.claudin/skills/<name>/SKILL.md`
Nested categories	`.claudin/skills/<category>/<name>/SKILL.md`
Legacy (deprecated)	`.claudin/commands/*.md` — still loads, prefer `skills/`

The file must be named exactly SKILL.md, in its own subdirectory — a stray skills/foo.md at the top level is silently ignored.

Frontmatter

Field	Notes
`name`	Display name; defaults to the directory name.
`description`	What it does and when to use it — drives the `/skills` listing and model auto-invocation.
`when_to_use`	Extra trigger guidance for auto-invocation.
`allowed-tools`	Tool allowlist while the skill runs, e.g. `Read, Bash(git diff:*)`.
`argument-hint`	Composer hint, e.g. `[pr-number]`.
`arguments`	A string or list of names — each becomes a `$<name>` placeholder in the body.
`disable-model-invocation`	`true` — user can invoke it, the model can't.
`user-invocable`	`false` — hides it from the `/` menu; model-only.
`model`, `effort`	Override the model or reasoning effort for this run.
`context: fork`, `agent`	Run the skill in a forked subagent, optionally a named one.
`paths`	Glob(s) — only surface this skill when matching files are in play.
`hooks`	Skill-scoped hooks, same schema as `settings.json`.

Body placeholders: $ARGUMENTS (everything typed after the name), $0 / positional args, $<name> for a named argument, ${CLAUDE_SKILL_DIR} for the skill's own directory, and inline ` `!`shell command`` ` execution before the prompt is sent (gated by allowed-tools).

---
name: my-skill
description: What it does AND when to use it — this drives auto-invocation.
---

Instructions for the model...

Invocation

/<name> — user-invoked, unless hidden by disable-model-invocation or user-invocable: false.
The Skill tool — model-invoked, when the description matches.
/skills — lists everything currently loaded.

A new skill dropped into an already-existing skills/ directory is picked up by a live file watcher within seconds — no restart needed.

Skills vs. rules vs. agents

	Skill	Rule	Agent
Path	`.claudin/skills/<name>/SKILL.md`	`.claudin/rules/<topic>.md`	`.claudin/agents/<name>.md`
Loaded	On demand (invoked)	Every session, always or path-conditional	When delegated to
Frontmatter	See above	Just `paths` (glob); no `paths`, or `paths: "**"`, means unconditional	See the Agents page

The /create skill authors any of the three from a plain-language description, straight into the right spot under .claudin/ or ~/.claudin/.

Bundled skills

Skill	What it does
`update-config`	Configure the harness via `settings.json` — hooks, permissions, env vars.
`code-review`	Review the current diff for correctness bugs and cleanup opportunities; supports inline PR comments and auto-fix.
`simplify`	Clean up changed code for reuse and clarity — quality only, not bug-hunting.
`verify`	Build and run the app, drive it to the changed code, confirm the fix works.
`run`	Launch the project's app and drive it to the change, end to end.
`batch`	Research/plan a large-scale change, then execute it in parallel across 5–30 isolated worktree agents that each open a PR.
`fewer-permission-prompts`	Scan recent transcripts for common read-only calls and allowlist them.
`create`	Author or refine skills, rules, and agents in `.claudin/`.
`loop`	Run a prompt on a fixed or dynamic interval — see Automation.
`debug`	Turn on debug logging and help diagnose an issue.
`keybindings-help`	Customize keyboard shortcuts via `~/.claudin/keybindings.json`. Model-only, hidden from the `/` menu. Currently gated to an internal preview — most users will see "not enabled" rather than working customization.

See Settings and Keyboard shortcuts for more on update-config and keybindings-help.

Try it

mkdir -p .claudin/skills/summarize-tests
cat > .claudin/skills/summarize-tests/SKILL.md <<'EOF'
---
name: summarize-tests
description: Summarize the last test run's failures in one paragraph.
---
Read the most recent test output and summarize only the failures.
EOF

Then run /summarize-tests, or just ask for it in plain language and let the model pick it up on its own.