ArcticFox2029 Record what you just worked out
Write a file into .chamnan/skills/<short-name>.md.
When this is worth doing
- A task took several steps that were not obvious, and will come up again
- Something failed in a way that was expensive to diagnose
- You have now done the same thing a third time
- A decision was made whose reason will not be visible in the code afterwards
When it is not
Anything a competent reader gets from the code itself. A file that restates what the code says costs tokens on every future session and returns nothing. When in doubt, don't — an over-full skills directory trains the next session to skip the directory.
Format
---
description: <one line, under 100 chars — this is what a future session sees in the registry>
---
# <what this is about>
## The trap / the task
What actually happens, concretely. Name real files, real commands, real error text.
## What to do
The steps, in order.
## Why it is like this
The reason. This is the part that stops someone "fixing" it back to the broken version.
The description line is not optional. Session start lists every skill by name and
description; a file with no description shows as a bare filename, and a bare filename is not enough
for a future session to decide whether to open it. That is the whole cost of the registry wasted.
Write in the language set as language in .chamnan/config.json (default en). These files are re-read on every session, which is why English is the default — but a procedure your team cannot read is worth nothing however cheap it is.
Be specific. "Be careful with the cache" is worthless. "_write_index is a plain write_text with
no atomic replace, so two threads writing the same index drop one update and can interleave into
invalid JSON, which _read_index turns into [] — batch such updates into one pass" is worth
keeping.