Skip to main content
Zubnet AI › Learn › Wiki › Agent Skills
Using AI

Agent Skills

Also known as: SKILL.md
Folders of instructions, scripts and resources that an agent discovers on its own and loads only when a task calls for them.

Why it matters

General-purpose models are capable but don't know your procedures: how your team formats reports, which steps your deployment needs, how to fill in a particular PDF form. Putting all of that in the system prompt doesn't scale, because every instruction costs context on every request, whether it's relevant or not.

Skills fix this with progressive disclosure. The agent only sees each skill's name and description up front, about 100 tokens apiece. When a task matches, it reads the full SKILL.md. If those instructions mention another file, it opens that one only if needed. An agent can have hundreds of skills installed and pay almost nothing until one is used.

Deep Dive

An agent skill is a folder that teaches an AI agent how to do a specific kind of task. At its core is one file, SKILL.md, which starts with a short YAML header (a name and a description) followed by plain Markdown instructions. The folder can also hold scripts, templates and reference documents that the instructions point to.

Anthropic introduced Agent Skills for Claude in October 2025 and published the format as an open standard in December 2025. Other agent tools, including OpenAI's Codex, GitHub Copilot, Cursor and Gemini CLI, have since adopted it, so the same skill folder can work across products.

Anatomy of a Skill

pdf-forms/
├── SKILL.md          # name, description, instructions
├── reference.md      # extra detail, read only if needed
└── scripts/
    └── fill_form.py  # code the agent can run

The header at the top of SKILL.md has two required fields:

name: pdf-forms
description: Fill in PDF forms. Use when the user asks to complete or extract fields from a PDF form.

The description is the most important line. It's all the model sees when deciding whether to load the skill, so it should say both what the skill does and when to use it.

Code Included

Skills can bundle scripts. This matters because some things are better done by code than by generating tokens: sorting a spreadsheet, extracting form fields, validating output. The agent runs the script and only sees the result, so the code itself never takes up context. This is also why skills need an environment with a file system and code execution, such as a coding agent or a sandboxed container.

Skills vs. MCP vs. Prompts

  • MCP connects an agent to external tools and data: your database, your ticketing system. It gives the agent new capabilities.
  • Skills teach the agent how to do something with the capabilities it already has. A skill can even describe how to use a particular MCP server well.
  • System prompts and project instruction files (like CLAUDE.md or AGENTS.md) are always loaded. They suit rules that apply all the time, while skills suit knowledge that's only needed sometimes.

Writing Good Skills

Start from real failures: watch where the agent struggles on a task, then write down what it was missing. Keep SKILL.md short and move details to separate files. Write for a smart newcomer: explain the non-obvious and skip what the model already knows. Test both that the skill triggers when it should and that it stays quiet when it shouldn't.

Security

A skill is instructions plus executable code, running with whatever access the agent has. A malicious skill can tell the agent to leak data or run harmful commands, which makes it a prompt injection delivered as a plugin. Install skills only from sources you trust, and read what's inside before you enable them, especially scripts and anything that calls the network.

← All Terms
ESC