Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

What are agent skills?

Agent skills are folders of instructions an AI agent loads when a task calls for them. Each has a SKILL.md file with a name, a description and Markdown instructions, plus optional scripts and reference files. The agent sees only the descriptions until a skill is relevant, then reads the whole file. Anthropic published the format as an open standard.

Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.

How it works

The agent keeps every skill's description in view, loads one SKILL.md when a task matches, and opens its supporting files only if told to.at startupyouagentClaude Code and othersevery skill:name and descriptionone SKILL.mdscripts/, references/1. descriptions only2. a matching task3. loads the full file4. only when needed
  1. You write a folder with a SKILL.md: YAML frontmatter with a name and a description, then Markdown instructions. Scripts and references sit beside it.

  2. At startup the agent loads only each skill's name and description, around a hundred tokens apiece.

  3. When a task matches a description the agent reads the full SKILL.md. In Claude Code you can also run one yourself by typing its name after a slash.

  4. Supporting files are read only when the instructions point at them, so a large reference costs nothing until it is needed.

  5. Once loaded, the instructions stay in context for the rest of the conversation.

Source: Agent Skills specification

Agent skills versus system prompts and CLAUDE.md

A system prompt and a CLAUDE.md file are always on. Everything in them is read every session, whether today's task needs it or not, and that cost grows with every rule you add. A skill is off until it matches. Its description is the only part the agent carries around, and the standard puts that at roughly a hundred tokens. The body, recommended at under five thousand tokens, loads when the skill is activated. Files in scripts/, references/ and assets/ load later still, only when the instructions point at them.

This three-level loading is what the standard calls progressive disclosure, and it is the whole reason skills exist. It lets a team keep a long, exact procedure for releasing a package, or a hundred-line style guide for a document type, without paying for it in every unrelated conversation.

Example: a release skill

The folder name and the name field must match. A minimal skill is one file:

---
name: release
description: Cut a release of this package. Use when asked to release, tag or publish a version.
---

1. Run the test suite and stop if anything fails.
2. Bump the version in package.json and update CHANGELOG.md.
3. Commit, tag the commit with the version, and push the tag.

The description does two jobs: it says what the skill does and when to use it, and it carries the words a person would use when asking. The spec's own bad example is a description that just says it helps with PDFs. Say which PDF tasks, and name them the way users do.

In Claude Code this file at .claude/skills/release/SKILL.md becomes /release for everyone in the repository, or at ~/.claude/skills/release/SKILL.md for all your projects. Claude Code's older .claude/commands/ files were folded into skills and still work. Its own additions include disable-model-invocation: true so only you can trigger a skill, user-invocable: false for the reverse, allowed-tools to pre-approve tools for that turn, and context: fork to run the skill in a subagent. Intraface ships a skill this way: npx intraface agent install adds the Intraface MCP server to Claude Code along with a SKILL.md that tells the agent how to pull, edit and publish a board.

Why it matters

Skills are how teams make an agent good at their specific work rather than work in general. The procedure that one senior engineer carries in their head becomes a folder anyone's agent can follow, checked into the repository and reviewed like code. Because the format is an open standard with a reference validator, the same folder can move between agents that support it instead of being rewritten for each.

Common mistakes

  • A vague description. If the description doesn't contain the words people use, the skill never triggers, and if it is too broad it triggers for everything. Put the main use case first.
  • A giant SKILL.md. Keep it under 500 lines and move the reference material into files beside it. Everything in the body is loaded on activation, whether or not the task needs it.
  • Deep reference chains. Keep file references one level from SKILL.md. An agent that has to follow links three deep often stops early.
  • Uppercase or underscores in the name. The name allows only lowercase letters, digits and single hyphens, and must match the directory.
  • Assuming the tool grant lasts. In Claude Code, allowed-tools applies to the turn that invoked the skill and clears on your next message, though the instructions stay loaded.

FAQ

What is in a SKILL.md file for agent skills?
YAML frontmatter, then Markdown. The frontmatter needs name, up to 64 lowercase characters and hyphens matching the folder name, and description, up to 1,024 characters. Optional fields are license, compatibility, metadata and allowed-tools. The body is free-form instructions, recommended under 500 lines.
Are Claude skills the same as agent skills?
Claude skills follow the Agent Skills standard, so a skill written for Claude Code is a valid agent skill. Claude Code adds fields the standard does not define, such as disable-model-invocation, context: fork and hooks. Other agents ignore fields they don't know, so the same folder still loads.
How are agent skills different from a CLAUDE.md file?
CLAUDE.md is read in full at the start of every session, so it should hold what applies to all work. A skill's body loads only when its description matches the task. Move anything long or occasional into a skill and keep CLAUDE.md short.

Stop sending HTMLover Slack.

Create an account in a minute, connect your coding agent, and make your first board.