Skills: Concepts

A skill is a folder with a SKILL.md file that teaches an agent how to do something specific: a procedure, a house style, domain knowledge, or a workflow backed by scripts. Skills follow the open Agent Skills standard, so one skill can work in Claude Code, Claude.ai, the Claude API, Cursor, Codex, and other compatible tools.

Anatomy

my-skill/
├── SKILL.md            # Required: frontmatter + instructions
├── references/         # Optional: detailed docs, read only when needed
│   └── api.md
├── scripts/            # Optional: executable helpers the agent RUNS
│   └── validate.py
└── assets/             # Optional: templates, schemas, images used in output
    └── report-template.md

---
name: my-skill
description: Does X for Y. Use when the user asks about Z or works with .abc files.
---

# My Skill

## Workflow
1. ...

Progressive disclosure: why skills are cheap

A skill loads in three stages, so you can install dozens without filling the context window:

Level	What’s loaded	When	Typical size
1. Metadata	name + description	Always, at session start	~100 tokens per skill
2. Instructions	The body of SKILL.md	When the agent decides the skill is relevant	Keep under ~5k tokens (< 500 lines)
3. Resources	Files in references/, assets/, script output	Only when the instructions point to them and the task needs them	Unlimited, but only what’s read counts

This leads to three design rules:

1. The description does the selling. At level 1 it’s the only thing the agent sees, so a vague description means the skill never loads.
2. The body is a table of contents plus the core workflow. Detail goes into reference files.
3. Scripts are executed, not read. Only their output enters the context, so a 500-line validator costs almost nothing.

How a skill gets invoked

Mode	How	Control
Automatic	The agent matches the request against descriptions	Default
Explicit	The user types /skill-name (Claude Code, Cursor) or asks for it by name	Always available
Manual only	disable-model-invocation: true	For risky or rarely wanted skills (deploys, bulk edits)
Scoped	paths: globs (Cursor) or a nested .cursor/skills/ in a subfolder	Only offered for matching files

What makes a good skill

Good fit	Poor fit
A procedure you repeat (“how we cut a release”)	General knowledge the model already has (“how to write Python”)
Org-specific facts (schemas, naming, brand voice)	Facts that change weekly (use an MCP server or live docs instead)
Fragile multi-step operations backed by scripts	Standing rules for every task (use a rule or AGENTS.md)
Instructions for using an MCP server well	Something needing credentials or a persistent connection (MCP)

Skill archetypes

1. Knowledge skill: reference material such as a database schema, brand guidelines, or API conventions. It’s mostly references/.
2. Workflow skill: a numbered procedure with checkpoints, such as a release process or incident report.
3. Tool skill: scripts that do the heavy lifting, such as a PDF form filler or data validator.
4. Output-format skill: templates and examples for a specific kind of artefact, such as commit messages, PRDs, or slide decks.
5. Integration skill: teaches how to use a particular MCP server or CLI effectively: which tool to use when, and the gotchas.

Security model

A skill can tell the agent to run code. Treat third-party skills like third-party code. Before installing one:

• Read every file, especially scripts/.
• Look for network calls, data exfiltration, or instructions to ignore other guidance.
• Prefer skills from trusted sources, and pin versions.

Next: Step-by-step: build a skill