Agent Skills

Agent Skills are folders of instructions, scripts, and reference files that give an AI agent expertise for a particular kind of task, packaged so the agent loads them only when a task calls for them. Each skill centers on a SKILL.md file whose short description tells the agent when to use it and whose body explains how. Anthropic introduced Agent Skills for Claude in October 2025 and published the format as an open standard at agentskills.io in December 2025. Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, VS Code, and dozens of other agents now read the same folders, so one skill works across all of them.

How Agent Skills Work#

A skill is a directory named after the skill, containing a required SKILL.md and optional scripts/, references/, and assets/ folders. SKILL.md opens with YAML frontmatter holding two required fields: a name of at most 64 lowercase letters, digits, and hyphens that matches the directory name, and a description of at most 1,024 characters that states what the skill does and when to use it. The Markdown body that follows holds the procedure, examples, and edge cases.

Agents load skills through progressive disclosure, which keeps a large library of skills cheap. At startup the agent reads only each skill's name and description, about 100 tokens per skill. When a request matches a description, it reads the full SKILL.md into its context window, and the specification recommends keeping that body under 500 lines and 5,000 tokens. Scripts and reference files load only when the instructions point to them, and a script's code never enters the context at all when the agent just runs it and reads the output.

Anatomy of a SKILL.md#

A retail team might give its agent this skill for shelf photos. The description carries the trigger words an agent matches against, and the body points to a script and a reference table that load only when needed:

---
name: shelf-audit
description: Counts products and finds empty facings in retail shelf photos. Use when the user asks about stock levels, gaps, or planogram compliance in store images.
---

# Shelf audit

1. Run `python scripts/detect_products.py <image>` on each photo. It prints one JSON line per product with its class, confidence, and box.
2. Compare the counts with the expected facings in `references/planogram.csv`.
3. Report each empty facing with its shelf position.
4. Send detections below 0.5 confidence to a person for review instead of counting them.

The agent sees only the two frontmatter lines until someone asks about shelves, and it opens the planogram file only at step 2.

Agent Skills vs. Related Concepts#

• Tools and function calling: A tool is one operation the agent can invoke, such as a database query or an object detection model. A skill teaches the agent when and how to combine tools for a task, with the validation rules and domain context the tools lack.
• Model Context Protocol (MCP): Connects an agent to live external systems through servers. Skills supply procedural knowledge, so agents commonly use both: a skill can tell the agent which MCP tools to call and in what order.
• System prompts and project instructions: Files such as AGENTS.md load into every session. A skill's body loads only for matching tasks, so an agent can carry hundreds of skills without crowding its context, the core idea of context engineering.
• Fine-tuning: Changes a model's weights to teach behavior. A skill changes only the context, so it can be edited, versioned, and reviewed like code and takes effect immediately.

Skills in Practice#

Skills package know-how that a general large language model (LLM) lacks or applies inconsistently: company brand rules, a team's release checklist, or a file format's quirks. Anthropic's public skills repository includes the Word, PDF, PowerPoint, and Excel skills that power Claude's own document creation. Ultralytics Agent Skills cover the computer vision lifecycle: a yolo router skill sends each request to a skill for model selection, datasets, training, tuning, inference, or export, and a platform-cli skill automates Ultralytics Platform with the ul cloud command line. Platform's own Ask AI assistant uses that platform-cli skill, and the same folders install in Claude Code with claude plugin install yolo@ultralytics or in other agents with npx skills add ultralytics/skills, which lets an agentic coding tool train and export a YOLO26 model from a plain-language request.

Security Considerations#

A skill runs with the agent's permissions, so installing a third-party skill resembles installing software. Its instructions can carry a prompt injection that redirects the agent, and its scripts can read files or send data anywhere the agent's environment allows. Teams review a skill's instructions, scripts, and dependencies before installing it, pin versions, and run skill scripts inside an agent sandbox with limited network access. The specification also defines an experimental allowed-tools field, a space-separated list such as Bash(git:*) Read that names the tools a skill may run without asking, and agents that support the field pre-approve those tools in their agent harness.