What Are Claude Skills?

Open any skill and you find the same skeleton. At minimum there is one file, SKILL.md, sitting in a folder named after the skill. Larger skills grow subfolders around it:

• SKILL.md — the only required file. YAML frontmatter up top, markdown instructions below.
• scripts/ — executable helpers (Python, Bash, Node) the agent runs instead of writing throwaway code.
• references/ — longer docs loaded only when needed: API references, style guides, checklists.
• assets/ — templates, fonts, or files the skill's output is built from.

The frontmatter has two fields that matter. name is the skill's slug — lowercase, hyphenated, matching the folder. description is the single most important line in the whole skill: it is what the agent reads to decide whether this skill applies to your request. Write it as when to trigger, not what the skill is — "Generate a slide deck from a markdown outline" triggers; "A presentation tool" does not.

A minimal working skill is just this:

---
name: changelog-writer
description: Write a release changelog from merged PR titles and commit messages when the user asks for release notes.
---

# Changelog Writer

When asked for a changelog:

1. Run `git log --oneline` between the last tag and HEAD.
2. Group commits into Added / Fixed / Changed / Removed.
3. Write one line per change, user-facing language only.
4. Skip internal refactors unless they change behavior.

Progressive disclosure is the reason installing fifty skills does not destroy your context window. A skill loads in three layers, and each layer costs more than the last:

1. Metadata (always loaded). Every installed skill's name and description — a few dozen tokens each — sits in context so the agent knows what exists.
2. Instructions (loaded on trigger). When a request matches a description, the agent reads the SKILL.md body — the actual how-to.
3. Attached files (loaded on demand). Scripts, references, and assets are pulled in only when the instructions call for them, and their contents can be read piecewise rather than wholesale.

The design consequence: keep SKILL.md bodies short and push detail into references/. A skill whose body is a 5,000-word essay consumes that context on every trigger; the same content moved to references/ only costs tokens when the agent actually needs it.

Four mechanisms overlap enough to confuse everyone, but they answer different questions:

• Skills teach the agent how — packaged expertise and workflows, loaded on demand.
• MCP servers give the agent access — live tools and data (a database, an API, your calendar) exposed over a protocol.
• Subagents change who — a separate agent with its own context and tools for a delegated task.
• System prompts / CLAUDE.md set always-on rules — conventions that apply to every message, not just matching tasks.

In practice they compose: a skill might tell the agent when to call an MCP server's tool; a project CLAUDE.md sets house rules while skills handle the repeatable jobs. If the knowledge is conditional ("only when making slides"), it belongs in a skill; if it is unconditional ("never commit secrets"), it belongs in the system prompt. For the operational side of this comparison on the CLI specifically, see Claude Code skills.

Three paths, in order of convenience:

1. The skills CLI. npx skills add owner/repo copies the skill from GitHub into the right folder — works for Claude Code, Codex, and most SKILL.md runtimes. The npx skills page covers the syntax and version pinning.
2. Manual copy. Clone the repo (or just the skill folder) into ~/.claude/skills/ for a user-level install available everywhere, or into .claude/skills/ inside a project for project scope.
3. Plugin marketplaces. Claude Code and Codex both have plugin flows (e.g. /plugin marketplace add owner/repo then /plugin install name@repo) that keep skills updated automatically.

Two common failure modes after installing: the skill isn't discovered — skills register at session start, so restart the agent — and the folder structure is wrong, e.g. an extra nesting level like ~/.claude/skills/repo-name/repo-name/. The SKILL.md must sit one level under the skills directory.

Start with a job you do repeatedly, not with prose. A good first skill: "write our release changelog." Then the loop is:

1. Do the task once manually and note the steps you'd give a competent colleague.
2. Write the SKILL.md — name, a description phrased as when to trigger, and the steps as a numbered procedure.
3. Trigger it with a natural request and watch whether the description fires and the steps produce what you wanted.
4. Iterate on the description first. Misfires and non-triggers are almost always a description problem, not an instruction problem.

The example in the first section is a complete working skill — copy it, rename it, and adjust the steps. When the skill is ready to share, run it through skillopt for a measured tighten-up, and check the best Claude skills list to see what well-written skills look like.

Anthropic introduced the format with the official Claude skills repo — the document skills (docx, xlsx, pptx, pdf) plus skill-creator and mcp-builder — and it became a de facto standard fast: OpenAI's Codex reads the same SKILL.md files, Google's Antigravity IDE adopted them, and Vercel shipped an installer CLI for the whole ecosystem. Community catalogs like awesome Claude skills collect what the ecosystem publishes.

The practical consequence of the standardization: a skill is no longer tied to one vendor's agent. Write a SKILL.md once and it follows you across Claude Code, claude.ai, Codex, and whatever adopts the format next — which is why skills have become the default packaging unit for agent expertise, the way extensions became the unit for editor features.

One decision every install forces: scope. Skills under ~/.claude/skills/ are user-level — available in every project, every session. Skills under a repository's .claude/skills/ are project-level — active only inside that codebase. The rule of thumb: personal productivity skills (decks, screenshots, note workflows) live at user level; anything encoding how your team works (changelog format, review checklist, release procedure) lives at project level, where it can be committed and shared with the repo.

Committed project skills are the underused pattern — they turn tribal knowledge into versioned, reviewable configuration. A new teammate's agent inherits the team's conventions on day one because the skills ship with the clone. And because a project skill is just a folder in the repo, it goes through the same pull-request review as any other change — nobody ships a behavioral change to the shared agent without a diff review.