What Is an AI Agent Skill?

What is an agent skill made of?

Open the folder and there is not much to it. One required file, SKILL.md, carries YAML frontmatter and a Markdown body. Beside it sit three conventional directories: scripts for code the agent runs, references for documents it opens on demand, assets for templates and lookup data. Nothing else is mandatory, and a sharp description with forty lines of body beats six hundred lines nobody reads.

---
name: monthly-close-report
description: Builds the month-end close packet from the exported ledger CSV. Use when someone asks for close, month-end, or the finance summary.
license: Proprietary. LICENSE.txt has complete terms
compatibility: Requires Python 3.14+ and read access to /finance/exports
allowed-tools: Read Bash(python:*)
---

# Monthly close report

1. Read /finance/exports/ledger-<month>.csv.
2. Reconcile against last month's closing balance in references/BALANCES.md.
3. Stop and ask before writing anything to the shared drive.

Two frontmatter fields are required and four are optional. The constraints are strict enough that a typo keeps the skill from loading at all, with no error and no clue.

The name has to match the parent directory exactly, and consecutive hyphens are rejected outright. Those two rules account for most skills that quietly never load.

How does an agent decide to use one?

It reads the description, and nothing else. At startup the host loads only the name and description of every installed skill into the system prompt, roughly a hundred tokens each. The body stays on disk. When a request matches a description, the agent reads SKILL.md, and only then do the instructions cost context. A bundled script runs and returns its output, so the code never enters the window.

This is why installing thirty skills is cheap and a vague description is expensive. A skill described as helping with reports never fires. Name the artifact, the source file, and the words a client would use, and it fires on the right sentence and stays quiet otherwise.

What a skill cannot do

A skill is instructions and files. It does not create capability. Tools come from the host: the file system, the shell, the browser, whatever MCP servers you connected. If your agent cannot send email today, a skill describing how to send email fails at the send step.

• It cannot grant a credential, an API key, or network access the host withholds.
• It cannot raise a permission ceiling. Approval prompts still fire on write, send, spend, delete, and deploy.
• It cannot rescue a bad procedure. Weak steps get followed faithfully, at speed.
• It cannot travel between surfaces. Claude Code, claude.ai, and the API hold separate copies.

Where a skill runs changes what it can reach. On the Claude API it sits inside the code execution container, no network access and no package installs at run time. In Claude Code the same file has the reach of any other program on your machine. Same skill, very different blast radius.

Where do skills install?

Copies do not sync. A skill uploaded to claude.ai belongs to one user and never appears in the API or in Claude Code. Keep the git repository as the source of truth and treat every install location as a deploy target.

How do you review one before installing it?

unzip -l vendor-skill.zip
find ./vendor-skill -type f | sort
grep -rniE 'curl|wget|fetch|requests\.|urllib|https?://' ./vendor-skill
grep -rniE 'rm -rf|chmod|sudo|[.]env|api_key|token|credential' ./vendor-skill
skills-ref validate ./vendor-skill

The validator checks frontmatter and naming, not intent, so the reading is still yours. The pattern that should stop you cold is a skill that pulls content from an external URL and then acts on what it finds. That is instruction laundering, and it survives a casual read because the hostile text is not in the folder yet. Anthropic's own guidance is blunt: audit anything from a source you do not trust, and treat installing a skill like installing software.

What makes it a product instead of a prompt folder?

Versioning, mostly. A prompt folder is a pile. A packaged skill declares its inputs, outputs, approval gates, known limits, license, and what changed in the last release. You can diff it and roll it back. Hand it to a new hire and they run the same procedure the agent runs, which is the real test of whether it was ever written down.

That is the line the Agent Systems catalog is built on. Agent Ready is free and lays the foundation. Each specialist skill is $149, and the four-skill bundle is $447 against a $596 separate total.