7.4 KiB
Skills
A skill is a markdown file with instructions for one kind of task. Only its name and description sit in the system prompt; the body is loaded on demand.
That split matters. The twenty-nine bundled skills are tens of thousands of characters of body against a small catalogue of names and descriptions — paid on every request. Putting every body in the prompt would cost that on every turn, for instructions relevant to one turn in twenty.
Format
---
name: deploy
description: Ship a release. Use when asked to deploy, cut a release, or publish a build.
---
# Deploy
1. Confirm the tests pass. Do not deploy on a red suite.
2. Tag with the version from `src/version.ts`, not by hand.
3. Push the tag. CI builds and publishes.
Never deploy from a dirty working tree.
name and description are both required; a file missing either is skipped. The
description is what the model matches against, so write it as a trigger — "use when asked
to X" — not as a summary.
The frontmatter reader handles those two fields and nothing else. A real YAML parser would be a dependency for two strings, so lists, nesting, and multi-line values are not supported: keep both on one line. Quotes around a value are stripped. A body over 20,000 characters is truncated.
A file that fails to parse is skipped silently rather than reported, which is worth knowing when
a skill you wrote does not appear in /skills — the usual cause is a missing --- fence or a
description spilling onto a second line.
Where they load from
Four sources, later overriding earlier by name:
- builtin — compiled into the binary
- registry —
~/.shiro-neko/registry/skills/*.md, installed with/registry add - user —
~/.shiro-neko/skills/*.md - project —
.shiro/skills/*.md
A project skill named debug replaces the bundled one entirely. /skills shows what
loaded and where each came from — which matters most for registry, since that body came
from someone else and is now in your system prompt. See registry.
--no-skills skips all of them, builtin included.
The bundled skills
debug — reproduce first, form three hypotheses, disprove them cheapest-first, fix the
cause not the symptom, write a test that failed before. After two failed attempts: re-read
the error literally and check whether the code you think is running is the code that is
running.
review — severity order: incorrect behaviour, missing validation at trust boundaries,
security, resource handling, then clarity. Say plainly when something is fine. Do not invent
findings to look thorough.
refactor — establish a safety net first, move in small steps with tests green between
each, do not fix bugs while refactoring, do not add abstraction for a single caller.
test — read two existing test files first and match them, assert on behaviour not
implementation, never weaken an assertion to make a test pass, a flaky test is a shared-state
problem and not something to retry around.
verify — confirm a change works by running the artifact the way a user would, not by
reading the source. What counts as evidence, what to do with the failure path, and reporting
what was not verified.
commit — stage and commit work: look at the diff before staging, one commit one reason,
match the repository's message style, and the refusals — no amending pushed commits, no
--no-verify, no push unless asked.
security — find the trust boundary, then work outward: injection, missing authorisation,
path traversal, secrets in the wrong place, SSRF, hand-rolled crypto. Do not report a finding
without a path from an attacker-controlled value to the sink.
perf — measure before changing anything, find where the time actually goes, change one
thing at a time, and stop at a target stated up front. Report the baseline alongside the win.
migrate — read the changelog first, find every call site before changing one (including
CI, Dockerfiles, and docs), apply one shape of change rather than improving as you pass, and
never hand-merge a lockfile.
plan — break a non-trivial task into an ordered, verifiable sequence before writing code:
order by dependency rather than by file, one step one verifiable outcome, keep it small, and
replan when the ground moves.
docs — write documentation grounded in the source: verify every claim against the code,
answer the reader's actual question, show a working example before describing one, and match
the house style.
They are Markdown files in src/skills-md/, one per skill, loaded by src/skills-builtin.ts
as Bun raw-text imports. The .md file is the single source of truth — frontmatter and body
in proper Markdown — and Bun inlines every text import into the compiled binary, so the folder
ships with bun build --compile rather than being left behind on disk.
How the agent uses one
The catalogue appears in the system prompt:
Skills available through the skill tool. Load one when its description matches the task,
before you start working, and follow it as if the user had written it:
- debug: Track down a bug whose cause is not obvious. Use when a test fails for unclear...
- refactor: Restructure code without changing behaviour. Use when asked to refactor...
When the model calls skill({ name: "debug" }) it gets the full body back and is told to
follow it for this task. The call needs no approval — it reads nothing outside the binary.
"Before you start working" is the load-bearing phrase. A skill loaded after the work is done is wasted tokens, and the failure mode in practice is a model that reads the catalogue, decides it already knows, and never calls the tool. A description written as a trigger is what prevents that.
Loading one costs its body, once, in that turn's context. A 3,000-character skill is cheaper than one wrong approach it prevents, and more expensive than the catalogue line that would have been enough.
Verifying a skill loaded
shiro -p "fix the failing pagination test" --json --yolo | grep skill
--json shows the tool-call for skill with the name it chose, or its absence. If the model
never calls it on a task the skill was written for, the description is the thing to change — not
the body.
Writing a good one
Skills work when they encode what a newcomer to your project would get wrong. The bundled ones are generic on purpose; yours should not be.
Useful:
---
name: migration
description: Write or run a database migration. Use when the schema changes.
---
Migrations live in `db/migrations/` and are timestamped, never renumbered.
Run `bun run db:migrate` locally first. Staging runs them automatically on deploy;
production needs `bun run db:migrate --env=prod` by hand, after the deploy is green.
Never edit a migration that has run anywhere. Write a new one.
Not useful:
---
name: quality
description: Write good code.
---
Follow best practices. Write clean, maintainable code with good naming.
The second costs tokens and changes nothing.
Skill or AGENTS.md?
AGENTS.md is always in the prompt. A skill is loaded when its description matches.
Put standing facts in AGENTS.md: build commands, layout, conventions that apply to every
change. Put task-specific procedure in a skill: how to deploy, how to add a migration, how
this project debugs its worker queue.
If it applies to every turn, it belongs in AGENTS.md. If it applies to one kind of turn,
make it a skill.