← All writing

AI Engineering

Agent Skills: Load Only the Instructions You Need

Mani G 3 min read

Papercut diorama of a wooden card catalog with many small drawers, one drawer open and glowing with folded paper tools inside.

Picture a system prompt that looks like a hostel noticeboard. Rules for writing tests. Rules for the deploy script. A paragraph about the team's weird date format. A warning, in capitals, about the staging database. The agent reads all of it on every single request, including the ones where you just want a variable renamed. Agent Skills fix that with an idea so plain it's almost embarrassing: put instructions in folders, and only open the folder you need.

What Agent Skills are

A skill is a directory with a SKILL.md file inside. The file starts with a little YAML header holding two required fields, a name and a description that says what the skill does and when to use it. Below that is ordinary Markdown with the actual instructions. Optional folders sit alongside: scripts/ for code the agent can run, references/ for longer docs, and assets/ for templates and data.

Anthropic originally developed the format and then released it as an open standard, now documented at agentskills.io. It travels well. Claude Code uses it, and so do Gemini CLI, Cursor and Microsoft's Agent Framework, each with its own docs on where skill folders live.

Progressive disclosure, explained simply

The clever bit is the loading order, which the spec calls progressive disclosure. It happens in three steps:

  1. At startup, the agent loads only each skill's name and description. The spec estimates about 100 tokens per skill.
  2. When a task matches, the agent reads the full SKILL.md body. The spec recommends keeping that under 5,000 tokens and 500 lines.
  3. Only if needed, it opens files from references/ or runs something in scripts/.

Microsoft's Agent Framework makes the steps visible as tools: the agent calls load_skill to pull in the body, read_skill_resource for extra files and run_skill_script to execute code. Gemini CLI goes a step further and asks for your consent before a skill activates and gains access to its folder.

A quick example

Say your team has an expense policy that the agent sometimes needs. As a skill, it's a folder called expense-report with a SKILL.md describing "use when the user files or checks an expense", a references/policy-faq.md with the long rules and a scripts/validate.py that checks a receipt. On a normal coding day, that skill costs the agent one short line of context. The day someone asks "can I expense this train ticket?", the agent opens the folder, reads the policy and runs the validator. The other 364 days, it stays shut.

What I like, and what I'd watch

What I like most is that skills are just files. They go in git, get reviewed in pull requests and work across tools. The bot that helps me run this blog leans on skills too, which is why it doesn't need my entire life story in every prompt.

What I'd watch is the description field. It's the only thing the agent sees at startup, so a vague one like "helps with PDFs" means the skill never fires, or fires at the wrong time. The spec's own advice is to say both what it does and when to use it, with the keywords a user might actually type. Scripts also deserve the same suspicion as any code you download, since an agent will happily run them.

This pairs nicely with Code Mode, which applies the same "load it when you need it" idea to API tools. One surprise from Anthropic's engineering post on code execution: an agent can save a working function to disk, add a SKILL.md beside it, and turn its own trick into a reusable skill. Should agents be allowed to write their own manuals?