Skill Definition Files for LLMs: Three Core Principles

一、Why the way skill files are written is changing

As large language models (LLMs) keep improving, a class of “skill files” built around the model has become a key engineering asset. A skill file is usually written in Markdown with a YAML metadata header, and it describes when a capability is triggered and how it should be executed. It is neither an ordinary document nor pure code: it sits somewhere between “a manual for the model” and “an executable workflow.”

Early on, many teams tended to cram as much context as possible into a single skill file. Now that model capabilities have grown and context management has become more granular, that approach exposes two problems. First, it consumes tokens and inference cost needlessly. Second, the model gets distracted by redundant information and its output drifts toward generic statements, losing specificity.

So rewriting skill files for newer models is essentially an information-architecture rebuild, not a round of copy editing. The three principles below form the core of efficient skill file design.

二、Principle 1: Put the most critical information at the top of the file

A widely adopted design assumption is worth treating as a default: when an agent picks a skill out of many and loads it, it usually previews the beginning of the file (say, the first 100 lines) to judge whether the skill is relevant, rather than reading the entire Markdown file every time.

The direct implication: the information that lets the model quickly understand “what this skill does, when to use it, and what the first step is” must land within the first 100 lines. Derived details, edge cases, and reference material are secondary and can sit further down.

Two engineering constraints go with this:

• Keep the main file short. Anthropic-style guidance typically suggests keeping the main skill file within a few hundred lines. The shorter the main file, the lower the cost for the model to locate and judge.
• Write a clear metadata header. The name and description fields at the top of the file determine whether the model can correctly decide to trigger the skill during preview, so make them specific and distinguishable.

---
name: design-review
description: Review design files against the requirements document and produce a structured review report
---
# Design Review Skill
## Goal
Check design files item by item against the requirements document and output a structured review report.
## Review Workflow
1. Read the requirements document (see `reference/prd.md`)
2. Check each item on the checklist to verify the design meets the requirements
3. Generate the review report
## Referenced Files
- `reference/prd.md`      —— Product requirements document
- `reference/checklist.md` —— Review checklist

This example deliberately puts “goal — workflow — reference list” up front, so even if the model reads only the first 100 lines, it immediately understands the skill’s responsibility and execution path.

三、Principle 2: Load information on demand with progressive disclosure

If a requirements document runs to a thousand lines or more, inlining all of it into the main file is clearly unrealistic. This is where progressive disclosure comes in: the main file keeps only the skeleton and an index, and supplementary information lives in other Markdown files that the model reads on demand.

The value is twofold:

• Saves context and tokens. The model only loads a file when it genuinely needs that detail, instead of absorbing irrelevant content up front.
• Cuts interference and improves focus. With a short main file, the model grasps the core workflow more easily and produces more focused output.

As the example above shows, step 1 does not paste the requirements document into the main file; it references a separate reference/prd.md. This layered structure — “the main file handles navigation, sub-files carry the detail” — is one of the most effective ways to control context cost.

One caution: progressive disclosure does not mean splitting endlessly. Split based on “does this need to be retrieved independently and on demand”: the stable, always-relevant core workflow stays in the main file; only content that is large, updated frequently, or needed on a specific branch should be pushed down into referenced files. Over-splitting creates maintenance burden and costs more than it saves.

四、Principle 3: Add a table of contents to every referenced file

For progressive disclosure to actually be efficient, there is one easily overlooked prerequisite: the referenced files must themselves be previewable. So it is strongly recommended that each referenced file open with a table of contents that summarizes what each section covers in one line.

# What This File Contains
1. Product Overview      —— What we are building
2. Core User Scenarios   —— Who uses it, and in what situations
3. Feature List          —— Each feature with acceptance criteria
4. Non-Functional Requirements —— Performance, availability, and security constraints
---
# Product Overview
...

With that table of contents, the model only needs to scan the section titles to decide “which part do I need,” then jump straight to it instead of reading the whole file. The logic matches Principle 1: put navigation information where it is most likely to be read first. That is the general idea running through skill file design.

五、A review checklist you can apply directly

Once you have accumulated a batch of older skill files, you can use the prompt template below to have the model audit them against current best practices and suggest improvements:

Please review the skill file(s) I provide and evaluate and rewrite them along these dimensions:
1. Is all critical information (trigger conditions, core workflow, responsibility boundaries) within the first 100 lines of the file?
2. Is the main file within a reasonable length? Which content could be pushed down into referenced files?
3. Are the name / description fields in the metadata header specific, distinguishable, and easy to trigger on?
4. Does each referenced file open with a table of contents that supports precise on-demand loading?
5. Is there any redundant, duplicated, or removable wording that could further reduce tokens?
6. Is there over-splitting, with a reference structure that raises maintenance cost?
Output: first a list of issues, then a recommended rewritten file structure.

六、Summary

Writing skill files for newer models is less about covering everything and more about getting the model the most critical information at the lowest possible reading cost. The three principles reinforce each other: critical information up front makes the skill “understandable at a glance,” progressive disclosure makes information available “on demand,” and a table of contents makes that on-demand retrieval actually work. Bake these three into your skill file templates and review process, and you will systematically lower token consumption, reduce useless interference, and get more precise, more consistent model output.