Shared Context

What are Claude Skills?

A skill is the simplest unit of teachable expertise for an AI coding assistant — usually a single Markdown file with a few lines of front matter. Here's what they are, what they aren't, and how to think about them.

The short definition

A skill is a packaged prompt or procedure — typically a single Markdown file — that an AI coding assistant can load on demand and follow as a recipe. It teaches the assistant how to do one specific thing: review code in your team's style, summarise a pull request, write a release note, draft a follow-up email, run a deployment checklist. The Markdown is the body. A short YAML front-matter block at the top tells the host tool when to surface it.

Anthropic introduced the SKILL.md shape in late 2025 as part of Claude Code's plug-in surface. Other tools — Gemini CLI, Cursor, Codex — converged on a near-identical idea, sometimes under a different name (Gemini calls them extensions; Codex calls them skills too). For day-to-day purposes you can treat them as the same thing.

What a skill file actually looks like

The minimum is something like this:

---
name: review-pr
description: Review a pull request in our team's house style.
user-invocable: true
---

You are reviewing a pull request. Apply these checks in order:

1. Does the PR title match our convention (feat:, fix:, chore:)?
2. ...

The front matter declares the skill's name and a short description. Optional fields tell the host how to expose it — user-invocable: true means a human can call it directly with a slash command. The body is just instructions. There is no DSL, no SDK, no compilation step. If you can write a Notion page, you can write a skill.

What a skill is not

It helps to draw clear lines:

  • A skill is not an agent. An agent is a configured sub-process — its own LLM call with its own tools and system prompt. Skills are content the host agent loads.
  • A skill is not an MCP server. An MCP server is a running process that exposes tools over a network protocol. A skill exposes a procedure in plain text. See Skills vs Agents vs MCPs vs Hooks.
  • A skill is not a "prompt template" in the old sense. Templates were fill-in-the-blank strings. Skills are full procedures, can reference other files in the same directory, and the host knows how to discover and invoke them.

Where skills live on disk

Each AI client has its own conventional location. Claude Code reads~/.claude/skills/<name>/SKILL.md; Cursor uses ~/.cursor/; Gemini CLI uses ~/.gemini/extensions/; Codex uses ~/.codex/skills/. The folder name is the slug; the file is always named SKILL.md on Claude. Tools scan their conventional directory at startup, so a freshly installed skill is available the next time the assistant launches.

A common pattern is to keep skills in your dotfiles repository or a shared team directory and symlink them into each tool's location, but that gets messy across platforms. Tools like Shared Context manage installation across every tool from a single library.

What skills are good at

  • Encoding tribal knowledge. The "the way we do X here" doc that lived in someone's head can become a skill the AI uses on every relevant task.
  • Repeated procedures. Anything a teammate would explain the same way each time — a release process, a debugging routine, a code-review rubric.
  • Style and voice. "Write our changelog in this format." "Reply to support tickets in this tone."
  • Composability. Skills can reference each other and are easy to bundle into collections grouped by role or workflow.

What skills are not good at

  • Live system access. A skill cannot call your CRM, read Gmail, or query a database — that's what an MCP server is for. A skill can however tell an MCP-aware host how to use those tools.
  • Long-running background work. Skills run in the host's main loop. Use a dedicated agent if the task needs an isolated context window.
  • Strict guarantees. Skills are guidance, not enforcement. If you need a rule to actually run on every commit, use a hook.

How skills get discovered

Two paths. User-invocable skills (the front-matter flag above) are promoted to slash commands — type /review-pr and the host loads the skill into context and runs it. Auto-loaded skills are picked up from a relevant scope by the host's discovery routine — for instance, Claude Code can be configured to always load every skill in a project's .claude/skills/ directory.

The trade-off is conventional. Auto-load means the model "always knows" how to do something but spends context tokens; user-invoked means zero token cost until called but relies on humans (or other skills) knowing the command exists.

The category is moving fast

Skills as a primitive are about a year old. Expect the spec to evolve — additional front-matter fields, richer discovery rules, better cross-platform compatibility — and expect each tool to add its own conventions on top of the shared base. Anthropic's documentation at docs.claude.com is the canonical source for the Claude side.

If you want to try it

Browse the skills hub for examples — every published skill on Shared Context is installable into any of the four supported tools with a single command. Reading three or four good skills tells you more about what the format is for than any spec ever could.