# Claude Code skills: what they are, how to write one, and where to find them

A skill is a folder of instructions Claude loads only when it needs them. How to write one in five lines, where to get good ones, and how a team shares them.

Published 2026-10-07 by Richard Kaminsky and Mitchell Lipyansky, the co-founders of Poly. Canonical: https://usepoly.co/claude-code-skills
Poly is a multiplayer AI coding workspace: a shared room where your team works with one AI agent, together. Free to start: https://usepoly.co/

**A Claude Code skill is a folder with a SKILL.md file: a short description at the top, then instructions, plus any scripts or reference files it needs. Claude reads every skill's description at the start of a session and loads the rest only when a task matches, or when you type /skill-name. Put personal skills in ~/.claude/skills and project skills in .claude/skills, where they're shared through git; install other people's from Anthropic's skills repository or the official plugin marketplace with /plugin. Custom slash commands have been merged into skills, and the format is an open standard that Codex, Cursor and GitHub Copilot read too.**

## Key takeaways

- **Cheap until used:** each skill costs about 100 tokens of context for its name and description; the body loads only when needed ([Anthropic](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)).
- **Two ways to run:** Claude picks one when a task matches its description, or you type `/skill-name`.
- **Commands are skills now:** `.claude/commands/deploy.md` and `.claude/skills/deploy/SKILL.md` both make `/deploy`, and old command files keep working.
- **Where to find them:** Anthropic's [skills repository](https://github.com/anthropics/skills) and the official marketplace, which Claude Code adds on first launch.
- **Only install skills you trust:** a skill can include scripts, and a plugin "can execute arbitrary code on your machine."

*Where skills live and who gets them, from Anthropic's docs, October 7, 2026.*

| Where | Path | Who gets it |
| --- | --- | --- |
| Personal | ~/.claude/skills/<name>/SKILL.md | You, in every project |
| Project | .claude/skills/<name>/SKILL.md | Everyone on the repository |
| Plugin | Installed with /plugin | Whoever installs the plugin |
| Enterprise | The managed-settings directory | Everyone in the organization |
| Claude app | Created on claude.ai | You; synced into Claude Code |

## What is a skill in Claude Code?

A folder with a SKILL.md file. The top of the file is YAML frontmatter with a name and description; below it go the instructions, in Markdown. The folder can also hold reference files Claude reads when it needs them and scripts it runs, where only the output enters the conversation ([Anthropic](https://code.claude.com/docs/en/skills)).

Anthropic calls this progressive disclosure. The description is always in context, so write it to say when to use the skill; the body loads when the skill is triggered, and stays loaded for the rest of the session.

## How do you write a Claude Code skill?

Create `.claude/skills/summarize-changes/SKILL.md` in your project:

```
---
name: summarize-changes
description: Summarizes uncommitted changes and flags risks. Use when asked what changed or for a commit message.
---
Summarize the diff in two or three bullets, then list any risks.
```

Then ask "what changed?", or type `/summarize-changes`.

- **name:** lowercase letters, numbers and hyphens, up to 64 characters, matching the folder name.
- **description:** what it does and when to use it, up to 1,024 characters in the open standard. Put the main use case first; Claude Code truncates long ones in its list.
- **Useful optional fields:** `allowed-tools` pre-approves tools while the skill runs, `disable-model-invocation: true` makes it run only when you type it, `argument-hint` shows what to pass, and `context: fork` runs it in a subagent.

Anthropic's advice: keep the body under 500 lines, move detail into reference files one level deep, and write the description in the third person ([Anthropic](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)). Its own **skill-creator** skill writes and tests skills for you.

## Where do Claude Code skills live?

- **Personal:** `~/.claude/skills/<name>/SKILL.md`, in every project.
- **Project:** `.claude/skills/<name>/SKILL.md`, committed to git so everyone on the repository gets it.
- **Plugin:** inside an installed plugin, run as `/plugin-name:skill-name`.
- **Enterprise:** in the managed-settings directory, set by an administrator.

When two have the same name, enterprise beats personal and personal beats project. Skills enabled on your claude.ai account sync into Claude Code terminal sessions from v2.1.275 (September 2026).

## Where can you find Claude Code skills?

- **Anthropic's skills repository** ([GitHub](https://github.com/anthropics/skills)), about 180,000 stars: frontend-design, mcp-builder, skill-creator, webapp-testing, the docx, pdf, pptx and xlsx document skills, and more. Most are Apache 2.0; the four document skills are source-available, not open source. Install with `/plugin marketplace add anthropics/skills`.
- **The official plugin marketplace,** `claude-plugins-official`, which Claude Code adds on first launch. Type `/plugin` and open the Discover tab, or browse it on the web with install counts and "Anthropic verified" badges ([Anthropic](https://code.claude.com/docs/en/plugins/anthropic-marketplaces)).
- **Vendors' own collections,** such as Vercel's agent-skills and Hugging Face's skills.

Anthropic's warning: "Use Skills only from trusted sources." Read every file before you install a skill, look for network calls, and remember that Anthropic doesn't review third-party marketplaces and auto-update can change a plugin after you've read it ([Anthropic](https://code.claude.com/docs/en/plugins/security)).

## Skills vs subagents, hooks, MCP and CLAUDE.md

From Anthropic's features overview ([Anthropic](https://code.claude.com/docs/en/features-overview)):

- **CLAUDE.md:** instructions loaded in every conversation. "Always do X" rules go here ([CLAUDE.md vs AGENTS.md](/claude-md-vs-agents-md)).
- **Skill:** instructions or a workflow loaded on demand.
- **Subagent:** a separate context that does a task and returns a summary ([Claude Code subagents](/claude-code-subagents)).
- **Hook:** a command that always runs on an event, such as before a tool call. Use hooks for rules that must be enforced ([Claude Code hooks](/claude-code-hooks)).
- **MCP:** connects Claude to an outside service; a skill can teach Claude how to use those tools ([Claude Code MCP](/claude-code-mcp)).
- **Plugin:** a package of skills, subagents, hooks and MCP servers ([Claude Code plugins](/claude-code-plugins)).

## Do skills work in Codex, Cursor and Copilot?

Yes. Anthropic released Agent Skills as an open standard in December 2025 ([agentskills.io](https://agentskills.io)).

- **Codex** reads skills from `.agents/skills`; run one with `$skill-name` or `/skills` ([OpenAI](https://learn.chatgpt.com/docs/build-skills)).
- **Cursor** reads `.cursor/skills` and `.agents/skills`, and also loads `.claude/skills` ([Cursor](https://cursor.com/docs/skills)).
- **GitHub Copilot** reads `.github/skills`, `.claude/skills` and `.agents/skills` ([GitHub](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)).
- **Claude Code** doesn't list `.agents/skills`; its `/import` command copies Codex, Gemini or Cursor skills over once.
- **The Claude app** has skills on every plan, Free included, with code execution turned on ([Anthropic](https://support.claude.com/en/articles/12512180-using-skills-in-claude)).

## How do you share skills with a team?

1. **Commit `.claude/skills/`** to the repository. Cloud sessions load them too.
2. **Run a plugin marketplace** and list it in the repository's `.claude/settings.json` so teammates are offered it.
3. **On Team and Enterprise,** owners can provision skills to everyone in the organization, and members can share or publish their own; provisioned skills sync into Claude Code.

A shared skill still runs in each person's own session. In Poly (usepoly.co), a team works with one Claude Code or Codex agent in a shared browser room, using the repository's skills and CLAUDE.md, and any member can approve a change before it happens. Free to start. [What is Poly?](/what-is-poly)

## Common questions

**What are skills in Claude Code?**

Folders with a SKILL.md file of instructions, plus optional scripts and reference files. Claude reads each skill's short description every session and loads the rest only when a task matches, or when you type /skill-name.

**Where do I put Claude Code skills?**

In ~/.claude/skills/<name>/SKILL.md for skills you want in every project, or .claude/skills/<name>/SKILL.md in a repository to share them through git. Plugins can also install skills.

**Is there a marketplace for Claude Code skills?**

Yes. Claude Code adds Anthropic's official plugin marketplace on first launch; type /plugin and open Discover. Anthropic's skills repository on GitHub can also be added as a marketplace.

**What is the difference between skills and slash commands?**

Anthropic merged custom slash commands into skills. A file in .claude/commands and a skill in .claude/skills both create a slash command; skills add supporting files and can load automatically when relevant.

**Do Claude skills work in Codex or Cursor?**

Yes. Agent Skills is an open standard. Codex reads .agents/skills, Cursor reads .cursor/skills and .claude/skills, and GitHub Copilot reads .github/skills and .claude/skills.

More guides: https://usepoly.co/guides · Security: https://usepoly.co/security · Pricing: https://usepoly.co/pricing