rjv-writing-skillslisted
Install: claude install-skill rjvim/ai-skills
# Writing skills agents obey
A skill is a hypothesis about agent behaviour. It makes the agent walk
the same process every run; the outputs still differ because every
context differs. Write it for a fast colleague who has never seen this
repo, and judge it only by what agents do after reading it.
Pick the branch:
- **Writing a new skill or doc**: walk steps 1 to 6 below.
- **Reviewing or improving existing skills** (this repo or another
project's internal skills): read [`REVIEW.md`](REVIEW.md), which
applies these same steps as a checklist.
- **Proving a skill works**: read [`TESTING.md`](TESTING.md).
## 1. Trigger: who invokes it
The description is a context pointer. It sits in every session, so
each word costs on every turn, and its wording decides when the agent
opens the skill.
| The skill must be reached... | Make it |
|---|---|
| by the agent on its own, or by another skill | model-invoked: keep a model-facing description |
| only when the user types its name | user-invoked: `disable-model-invocation: true`, one-line human description |
Model-invoked skills cost context load and can be skipped even when
they fit. User-invoked skills cost the user's memory. Choose per skill,
and say which in one line of the commit.
A model-invoked description:
- opens with what the material is, using the leading word the user
actually types (`plan`, `review`, `spec`);
- lists one trigger per distinct case; synonyms for the same case are
one trigger;
- says where a siblin