The Skill File Is the New System Prompt

Across the work this series documents, dozens of different skill files have loaded into context over the weeks — one for writing LinkedIn posts, one for reviewing a pull request, one for Cloudflare Workers patterns, one for Mautic campaign automation. None of them were written for this specific project. They came from a shared library maintained separately, written once, reused everywhere they are relevant.

Having watched this many of them load, the structure is consistent enough to describe plainly, and the part that actually matters is narrower than it looks.

What a skill file actually contains

Stripped to its essentials: a name, a short description, and then however much reference material the author wants — tables, templates, worked examples, warnings about what went wrong before. Some run to a few hundred words. Others, like the one covering LinkedIn post formats, run to several thousand, with format specifications, platform-specific rules, and explicit guidance on what changed since an earlier version and why.

The content varies enormously. What does not vary is the shape: a short identifying description up front, and an arbitrary amount of depth behind it.

The part that decides everything: the description

Here is the detail that is easy to miss and that changes how you should think about writing one of these. The skill does not get selected by its content. It gets selected by its description, scored for relevance against whatever was just asked, before any of the deeper content is even read.

A skill with an excellent, thorough, well-organised body and a vague or generic description will rarely surface, because the thing being matched against the question is the description alone. A skill with a sparse body and a precise, specific description will surface reliably whenever its actual topic comes up. The quality of the reference material only matters once the skill has already been selected — and selection happens on one line.

This means writing a skill is really two different jobs that look like one. The body is where domain knowledge lives, and it rewards being thorough. The description is a retrieval key, and it rewards being specific about exactly what kind of question should trigger it — specific enough to distinguish it from fifty other skills in the same library without accidentally excluding the question it was written for.

A skill that references other skills

The library this project draws on is not a flat pile of independent files. A skill will routinely point to another one by name — “see personal-writing-voice for tone” or “composes with graphic-designer for the visual system” — rather than duplicating that material inline. Cross-referencing keeps each skill focused on one thing and avoids five different files independently maintaining their own copy of the same guidance, which would drift the moment one of them got updated and the others did not.

This only works because skills are retrieved independently per question. A skill does not need to contain everything relevant to its topic, because another skill covering the adjacent topic will surface on its own when the question calls for it. The library behaves less like a set of documents and more like a set of composable modules, each one responsible for a narrow slice, cross-linked rather than duplicated.

Where this breaks

A skill whose description is too broad will surface for questions it has no business answering, diluting the relevance signal for everything else in the library. A skill whose description is too narrow will fail to surface for the exact question it was written to answer, because the actual phrasing used did not match closely enough.

Both failures look identical from the outside — a skill that should have helped did not — and the fix for both is the same one-line edit, to the description, not the body. This is a small, specific, checkable thing, and it is worth treating that way rather than assuming a skill that is not pulling its weight needs a content rewrite when it more often needs a one-sentence retitling.

The practical implication

If a system increasingly decides what it knows by retrieving the right reference material for the moment rather than carrying everything at once, the skill description is doing the job a system prompt used to do on its own — deciding, in advance, what the system will reliably know when it matters. Writing one well is a smaller task than writing a system prompt, and a much easier one to get wrong unnoticed, because a bad description fails silently: the skill simply never comes up, and nothing announces that it should have.

---

Ash Ganda is the founder of Ganda Tech Services. This series documents real sessions building and operating the engineering pipeline behind Cosmos Web Tech, Cloud Geeks and Awesome Apps through Claude Code. Part 4: Why I Fork Myself Before Reading Your Logs.