A copilot skill is a Markdown file with YAML frontmatter that an agent loads on demand. It is not a prompt, not a plugin and not memory: it is a document the assistant may read before answering, and the whole design follows from that.
Code: Atomic-Framework-Skills, GPL-3.0 licensed.
Twelve files cover Atomic Framework, a PHP 8.1 framework with 25 component folders under engine/Atomic/ and 44 documents in docs/.
The file has four fields that matter
---
name: atomic-framework-core
description: "Use when working with..."
argument-hint: "Bootstrap, config, logging, routing"
user-invocable: true
---
description is the router: the agent reads it to decide whether this file applies, so it has to name the tasks rather than the subsystem. argument-hint is what the editor shows when a person invokes the file by name. user-invocable decides whether anyone can call it directly.
The body is prose with code references taken from the engine source. There is no schema, no manifest and no build step, which is why the files survive a framework release that changes nothing in their area.
Twelve areas, deliberately small
Overview, core, app and auth, data, CLI and API, events and hooks with i18n and mail, mutex and session, queue and scheduler with telemetry, theme, plugins, tools and WebSockets, and a doc map.
The granularity is the useful part. A model that loads the queue file answers questions about Manager::instance()->push(); a model that loads a 60-KB omnibus document quotes a paragraph about caching and sounds plausible.
Loading through a glob
{
"github.copilot.chat.skills.instructionFilesGlob": "skills/**/*.md"
}
The glob tells the editor where the skills live. It does not make them load: the agent selects one by description or by an explicit invocation. An empty or generic description means the file is never chosen, and the fix is in the file rather than in the editor.
Guardrails instead of general advice
The contributing guide asks for two things: never document a method that does not exist in the source, and add a ## Guardrails section when a mistake is easy to repeat.
A guardrail is a note about a specific failure, written after it happened. “The Hook class is not the Event class, and apply_filters returns a value while emit returns nothing” prevents more wrong code than a page about the event system.
The doc map as a separate skill
atomic-framework-doc-map is a cross-reference table: document file, engine path, skill. It exists because an agent sometimes needs to find the authoritative document rather than an API signature, and a map of 44 documents is cheaper to load than the documents.
That file is the one that ages fastest. Every new document has to be added by hand, and a map that misses a file sends the agent to a stale answer.
What the format cannot do
A skill cannot verify itself. The repository states that the content is audited against engine/Atomic/<Component>/<File>.php by hand, and that is the only thing standing between a model and a confident invention.
It also cannot run code. A test suite is still the check that a suggestion compiles, and no amount of accurate documentation replaces a failing assertion.
Why this shape works for a framework
A framework is a large repository with a small set of public entry points, which is exactly the shape where retrieval by description beats a single long prompt. Twelve small files are also reviewable by the people who wrote the engine, and reviewability is what keeps them true.
Related: modular php framework for the engine these skills document, and islands architecture for another case where a small unit beats one big bundle.