# Skills Packaged know-how that an agent loads into its context only when a task needs it, keeping the context window free the rest of the time. > A skill is a folder of instructions, and optional scripts, for one task. Only its short description is always in context; the rest loads when needed. Source: https://ai-sw-factory.mellicci.dev/fundamentals/skills **Diagram:** A skill loads in stages, so only its short description occupies the context all the time. - Skill description — always in context - → task matches - Instructions — loaded when relevant - → if called for - Scripts, references — read or run on demand A skill packages the know-how for one task, such as "add a database migration safely". It is a folder with a `SKILL.md` file, which holds the instructions, and optionally scripts and reference documents. The point is *progressive disclosure*. The harness always loads a short name and description for each skill. It loads the full instructions only when the task matches, and the bundled files only when the instructions call for them. ## Why it exists Putting every procedure in an [instruction file](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files) does not scale. Ten procedures of 500 words each occupy the context window on every turn, including turns where none applies, and the model gets worse at finding the relevant rule. Leaving procedures out means the agent improvises them. ## How it works **Diagram:** Who does what — the harness finds and loads skills; the model only decides which one fits the task. - Harness scans — at session start, reads each skill's name and description - → a task arrives - Model picks — matches the task to a description — or you invoke it - → - Harness loads — puts the SKILL.md instructions into context - → only if needed - On demand: - Reference files — read when the instructions say - Scripts — run for a deterministic result A script's result is deterministic; the instructions around it are still guidance the model can misapply. ## Prompt + live data: the real power of skills A skill is more than stored instructions. It can combine a **prompt** (what to do and how) with **data fetched by scripts** (what is true right now) — and with **parameters** that make the same skill work for any issue, branch or file. **Diagram:** A parametric skill — arguments fill the placeholders, scripts fetch live facts, and the model starts from intent plus evidence instead of guessing. - Arguments — e.g. issue 42 — from you or the model - → fill placeholders - Skill · when loaded: - Instructions — the prompt — goal, steps, conventions - Scripts — fetch the issue, diff, schema, test results - → one prompt - Model starts — with intent and current facts There are three ways data gets into a skill, from least to most dynamic: - **Reference files** — static knowledge the model reads when the instructions point to it. - **Scripts the model runs** — the instructions say *run `scripts/check-migration.sh`*; the output lands in the context. The data is deterministic, but the model decides when to fetch it. - **Pre-injected data** — the harness runs commands *while loading the skill* and inlines their output, so the model's first read already contains the live facts (the current diff, the issue text, the failing test). Nothing is left to the model's memory or initiative. **Parameters** multiply this: `/fix-issue 42` fills the placeholders in the instructions — including the commands they tell the model to run — so one skill serves every issue. Because the model can pass arguments too, a skill becomes a small, reusable function the agent can call with different inputs. Support differs by agent: all three run scripts packaged with a skill; pre-injection and arguments are not universal yet — the agent pages list what each one documents. Injected commands and skill scripts run with your permissions, and a skill from a plugin or another repository is code you did not write. Read skills before you install them; see the [security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model) and [sandboxing](https://ai-sw-factory.mellicci.dev/fundamentals/sandboxing). ## Use it when - A procedure has several steps and applies to a subset of tasks. - The steps depend on files or scripts that should ship with the instructions. - You want the same procedure available to the whole team. ## Use something else when - The guidance applies to every task → [Instruction files](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files) - The step must run every time, automatically → [Hooks](https://ai-sw-factory.mellicci.dev/fundamentals/hooks) - The work needs its own isolated context → [Subagents](https://ai-sw-factory.mellicci.dev/fundamentals/subagents) - The agent needs a tool it does not have → [MCP](https://ai-sw-factory.mellicci.dev/fundamentals/mcp) ## Key terms - **Skill** — a folder with `SKILL.md`, plus optional scripts and references. - **Progressive disclosure** — staged loading: description, body, resources. - **Skill description** — the always-loaded text that triggers selection. - **Bundled script** — deterministic code shipped inside the skill.