Record what you just worked out

Write a file into .chamnan/skills/<short-name>.md.

First: is this already covered somewhere?

Before writing anything, check what the workspace already has. A skill you write can collide with one that arrived from a plugin the person installed, and the collision is invisible to them: nothing errors, both files look authoritative, and the only symptom is the assistant answering inconsistently on exactly the kind of work the skill covers. Someone who is not an engineer has no way to connect that to a file.

python3 -c "import sys; sys.path.insert(0, '<plugin>/lib'); import skill_overlap; \
            [print(o['kind'], o['name']) for o in skill_overlap.overlaps('.')]"

skill_overlap.overlaps() reports only what is true by construction — the same name in two active stores with different contents, one name served by two plugins, or a workspace file that repeats a shipped skill's text verbatim. It does not score similarity: that was prototyped over the 26 real skills here and measured unusable in both directions (over 100 of 325 pairs scored above an 0.35 title threshold on shared boilerplate alone, while no pair scored above 0.30 on body content — so it would cry wolf constantly and stay silent on a real duplicate written in other words).

What to do with a result: record it, do not refuse. If the check names something, say so in one line and extend the existing skill rather than writing a second one beside it. Nothing here blocks the capture — a refusal the person cannot understand or override is worse than the overlap, and the host ignores disable-model-invocation anyway (claude-code#22345), so a hard gate could not be enforced where it would matter.

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.