Agent Skills Guide

What is this about?

An Agent Skill is a reusable instruction package that teaches an AI agent how to handle a recurring kind of work. Instead of pasting the same checklist, procedure, or playbook into chat over and over, you store it once as a SKILL.md-based capability and let the agent load it when relevant.

Source scope as of June 25, 2026

This guide is based primarily on the Agent Skills open specification at agentskills.io and the current Claude Code skills documentation. The open standard defines the portable skill format; Claude Code extends it with product-specific features such as invocation control, subagent execution, and dynamic context injection.

1. What a skill is

A skill is best understood as a small capability package:

a SKILL.md file with metadata and instructions,
optional scripts/ the agent can run,
optional references/ the agent can read on demand,
optional assets/ such as templates or schemas.

Typical examples:

a release checklist,
a code-review procedure,
a debugging workflow,
a deployment recipe,
a project-specific "how to run this app" guide,
a house style for architecture docs or API design.

The core idea is simple:

prompts are one-off,
skills are reusable.

2. Skill vs. prompt vs. tool vs. MCP

These concepts are related, but they are not the same thing.

Concept	What it is	Best for
Prompt	One instruction in a conversation	One-off requests
Skill	Reusable instructions plus optional files and scripts	Repeatable workflows
Tool	A callable function or capability	A single concrete action
MCP server	A protocol-based integration that exposes tools, prompts, or resources	External systems and structured access
Project memory (`CLAUDE.md`, repo docs, etc.)	Standing context about a repo or organization	Facts, conventions, constraints

Good rule of thumb:

if the agent needs one action, use a tool;
if the agent needs a procedure, use a skill;
if the agent needs background facts, use project memory or docs.

3. Why skills matter

Without skills, agents tend to produce generic output:

average-looking frontend work,
shallow reviews,
inconsistent rollout steps,
rediscovered setup instructions,
fragile multi-step workflows.

With skills, you shift the defaults.

That is the real value: not "the model can technically do more", but "the model does the right kind of work more consistently."

Skills are especially useful when:

you keep repeating the same instructions,
a procedure spans multiple steps,
quality depends on a checklist,
the work needs project-specific context,
you want the same behavior across a team.

4. How skills work

The current skills model uses progressive disclosure.

At a high level:

the agent knows the skill exists from its metadata,
it loads the full SKILL.md body when the task looks relevant,
it loads scripts, references, and assets only if they are needed.

That matters because long instructions no longer need to sit in every chat from the start.

Why this is better than a giant system prompt

The skill body and supporting files cost almost nothing until the skill is actually used. That makes skills a better place for procedures, references, and playbooks than stuffing everything into permanent always-on context.

In tools like Claude Code, skills can be used in two ways:

automatically, when the description matches the task,
manually, by invoking the skill directly, for example with /skill-name.

5. Where skills live

The exact locations depend on the client, but the general pattern is:

Scope	Typical location	Who it applies to
Personal	`~/.claude/skills/<skill-name>/SKILL.md`	Your own work across projects
Project	`.claude/skills/<skill-name>/SKILL.md`	One repository or workspace
Enterprise / managed	centrally configured	An organization
Plugin-provided	inside a plugin bundle	Wherever that plugin is enabled

Practical guidance:

put personal working habits in personal skills,
put repo-specific workflows in project skills,
put governed team standards in enterprise-managed skills.

6. What a skill usually contains

The open standard is intentionally simple.

Required minimum

A skill directory needs at least:

skill-name/
└── SKILL.md

Common full shape

skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

`SKILL.md`

The SKILL.md file contains:

frontmatter metadata such as name and description,
the actual instructions the agent should follow.

`scripts/`

Use scripts when the skill needs executable help, for example:

gather data,
validate output,
run checks,
transform files,
avoid forcing the model to recreate fragile logic from scratch.

`references/`

Use references for:

long procedures,
domain-specific notes,
API details,
examples that should only load when needed.

`assets/`

Use assets for:

templates,
schemas,
static examples,
lookup files.

7. When to create a skill

Create a skill when the work is repeatable enough to deserve a named workflow.

Strong candidates:

code review
deployment
release notes
meeting prep
environment setup
architecture decision records
test strategy
incident response checklists
"run this project locally" recipes

Weak candidates:

a one-time answer,
generic knowledge the model already knows,
a tiny instruction that is easier to say directly than to maintain as a skill.

A useful test

If you have pasted roughly the same instructions two or three times already, that is often enough evidence that a skill should exist.

8. What makes a good skill

A good skill is:

discoverable: the description clearly says what it does and when to use it,
scoped: it covers one job well instead of five jobs badly,
practical: it helps the agent complete real work, not just talk about it,
lightweight: the main file stays concise and pushes detail into references when needed,
opinionated where it matters: it teaches defaults, checklists, and quality bars.

Common mistakes:

vague descriptions like "helps with coding",
oversized SKILL.md files that should be split up,
mixing facts, policy, and procedures into one blob,
creating a skill for something that should just be a tool,
writing rules without explaining why they matter.

9. Typical examples

Here are a few realistic examples of what a skill can do:

Skill idea	What it teaches the agent
Code review	Look for regressions, risks, missing tests, dead code, and unsafe changes
Run / verify app	Start the project correctly, including env vars, services, and launch steps
API design	Apply your resource conventions, naming rules, and response patterns
Security review	Check auth boundaries, secrets, injection risks, and unsafe defaults
Docs publishing	Write docs in the house style and validate links before shipping

This is why skills sit between "mere prompting" and "full integration". They encode working method.

10. Decision guide

If you want to…	Do this…
reuse a workflow you keep repeating	create or install a skill
give the agent one concrete capability	add or use a tool
store enduring repo conventions	use project docs or `CLAUDE.md`-style memory
teach a complex process with examples and files	use a skill with `references/` and `scripts/`
make an agent work better across a whole team	share project or enterprise skills

11. Where to go next

Must-Have Skills — curated examples of high-value skills to install first
Skill Authoring — how to design and write a SKILL.md well

If you are new to the concept, read this page first. If you already know you want to create or improve skills, jump straight to Skill Authoring.

1. What a skill is​

2. Skill vs. prompt vs. tool vs. MCP​

3. Why skills matter​

4. How skills work​

5. Where skills live​

6. What a skill usually contains​

Required minimum​

Common full shape​

SKILL.md​

scripts/​

references/​

assets/​

7. When to create a skill​

8. What makes a good skill​

9. Typical examples​

10. Decision guide​

11. Where to go next​

12. Official links​