Skip to content
All guidesUsing the tools

What an AI skill is, how it loads, and how to check it helps

A skill is a folder of instructions that an AI agent opens only when the job calls for it. This guide covers what is inside one, why that leaves the agent less to carry, the skill collections people bookmark most, the rules that matter and a simple test.

7 min read

If you use an AI agent, meaning an AI tool that carries out tasks for you, such as Claude Code, Codex or GitHub Copilot, you will have seen the word skill. A skill is a folder of notes on how one job is done, much like the notes you would hand a new colleague. The agent opens the folder only when that job comes up.

What a skill is

Anthropic introduced skills on 16 October 2025 and described them as organised folders of instructions, scripts and resources that agents can discover and load dynamically. On 18 December 2025 the format was published as an open standard at agentskills.io, meaning a public format that any tool can adopt. The standard defines a skill as a folder containing a SKILL.md file.

SKILL.md is a plain text file. It starts with two required fields, a name and a description, and then carries the instructions in ordinary writing. The folder can also hold three optional subfolders.

  • scripts holds code the agent can run for steps that have one right answer.
  • references holds longer documents the agent reads only when it needs them.
  • assets holds templates and files to reuse.

Because the format is an open standard, the same folder works in more than one product. We confirmed support on each vendor's own documentation for Claude, OpenAI's ChatGPT and Codex, GitHub Copilot, VS Code, Cursor and Gemini CLI. The standard's site lists 46 tools in total.

Why skills are useful

A general model knows how to write a report. It does not know how your firm writes one, which sections come first, which figures must be checked, or where the finished file goes. Without a skill you explain that every time, or you paste it into a standing instruction file that the agent carries into every conversation. A skill lets you explain the job once and have later runs follow it.

How a skill loads

First, one term. Context is everything the agent is holding in mind while it works, including your instructions, the conversation and any files it has read. It is measured in tokens, the units a model reads, and one token is roughly three quarters of an English word. The standard describes three stages of loading. Each costs more context than the one before and happens less often.

  1. At start-up the agent loads only the name and description of each skill, about 100 tokens apiece. This is how it knows the skill exists.
  2. When a task matches a description, the agent reads the instructions in SKILL.md. The standard advises keeping these under 5,000 tokens.
  3. Reference files are opened only if the instructions point to them. Scripts run outside the model's context, and only their output comes back.

Why bloat in the always-on context matters

Everything an agent has loaded competes for its attention. Anthropic's guidance on context engineering calls context a finite resource with diminishing returns and recommends the smallest set of high-signal tokens that gets the outcome. Chroma's 2025 study of 18 models found that performance grows less reliable as the input gets longer.

There is direct evidence on instruction files too. A 2026 study (Gloaguen and others) tested the context files that coding agents read at the start of every run, such as AGENTS.md. It found the files did not generally improve task success and raised running cost by over 20% on average. The authors concluded that such files are useful for non-standard practices and that anything added to improve performance should be tested first. Anthropic's Claude Code documentation advises keeping its always-loaded file, CLAUDE.md, under 200 lines, because longer files are followed less closely, and moving task-specific material into skills.

The three skill collections with the most stars

GitHub is the site where most open-source code is shared. A project there is called a repository, and a star is a user's bookmark on one. We searched GitHub for repositories built around SKILL.md files and ranked them by stars, read from the GitHub API on 17 September 2026. Stars measure attention and say nothing certain about quality, so treat this as a list of where to look.

  1. obra/superpowers, 288,060 stars. Fourteen skills covering planning, writing the test before the code, and debugging. Free to reuse under the MIT open-source licence.
  2. mattpocock/skills, 264,347 stars. Thirty-eight skills from one developer's own daily setup. Same licence.
  3. affaan-m/ECC, 260,993 stars. A wider agent setup in which skills sit beside ready-made agents and commands. Same licence.

Anthropic's own reference repository, anthropics/skills, is fourth with 176,867 stars. The collection with the most stars holds only fourteen skills, which fits the research below.

Rules that matter when you write one

These come from Anthropic's authoring guide and the open standard.

  • Write the description to say what the skill does and when to use it. It is the only part that is always loaded, and the agent chooses from it.
  • Add only what the model does not already know. The guide's test for each paragraph is whether it justifies its token cost.
  • Keep SKILL.md under 500 lines and move detail into reference files, one level deep from SKILL.md.
  • Use a script for any step with one right answer. The guide calls scripts more reliable than generated code, and they save tokens.
  • Test the skill with every model you plan to use it with.

Treat a skill like installed software

A skill can carry code and instructions that the agent will act on. Anthropic's documentation says to use skills only from sources you trust. A January 2026 study analysed 31,132 skills from two marketplaces and found that 26.1% contained at least one security weakness, with 5.2% showing patterns that suggested malicious intent. Skills with scripts were 2.12 times more likely to contain one. Scripts are still the right choice for fixed steps. The point is to read a skill before you install it, scripts included.

How to check a skill helps

Anthropic's guide says to create evaluations before writing extensive documentation. The method is short.

  1. Pick three or more real tasks where you can tell a pass from a fail.
  2. Run them without the skill. This is the baseline.
  3. Run the same prompts on the same model with the skill.
  4. Compare pass rate, time taken and tokens used.
  5. Keep the skill if it passes more often. Fix it if it helps some tasks and hurts others. Delete it if nothing changes, because then it only costs context.

Anthropic's skill-creator skill automates this. It runs one agent with the skill and one without, reports pass rate, time and tokens for each, and flags checks that pass either way. It also tests whether the description triggers on the right requests.

Independent research supports the effort. SkillsBench ran 87 tasks across 18 model and tool combinations. Curated skills raised the average pass rate from 33.9% to 50.5%. Focused skills covering three parts or fewer beat larger bundles, and smaller models with skills can match larger models without them. The gain ranged from 4.1 to 25.7 percentage points, so the same skill can matter a great deal in one setup and little in another.

Sources

Keep reading