skills-best-practices: a style guide for agent skills, not a runtime

The problem is context budget, not skill authoring

Most teams writing agent skills start by writing documentation. The result is a SKILL.md that explains background, restates the API, and includes a changelog, all of which is loaded into the context window every time the skill is considered. The guide takes the opposite position: a skill is for an agent, not a human, and the guide states plainly that you should not create README.md, CHANGELOG.md, or INSTALLATION_GUIDE.md inside a skill directory. The audience is whoever maintains a skill library that an agent routes over, and the failure they are trying to prevent is a context window filled with material the agent never needed for the current task. There is a second, less obvious problem the guide addresses: discovery. The name and description in the YAML frontmatter are described as the only fields the agent sees before triggering a skill, which means a vague description makes the skill invisible regardless of how good the body is.

Progressive disclosure is the whole architecture

The mechanism is a directory convention rather than a runtime. Every skill follows the same layout: SKILL.md at the root, with scripts/, references/, and assets/ beside it. SKILL.md is described as the brain, used for navigation and high-level procedures, and is capped at under 500 lines. Everything bulky moves into the subdirectories, and the guide is strict that files sit exactly one level deep, so references/schema.md is acceptable and references/db/v1/schema.md is not. The data flow is just-in-time: the guide states that the agent will not see these resources until you direct it to them, which is why SKILL.md has to contain explicit pointers such as a line telling the agent to read references/auth-flow.md for specific error codes. Paths are relative with forward slashes regardless of operating system. The practical consequence is that the quality of a skill depends heavily on how well SKILL.md routes, because the agent only reads what SKILL.md tells it to read. A skill with excellent reference files and a vague SKILL.md will never surface them.

Frontmatter rules that decide whether the skill fires at all

The naming constraints are the most mechanical part of the guide and the easiest to get wrong. The name field must be 1 to 64 characters, lowercase letters, numbers, and hyphens only, with no consecutive hyphens, and it must exactly match the parent directory name. The guide gives the example that name: angular-testing must live in angular-testing/SKILL.md. Descriptions cap at 1,024 characters and are expected to be written in the third person with negative triggers included. The guide's own contrast is worth quoting in short: a bad description is "React skills.", and a good one names the capability, states when to use it, and then states what it is not for, listing Vue, Svelte, and vanilla CSS as exclusions. That negative-trigger instruction is the part most authors omit, and it is the part that prevents a skill from firing on the wrong project.

Writing instructions an agent can execute without interpretation

The guide asks for procedural, numbered steps in the third-person imperative: "Extract the text..." rather than "I will extract..." or "You should extract...". Decision points are meant to be explicit, with an example of the form: if you need source maps run ng build --source-map, otherwise skip to step 3. Terminology is expected to be fixed across the skill files, and domain-specific. The guide's example is Angular, where you should use the term template rather than html, markup, or view. For output shape, the recommendation is to avoid describing a JSON structure in paragraphs and instead place a template in assets/ and instruct the agent to copy its structure, on the reasoning that agents pattern-match well. Scripts belong in scripts/ and are meant to be tiny CLIs for fragile or repetitive operations where variation is a bug. The guide is explicit that library code does not belong there, and that scripts should return descriptive, human-readable errors on stderr so the agent can self-correct without a human in the loop. Composition is also covered: a router skill can reference subskills conditionally, with a build_project example that branches between a client and a server skill.

Validation is a prompt, not a test runner

The validation section is where the repository is thinnest as software and most honest as a method. There is no CLI, no schema checker, and no linter in the material provided. What the guide offers is a discovery-validation procedure: paste the frontmatter into a fresh LLM chat with framing that says agents will decide whether to load the skill based entirely on the YAML metadata, and see whether the model routes correctly. The example frontmatter used in that prompt is a skill named angular-vite-migrator that migrates Angular CLI projects from Webpack to Vite. The reasoning is sound, since routing is a classification problem and a fresh context is the closest cheap approximation of how a runtime sees your skill. The limitation is equally clear: this tests the description in isolation, with no tool calls, no file reads, and no multi-turn behaviour, so it will not catch a skill whose body sends the agent down a wrong path. The guide acknowledges the gap by pointing to skillgrade, a separate repository, for evaluating skills and preventing regressions, and to SkillsBench as a benchmark for inspiration. Neither is part of this repository.

Where the guidance runs out

Several things a reader will want are simply not in the material. The licence is unknown from what is provided, so anyone planning to copy the text into internal documentation should check the repository directly rather than assume. There are no releases retrieved, which suggests there is no versioned artifact to pin, and no install command because there is nothing to install. The 500-line cap on SKILL.md is stated as a rule without a derivation, and the one-level-deep rule for reference files is likewise asserted rather than justified, so treat both as conventions that a given runtime may or may not enforce. The guide also assumes a runtime that exposes only name and description for routing; if your agent platform surfaces the full frontmatter or the file tree, the discovery advice matters less and the body-writing advice matters more. The strongest case against adopting it wholesale is a team that already has a working skill format with different constraints. The guide's rules are specific enough to conflict with an existing convention, and nothing in the repository reconciles the two.

The alternative: prompt libraries and full agent frameworks

The obvious comparison is a prompt library or a system-prompt template repository, where instructions live in one long file that is always loaded. The difference in approach is the loading model. A prompt library pays the token cost on every request and relies on the model to ignore irrelevant sections. This guide assumes on-demand loading, where SKILL.md is cheap because it is short and the expensive material sits in references/ until the agent is told to open it. That trade only pays off if the runtime actually implements just-in-time loading and if the author writes the pointers. A second alternative is a full agent framework that packages skills as code with typed inputs and a registry. That gives you programmatic validation and versioning, which this repository does not provide, at the cost of writing your instructions as code rather than as markdown. The guide's position is closer to the prompt library in format and closer to the framework in intent: markdown files, but structured so that a router can pick between them.

Maintenance cost and what to verify before you commit

The maintenance burden here is editorial rather than operational. There is no dependency graph to update and no upgrade path, because the repository is prose. The recurring cost is the review discipline the guide implies: every time a skill grows past the point where SKILL.md is navigation rather than explanation, someone has to move material into references/ and add the pointer line. The guide's own test for redundancy is blunt, stating that if the agent already handles a task reliably without help, you should delete the instruction. That is a deletion habit, not an addition habit, and it is the part of the method most likely to be abandoned first under deadline pressure. Two checks are worth running before you restructure an existing skill library around this guide. First, confirm that your runtime routes on frontmatter alone, since the entire discovery argument rests on that. Second, confirm that your tooling tolerates the directory name matching the name field exactly, because renaming directories to satisfy that rule will break any path references you already have. If both hold, the guide is a reasonable style contract to write down and enforce in review.

Editorial conclusion

Adopt this if you are authoring SKILL.md files for an agent runtime and your current skills are drifting toward prose documentation. Skip it if you need a validator binary or a CI gate; the repository is a guide, and the companion tooling lives in a separate project, skillgrade. Before writing your first skill, verify two things in your own setup: that your runtime exposes only the name and description fields for routing, and that your skill directory name matches the name field exactly, since the guide states this must hold.

Official sources

1. Issues
2. mgechev/skills-best-practices on GitHub
3. README