# What open source agent skills cost before any of them fire > Progressive disclosure is the loading model behind every open source agent skill: the agent sees a name and a description first, and the rest only when a task calls for it. That first load costs context on every request. Kortix is the open-source CompanyOS. URL: https://agentskillsguide.dev/progressive-disclosure ## The three tiers, in the specification's own words `skills/pdf-processing/` ``` Metadata (~100 tokens): The name and description fields are loaded at startup for all skills Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required ``` Source: https://agentskills.io/specification The first line is billed on every request, the second only when a skill is activated, the third only when a step opens a file. A team sets the first line by deciding what to install. ## One skill file, and the folder its references live in The body names two files it does not inline, so neither is read until a step asks for it. The first panel is an example for a repeated extraction task. The second shows where the two named files sit, and that a script ships beside them. ### SKILL.md `skills/pdf-processing/SKILL.md` ``` --- name: pdf-processing description: Extract text and tables from PDF files and fill form fields. Use when a task involves a PDF, a scanned document or a fillable form. --- # PDF processing 1. Read the file with `pdfplumber` and print the page count. 2. Extract text page by page, and keep tables as rows. 3. For form fields, open `references/FORMS.md` and follow it. 4. For layout or encoding questions, open `references/REFERENCE.md`. 5. Write the result to the path the task named, then stop. ``` ### folder `skills/pdf-processing/` ``` skill-name/ ├── SKILL.md # Required: metadata + instructions ├── references/ # Optional: documentation │ ├── REFERENCE.md # Detailed technical reference │ └── FORMS.md # Form templates or structured data formats └── scripts/ # Optional: executable code ``` ## Only one tier is charged whether you use it or not A skill is read in three stages, and the format's repository names them. [Discovery](https://github.com/agentskills/agentskills) is the startup pass that loads "only the name and description of each available skill, just enough to know when it might be relevant." Activation is the agent reading the full `SKILL.md` into context once a task matches. Execution is the steps, with bundled code run or a referenced file opened as needed. Prices attach to those stages. Claude's [overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) gives the table: "~100 tokens per Skill" at level 1, "Under 5k tokens" at level 2, "None until accessed" at level 3. The [specification](https://agentskills.io/specification) writes the same model as a rule for authors. It adds a ceiling to the middle tier: "Keep your main SKILL.md under 500 lines." The asymmetry decides the rest. A body costs tokens after the agent chooses the skill, a reference after a step opens it, and metadata on every request, chosen or not. ## The arithmetic to do before you install twenty The number that matters is how many skills one agent can load. In Kortix that is the grant list: a skill reaches no agent until the agent's `skills` line names it, because an omitted `skills` grants nothing ([Kortix](https://kortix.com/docs/developers#kortixyaml-reference)). Every name on it is billed at Discovery, on requests that use none. At the specification's rough figure, twenty skills carry about 2,000 tokens of name and description into every request. A hundred carry about 10,000. The task then gets whatever space is left: the conversation, the attached file and the instructions all share the window with that index. Each skill looks cheap alone, but the cost is carried by every other skill beside it, so two hundred descriptions at about 100 tokens each become a small document the model reads on every turn. ## The description is the whole first tier Discovery has two fields, and the folder fixes the name, so the description carries the decision. The specification requires 1 to 1,024 characters. It asks the description to say what the skill does and when to use it, with keywords a request would contain. Claude's documentation is blunt about the job: "until a Skill is triggered, only its name and description occupy context", and "The description is what Claude matches your request against when determining whether to trigger the Skill, so it must say both what the Skill does and when to use it." Kortix puts the same instruction in fewer words: "Write the description as 'when to use this', not only 'what this is'." ([Kortix](https://kortix.com/docs/guide#skills)) The [description guide](https://agentskills.io/skill-creation/optimizing-descriptions) goes past both. "Use imperative phrasing", with "Use this skill when..." in place of "This skill does..."; describe the user's intent rather than the skill's internals; and err on the pushy side, so a skill fires on a request that never names its domain. It also supplies the measurement. Label a set of requests, run each one three times, and a should-trigger query passes "if its trigger rate is above a threshold (0.5 is a reasonable default)". Testing is where the tier earns its tokens back. The 1,024 characters are rarely the binding limit; what the line must buy is a trigger on the right tasks and silence on the others. ## When a body moves into references The token recommendation and the 500 line ceiling do different jobs. One sets the reading cost at Activation; the other keeps the file reviewable. A body can pass both and still be the wrong shape: four pages of field tables around a five step procedure. Move the material a step does not need in order to choose the next step. Tables, long examples, API references, templates. The specification says "Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context", and it asks for relative paths from the skill root with no deep chain of references. What a file costs when opened depends on what kind it is, and Claude's page separates the two. A reference file's text enters the context when it is read. A script's code does not: "When Claude runs validate_form.py, the script's code never loads into the context window. Only its output ... consumes tokens." A deterministic check belongs in `scripts/`, where the price is the answer it returns. Explanatory material belongs in `references/`, where the price is its length. ## Three ways a skill spends more than it should The first is a reference too large to open on a real task. It is the failure a passing check hides. [skill-validator](https://github.com/agent-ecosystem/skill-validator) states it plainly: "A spec-compliant skill that has broken links or a 60k-token reference file will technically pass the spec but perform poorly in practice." A [validator](/validate-a-skill-md) checks structure and token counts, yet the cost lands on the first task that needs the file, which then spends the window it needed on documentation. The second is a body that grew into a manual. Every Activation pays for all of it, including the sections the task never touches. Subtraction is the fix. Keep the decision path in `SKILL.md`, and put the rest one level down, where it is read only if a step reaches for it. The third is a description broad enough to fire on everything. A skill described as "helps with documents" claims every PDF, every invoice and every summary, and pulls its body into tasks that did not need it. Each false trigger is an Activation nobody budgeted for. ## What the budget does not buy A skill that never triggers costs its metadata and nothing else. That is the quiet failure: no error, no visible spend, just a permanent line in every prompt for a file the agent never opens, and a silent tax on every request. The remedy runs the arithmetic backwards. Count the skills one agent can load and multiply by the metadata figure. Cut the entries that do not earn it, then measure what remains with the trigger test. The [agent skills specification](/agent-skills-specification) fixes the folder and the files. [How to write a SKILL.md](/how-to-write-a-skill-md) covers what belongs in each. What a team controls is what it installs and what each description claims, and those two decisions set the bill before any skill fires. Kortix runs on this format, with every skill a file in a git repo you own. Open source. Read it, fork it, audit it. ## What people ask about the loading model Two definitions, and the two costs a large skill folder raises. ### What is progressive disclosure in agent skills? Progressive disclosure is the staged loading of a skill: the agent sees a name and description at startup, reads the full SKILL.md only when a task matches, and opens bundled files only when a step needs them. Each stage adds context only when the one before it earned it. ### What is progressive disclosure? A pattern for loading information in stages instead of all at once. In agent skills the first stage is the name and description, the second is the body, and the third is whatever file a step reaches for. ### Does a bundled script's code count against the context window? No. When the agent runs a script, the code stays on the filesystem and only its output enters the context. A script that validates a form costs the tokens of the result, not the tokens of its source. ### Is a skill with many reference files expensive? Not while they sit unread. Files under references/ cost nothing until a step opens one, so a folder of ten guides costs what the one guide a task reads costs. Broad descriptions, not file count, are what raise the bill. ## Install the skills a task needs, then count what they cost at startup. Run it on Kortix Cloud, in your VPC, or on your own on-prem network. Self-host is free. [Try Kortix](https://kortix.com) · [Read the docs](https://kortix.com/docs/guide#skills) Session work reaches main through a change request · Merge is default-deny for agents