| name | elfuse-skills |
| description | Writing and editing the elfuse skill files themselves - frontmatter, the description as a pointer, what belongs in a references file, and the gate. |
Writing an elfuse skill
The skills are documentation that an agent loads instead of rediscovering the
tree, so they are priced differently from docs/. A description is loaded on
every turn whether or not it fires; a body is loaded whole the moment it does.
Both halves are written against that price.
The gate
make check-skill-refs runs scripts/check-skill-refs.py over every skill
plus any routing document named on the command line. It checks the mechanical
half: the frontmatter name matches the directory, backticked paths resolve to
exactly one file, make <target> names a real target, a quoted section name
exists in the docs file nearest it, and a named sibling skill exists.
It cannot check whether a sentence is true. That half rots silently and only a
reader catches it, which is why a claim here names the file that carries the
real contract rather than restating what the contract currently says.
The description is a pointer
It does two jobs: say what the material is, then list the branches that should
reach it. Each branch appears once. A synonym for a branch already listed is
the same branch written twice, and it costs on every turn.
Cut anything the body already carries. A description that summarizes the
sections is paying always-on rent for a table of contents.
Set disable-model-invocation: true when only a human will ever type the
name. The description then costs nothing and becomes a one-line human summary.
Leave it off when the agent should reach the skill on its own, or when a
sibling skill names it.
The body
The shape the tree already uses, and the reason for it:
- A rule is stated with the consequence of breaking it, because the
consequences here are guest-visible and delayed. A rule with no consequence
attached reads as a preference and gets traded away.
- The authority is named at the point of use: the header comment, the lock
order comment, the docs section. A skill is a working summary, so every one
of them closes with the tracked sources that win when the two disagree.
- Numbers are recomputed rather than carried. A count quoted from a document
reads as verified.
- Material that only one branch reaches goes in a
references/ file beside the
SKILL.md, reached by a pointer sharp enough to fire on its own. The gate
checks those files too. Material every branch needs stays inline; splitting
it buys nothing and risks the pointer being skipped.
elfuse-conventions binds this prose the same as any other surface in the
tree: no em dash, third person, and no register the machine writes in.
Authoritative sources
scripts/check-skill-refs.py - the module docstring states exactly what is
checked and what is deliberately left unchecked.
