mgechev/skills-best-practices: A Style Guide for Agent Skills That Stay Inside the Context Window

The problem: skills that are too long to be found and too long to be read

An agent skill is a directory with a SKILL.md file that an LLM loads when it decides the skill is relevant. Two things can go wrong, and the guide names both.

The first is routing. According to the README, the name and description in the frontmatter are the only fields the agent sees before triggering a skill. If the description is vague, the skill is invisible. The guide's own example makes the failure concrete: a description of "React skills" tells the router nothing, so a request about component styles may never reach the skill that handles it.

The second is context. The README states that SKILL.md should stay under 500 lines and that bulky material belongs in subdirectories, loaded only when the skill instructs the agent to read it. A skill that inlines every API schema and every example consumes the window before the actual task begins.

The audience is narrow and specific: people authoring skills for coding agents, not people building an agent framework. The guide assumes you already have an agent that reads SKILL.md and that you are now fighting discoverability and token cost.

The directory layout the guide enforces

The README gives one canonical structure, and it is not negotiable within the guide's terms:

skill-name/
├── SKILL.md              # Required: Metadata + core instructions (<500 lines)
├── scripts/              # Executable code (Python/Bash) designed as tiny CLIs
├── references/           # Supplementary context (schemas, cheatsheets) 
└── assets/               # Templates or static files used in output

SKILL.md is described as the brain: navigation and high-level procedure. The other three directories hold what the brain points at. references/ carries API docs, cheatsheets and domain logic. scripts/ carries executable code for deterministic tasks. assets/ carries output templates, JSON schemas and images.

The constraint that matters most is depth. The README says files must sit exactly one level deep, and gives the contrast directly: references/schema.md is correct, references/db/v1/schema.md is not. That is a deliberate trade-off. A nested tree is more natural for a large domain, but every extra level is a path the agent has to be told about and can get wrong. The guide chooses a flat namespace and accepts the resulting name collisions.

Paths are also constrained: relative paths with forward slashes, regardless of the operating system the agent runs on.

Frontmatter is the routing table, so write it like one

The frontmatter rules are the most mechanical part of the guide, which makes them the easiest to check.

The name field must be 1 to 64 characters, lowercase letters, numbers and hyphens only, no consecutive hyphens, and it must exactly match the parent directory name. The README's example is explicit: a skill named angular-testing has to live at angular-testing/SKILL.md. This is a real constraint because it couples two things authors usually treat separately, the identifier and the filesystem path.

The description field is capped at 1,024 characters and is the only metadata used for routing. The guide asks for third-person phrasing and, more usefully, negative triggers. Its good example names the capability, the situation that should fire it, and the frameworks that should not: it creates and builds React components using Tailwind CSS, fires when the user wants to update component styles or UI logic, and does not apply to Vue, Svelte or vanilla CSS projects.

That last clause is the part most skill authors omit. A router with no negative signal will over-trigger, and the guide treats over-triggering as a defect worth designing against rather than a tuning problem.

No install step: using the repository as a checklist

There is no package to install. The repository is documentation plus a skill/ directory, and the README does not describe an install command, a CLI, or a published package. What you do instead is read it while you write your own skills, or point your agent at the skill/ directory if your setup supports loading a skill from a path.

Because no install command is documented, the practical first use is a structural check against an existing skill. Start by listing what a skill directory actually contains. The README's canonical layout is the thing to compare against:

skill-name/
├── SKILL.md              # Required: Metadata + core instructions (<500 lines)
├── scripts/              # Executable code (Python/Bash) designed as tiny CLIs
├── references/           # Supplementary context (schemas, cheatsheets) 
└── assets/               # Templates or static files used in output

If your own tree shows references/db/v1/schema.md, the one-level rule is already broken and the agent has to be handed a longer path than necessary.

The line limit is the second check. The README puts SKILL.md at under 500 lines, so anything above that is material the guide would move into references/ and load just in time.

Finally, check the frontmatter by eye against the naming rule. The name value and the directory name must be identical, lowercase, hyphenated, and free of consecutive hyphens.

Where the guide is thin: no validator, no licence, no rollback

The repository states rules but does not ship the tooling to enforce them. Nothing in the README describes a command that checks the frontmatter length, the directory-name match, or the one-level depth rule. You either write that check yourself or you catch violations in review. For a guide whose central claim is that mechanical rules prevent regressions, the absence of a linter in the same repository is the obvious gap.

Validation is delegated. The README describes a discovery-validation procedure that is manual: paste the frontmatter into a fresh LLM chat with a fixed prompt and see whether the model routes correctly. It also points to skillgrade for evaluating whether skills perform well and to prevent regressions, and to SkillsBench for benchmark inspiration. Those are separate projects, not part of this one.

The licence is not stated in the repository metadata available, so the terms under which the guide's text can be reused are unclear. Treat that as unresolved rather than permissive.

And the guide is the wrong tool if your problem is that the agent does not support skills at all. Every rule here assumes a host that reads YAML frontmatter and loads files on demand. Without that, the layout advice is just folder hygiene.

How it differs from the official skill documentation

The README is upfront that it is not the full reference. It calls itself a concentrated set of best practices and directs readers to Claude's documentation for comprehensive coverage. That framing sets up the real difference in approach: the official docs describe the format and the platform, while this repository compresses the format into a set of authoring rules with explicit numbers attached.

Concretely, this guide gives you a 500-line ceiling for SKILL.md, a 1,024-character ceiling for the description, a 1-64 character range for the name, a one-level depth limit, and a ban on README.md and CHANGELOG.md inside a skill. The official documentation is the place to check whether a field exists or what the spec permits; this is the place to decide whether your draft is too long and too vague. The two are complements, and the README says as much rather than positioning itself as a replacement.

The other distinction is the validation stance. The guide treats evaluation as something you do with LLMs, in a fresh chat, against the frontmatter in isolation. That is a cheaper loop than a full benchmark run, and it targets the failure that costs the most: a skill that never fires.

Writing instructions an agent can execute, not prose a human enjoys

The most transferable part of the guide is its stance on instruction style. It states plainly that skills are for agents, not humans, and the consequences follow.

Step-by-step numbering replaces narrative. The README's example of a decision tree is a numbered step with an explicit branch: if source maps are needed, run ng build --source-map, otherwise skip ahead. The agent is never asked to infer ordering.

Templates beat descriptions. Rather than spending paragraphs explaining what a JSON output should look like, the guide says to put the template in assets/ and instruct the agent to copy its structure, on the grounds that agents pattern-match well.

Voice is third-person imperative: extract the text, not I will extract or you should extract. Terminology is fixed to one term per concept, and the README's example is domain-specific: in Angular, use template rather than html, markup or view.

The guide also says to delete instructions the agent already handles reliably. That is the part teams resist, because deleting a paragraph feels like losing knowledge. Under a token budget it is the same move as moving a schema into references/.

Scripts, composition and what to leave out

For anything fragile or repetitive, the guide moves work out of the model and into code. A tested Python, Bash or Node script in scripts/ handles parsing a complex dataset or querying a database, and the README warns against bundling library code there: scripts should be tiny, single-purpose CLIs, and long-lived library code belongs in a standard repository CLI directory.

One detail in this section is easy to miss and matters in practice. The agent judges success from stdout and stderr, so scripts should return descriptive, human-readable errors that tell the agent how to correct itself without a human in the loop. An exit code alone is not enough.

Skills can also be composed. The README shows a router skill whose SKILL.md branches to other skills by path, for example a build_project skill that points at one skill for building the client and another for the server. That keeps the top-level file short while still covering a multi-target workflow.

The negative list is just as concrete. Do not create README.md, CHANGELOG.md or INSTALLATION_GUIDE.md inside a skill, because they consume context without changing agent behaviour. Do not keep redundant instructions. Do not inline library code. The guide's position is that a skill directory is an execution artifact, and documentation aimed at human readers is a cost with no corresponding benefit.

Editorial conclusion

Adopt this if you are writing SKILL.md files for an agent and your current ones are long prose documents that the model reads in full every time. Skip it if you need a validator or a test harness: this repository is a guide, and the README points to skillgrade for regression evaluation. Before you restructure anything, verify two things against your own setup: that your agent actually loads skills from YAML frontmatter alone, and that your skill name exactly matches its parent directory, since the guide states that mismatch is a naming violation. Then count the lines in your SKILL.md. If it is over 500, that is the first thing to cut.

Frequently asked questions

Official sources

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