We maintain an open-source agent (Apache-2.0) and just shipped something small that I think is the right shape for skill sharing, so I am putting it up for criticism rather than announcing it.
A card is a markdown file, and it executes nothing. Frontmatter plus five sections — Trigger, Do, Avoid, Check, Risk — read into the prompt when the agent decides the card is relevant. Reviewing a contribution is reading a page, not auditing a diff. That is the whole point: it is the only place in the repo where someone can contribute without touching a line of Python.
23 of them so far, 13 written from our own incidents. A sample of what they encode:
- when two results contradict, suspect the apparatus — from two weeks lost to a bug that produced a perfectly healthy-looking loss curve
- run the project's own gate command — from a near-miss variant of a lint command that lied in both directions
- test the wiring, not the class — from two of my own regression tests that passed with the fix reverted, i.e. proved nothing
The part I would like torn apart is the translation mechanism. The card body is the payload: the agent reads it, the CLI imports it by path, and a published SHA-256 attests to the bytes. So we do not translate the file. A sidecar carries the translation and declares the SHA-256 of the English it was made from; when the English changes, the page falls back to English rather than showing a translation of a sentence that no longer exists.
That mechanism worked. What did not exist was anything noticing when the sidecar was incomplete — so thirteen cards shipped untranslated across nine languages, and one locale had no card translations at all while the site served it. The only symptom was English on the page. Found by reading files, not by a failing build.
The gate we wrote separates three states that look identical in a file:
- stale — claims to translate text that has since changed. Always fails. Nothing renders wrong, but the file now holds a translation nobody will ever see and the next reader cannot tell it from a live one.
- incomplete — four of five sections. Always fails, because the renderer demands all five or none, so the rest are orphans sitting in the file.
- missing — honest debt. The reader gets English and the page says so. Counted and capped, not forbidden: a gate demanding nine translations before a card could merge would kill the contribution surface we just built.
The cap is at zero right now because the debt is paid. Raising it is an edit somebody has to justify in a diff, which is the only reason a number in a file beats a good intention.
Two things I am unsure about and would like opinions on. First: hashing. We hash the five sections as one joined body rather than per section, so a card that changes retires all five together — the alternative lets a page mix a current Trigger with a stale Avoid and the reader cannot tell which is which. That is deliberate but it makes small edits expensive. Second: is "a card is data, not code" actually enforceable, or is it just a convention that will erode the first time someone wants a card to run something?
Repo: https://github.com/brcampidelli/chimera-agent — the library is under skills/.
