← back to the archiveCover illustration for “Agent skills: packaged know-how an agent loads on demand”
TERM7mo ago·Published · Updated ·by Andy Padia

Agent skills: packaged know-how an agent loads on demand

In short: Agent skills are folders of instructions, scripts and files that an AI agent loads only when a task needs them, which keeps most of them out of the prompt.

Agent skills are folders built around a SKILL.md file, with a name, a description and instructions plus optional scripts, templates and reference files, that an AI agent loads when a task calls for them. Only the name and description sit in context by default. Anthropic introduced the format on 16 October 2025 and published it as an open standard on 18 December 2025.

Agent skills in plain words

A shelf of well-labelled binders. The agent reads the spine labels all the time and pulls a binder down on demand, when the job needs it.

How it works

At start-up the agent sees each skill's name and description. When your request matches, it reads the full SKILL.md, follows its steps and runs any bundled scripts. Extra files in the folder load only when the instructions point to them, so one agent can carry many skills without filling every prompt.

The Claude Code documentation, read in November 2026, describes three homes for a skill: personal, shared in a project repository or bundled in a plugin.

Example

---
name: release-notes
description: Use when asked to write release notes from merged pull requests.
---
1. Run scripts/merged_prs.sh to list PRs since the last tag.
2. Group by label: feature, fix, chore.
3. Write notes in docs/RELEASE_TEMPLATE.md format. Skip chores.

Where you'll meet it

  • Claude.ai, Claude Code, the Claude Agent SDK and the Claude Developer Platform
  • Plugins that bundle skills
  • Team repositories sharing house workflows
  • Other AI tools that adopt the Agent Skills open standard

What it changes for you

Skills are how teams turn "the way we do it here" into something an agent can repeat. For developers, the description is the trigger: the documentation says it helps the agent decide when to load the skill, so write it like a search query. For leads, skills are reusable assets worth reviewing and versioning, much like internal libraries.

Agent skills vs subagents

A skill adds instructions to the current agent's context. A subagent is a separate agent with its own context that returns a result.

Common mistake

My view: writing skill descriptions that say what the skill is instead of when to use it. "Release notes skill" rarely triggers; "Use when asked to write release notes from merged PRs" does.

Subagent · Claude Code · Slash commands · Context engineering · AGENTS.md and CLAUDE.md

From the archive: A 311-skill catalogue is a routing problem

Write each skill description to say when to use it, because that line is the trigger.

#field-guide#claude-code#agents#skills#context

Sources

  1. anthropic.com/research/equipping-agents-for-the-real-world-with-agent-skills
  2. code.claude.com/docs/en/skills
← older drop
LLM tracing: following one AI request step by step
newer drop →
Reasoning model: an LLM that thinks before it answers

related drops

explore all 557 drops →
← back to the archiveday 175