An assistant knows PHP and does not know my engine. Give it a task in an unfamiliar subsystem and it writes something that looks right, names a method that never existed, and the reviewer pays for the discovery. Skills for ai agents exist to close that gap with a document instead of a hope.
Code: Atomic-Framework-Skills, GPL-3.0 licensed.
Twelve files, one per area of the framework, each a SKILL.md with a YAML header. Five reasons shaped what went in.
Reason 1: the source is the only authority
Every signature in those files was read from engine/Atomic/, and the contributing guide forbids documenting a method that is not there. A skill that invents one function is worse than no skill, because the assistant trusts it and the reviewer has to prove it wrong.
The rule costs time on the day of writing and saves it on the day of reading. When the engine renames a method, the skill is wrong and visible; when a model guesses, the skill is wrong and invisible.
Reason 2: one area per file, because context is finite
Twelve areas: overview, core, app and auth, data, CLI and API, events with hooks and i18n and mail, mutex and session, queue and scheduler with telemetry, theme, plugins, tools and WebSockets, and the doc map.
A single omnibus file would fit in a prompt and drown the answer. Twelve small files let the agent load the one that matches the task, and let a person review one without holding the whole framework in mind.
Reason 3: the description is the interface
The agent chooses a file by the description field, so that field is a requirement, not a label. It names tasks: bootstrap, config, logging, routing. A description that says “core functionality” gets loaded for everything and helps with nothing.
The same rule applies to any tool I write. The name and the description are the part the machine reads, and the body only matters after the choice is right.
Reason 4: guardrails are written after a mistake
The repository asks contributors to add a ## Guardrails note whenever a mistake is easy to repeat. Not a general caution: a note that names the wrong thing people do, in the place where they do it.
The Hook class is not the Event class. apply_filters returns a value. A nonce is bound to IP and User-Agent. Each of those lines prevents a class of wrong code that a page of correct documentation does not.
Reason 5: a map is not an answer
The doc map lists 44 documents by topic with the engine path each one describes. It is a skill of its own because finding the authoritative document is a different job from answering a question, and a model that finds the right file reads the real thing instead of paraphrasing mine.
That file ages fastest of all: every new document has to be added by hand, and a stale map is worse than no map because it sends the agent somewhere confident.
What the format cannot do
It cannot verify itself, run tests or know a client’s domain. The audit against the engine is manual, and that is the honest cost of the approach: someone has to read both sides.
It also cannot make a model careful. It can only make the reference specific, which turns “plausible” into “checkable”.
What it teaches about writing for agents
Write the reference the way you write code review comments: short, specific, with the wrong version nearby. A document that only lists what is correct gets skimmed; one that says “not this, this” gets used.
The same discipline is in the AI copywriting skill, where the rules name the failure they prevent. The reason to keep the source close is the same as in building a php framework: a system that hides its own behaviour cannot be reviewed.
The skills are GPL-3.0 and install by pointing an editor at a folder.