---
type: analysis
slug: guide-claude-code-skills-and-plugins-how-to-write-your-own
title: "Claude Code skills and plugins: how to write your own"
description: "Claude Code skills are folders with a SKILL.md (YAML frontmatter + Markdown instructions) that Claude loads on demand when a task matches the description, or that you invoke as /skill-name. Custom commands in .claude/commands/ still work but are merged into the skills model. Skills live under person"
published_at: 2026-11-11T09:00:00.000Z
topics: ["tools","developer_tools"]
source_urls: ["https://code.claude.com/docs/en/skills","https://code.claude.com/docs/en/plugins/overview","https://code.claude.com/docs/en/plugins/create","https://code.claude.com/docs/en/mcp","https://code.claude.com/docs/en/hooks","https://code.claude.com/docs/en/sub-agents","https://code.claude.com/docs/en/plugins/anthropic-marketplaces","https://code.claude.com/docs/en/plugins/install","https://claude.com/pricing?mode=code","https://code.claude.com/docs/en/whats-new/2026-w37","https://code.claude.com/docs/en/whats-new/2026-w36","https://code.claude.com/docs/en/whats-new","https://github.com/anthropics/claude-code/issues/46952"]
author: "Andrey Reshetnikov"
author_profile: https://newruntime.com/owner-profile.md
---
Claude Code skills are folders with a SKILL.md (YAML frontmatter + Markdown instructions) that Claude loads on demand when a task matches the description, or that you invoke as /skill-name. Custom commands in .claude/commands/ still work but are merged into the skills model. Skills live under personal (~/.claude/skills/), project (.claude/skills/), enterprise/managed, nested dirs, --add-dir, plugins, or claude.ai sync. A plugin is a directory with .claude-plugin/plugin.json that can bundle skills/, agents/, hooks/hooks.json, and .mcp.json; install from marketplaces such as claude-plugins-official (auto-added) or claude-community (add anthropics/claude-plugins-community). Author with claude plugin validate and test via --plugin-dir, /reload-plugins, skill-creator, or claude plugin eval. Skills/plugins share plan usage; they are not a separate product SKU.

*Field guide compiled 2026-11-06 from the official documentation, pricing pages and changelogs linked below; every line links to the page that states it.*

## What it does

- **Skills (SKILL.md).** A skill is a directory whose required file is SKILL.md: YAML frontmatter between --- markers, then Markdown instructions. Claude uses skills when relevant, or you invoke one with /skill-name. Unlike CLAUDE.md, the skill body loads only when used. How: mkdir -p ~/.claude/skills/name then write SKILL.md; invoke with /name or let Claude match the description. [source](https://code.claude.com/docs/en/skills)
- **Skill frontmatter.** Frontmatter configures name, description (recommended; used for auto-invocation), whentouse, disable-model-invocation, user-invocable, allowed-tools, context: fork, paths, hooks, and more. Claude Code ignores unrecognized fields without error. Combined description+whentouse listing text is truncated at 1,536 characters. How: Put fields at the top of SKILL.md between --- markers. Set disable-model-invocation: true for manual-only workflows such as deploy. [source](https://code.claude.com/docs/en/skills)
- **On-demand skill loading.** Skill descriptions stay in context so Claude knows what is available; full skill content loads only when invoked. Supporting files (references, scripts) stay out of context until Claude opens them. Keep SKILL.md under 500 lines. How: Reference supporting files from SKILL.md so Claude loads them only when needed; use !command for dynamic context injection before the skill body is sent. [source](https://code.claude.com/docs/en/skills)
- **Skill locations (personal, project, plugin).** Personal skills at ~/.claude/skills/name/SKILL.md load in all local projects on the machine (not Cowork/cloud). Project skills at .claude/skills/ load for that repo. Plugin skills load as /plugin-name:skill-name wherever the plugin is enabled. Other locations: enterprise managed, nested monorepo paths, --add-dir, and claude.ai account sync. How: Choose the path from the location table on the skills docs; commit project skills; distribute team packs as plugins. [source](https://code.claude.com/docs/en/skills)
- **Custom commands merged into skills.** A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Existing .claude/commands/ files keep working. Skills add a directory for supporting files, frontmatter for who can invoke them, and automatic loading when relevant. How: Prefer skills/ for new work; keep .claude/commands/ for legacy flat Markdown commands. [source](https://code.claude.com/docs/en/skills)
- **Plugins.** A Claude Code plugin is a directory of skills, agents, hooks, MCP servers, or other components that Claude Code installs and loads as one unit, usually with a manifest at .claude-plugin/plugin.json. How: Create .claude-plugin/plugin.json (name required), add skills under skills/name/SKILL.md, then claude --plugin-dir ./my-plugin or install from a marketplace. [source](https://code.claude.com/docs/en/plugins/overview)
- **Plugin components (skills, agents, hooks, MCP).** Under the plugin root: skills/ (SKILL.md per skill), commands/ (older flat commands; use skills/ for new plugins), agents/ (subagent Markdown), hooks/hooks.json, and .mcp.json (or mcpServers inline in plugin.json). Only plugin.json goes inside .claude-plugin/; components saved there do not load. How: Layout documented in Create a Claude Code plugin; validate with claude plugin validate ./my-plugin. [source](https://code.claude.com/docs/en/plugins/create)
- **Plugin-provided MCP servers.** Plugins define MCP servers in .mcp.json at the plugin root or inline in plugin.json. Enabling the plugin starts those servers automatically. Add/remove them by installing/uninstalling the plugin (toggle off in /mcp without uninstalling). Tool names are scoped as mcppluginpluginservertool. How: Use ${CLAUDEPLUGINROOT} in command/args/env; manage connection status in /mcp. [source](https://code.claude.com/docs/en/mcp)
- **Hooks (including plugin hooks).** Hooks are shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that run at lifecycle points (PreToolUse, PostToolUse, Stop, etc.). Plugin hooks live in hooks/hooks.json and merge when the plugin is enabled. Skills and subagents can also declare hooks in frontmatter. How: Configure in settings or plugin hooks/hooks.json; browse with /hooks; use ${CLAUDEPLUGINROOT} for bundled scripts. [source](https://code.claude.com/docs/en/hooks)
- **Subagents (including plugin agents).** Subagents are specialized assistants with their own context, system prompt, and tools. Custom ones are Markdown files with YAML frontmatter under .claude/agents/ or a plugin's agents/ directory. Plugin agents appear under scoped names such as my-plugin:reviewer. How: Ask Claude to create one, or add agents/name.md; invoke via natural language, @-mention, or Agent tool. Plugin agents ignore hooks/mcpServers/permissionMode frontmatter for security. [source](https://code.claude.com/docs/en/sub-agents)
- **Plugin marketplaces.** A marketplace is a catalog (.claude-plugin/marketplace.json) listing plugins and fetch sources. Official marketplace name claude-plugins-official (repo anthropics/claude-plugins-official) is auto-added on first interactive terminal session unless blocked. Community marketplace name is claude-community (repo anthropics/claude-plugins-community); add manually. How: /plugin marketplace add anthropics/claude-plugins-community then /plugin install name@claude-community; official: /plugin install commit-commands@claude-plugins-official. [source](https://code.claude.com/docs/en/plugins/anthropic-marketplaces)
- **Install and manage plugins.** Installing a plugin adds its skills, agents, hooks, and MCP servers. Scopes: user (~/.claude/settings.json), project (.claude/settings.json, committed), local (.claude/settings.local.json). Project enable does not download for collaborators—they must install once. Cloud sessions do not load local machine plugins. How: /plugin install plugin@marketplace, choose scope; shell: claude plugin install ...; apply with /reload-plugins when needed. [source](https://code.claude.com/docs/en/plugins/install)
- **Write and test your own skills/plugins.** Create SKILL.md, optionally scaffold a skills-directory plugin with claude plugin init, validate with claude plugin validate, load for one session with --plugin-dir or --plugin-url (.zip), reload with /reload-plugins. Evaluate with skill-creator@claude-plugins-official or claude plugin eval. How: claude plugin validate ./my-plugin; claude --plugin-dir ./my-plugin; /plugin install skill-creator@claude-plugins-official; claude plugin eval init [source](https://code.claude.com/docs/en/plugins/create)

## Modes

- **Personal skill.** Path ~/.claude/skills/name/SKILL.md. Loads in all your local projects on this machine, but not Cowork or cloud sessions. [source](https://code.claude.com/docs/en/skills)
- **Project skill.** Path .claude/skills/name/SKILL.md. Loads in sessions in this repository (not cloud threads in a project). Commit to share with the team. [source](https://code.claude.com/docs/en/skills)
- **Plugin skill.** Path plugin/skills/name/SKILL.md. Invoked as /plugin-name:skill-name wherever the plugin is enabled. [source](https://code.claude.com/docs/en/skills)
- **Plugin install scope: user / project / local.** User: every project on this machine via ~/.claude/settings.json. Project: committed .claude/settings.json for collaborators (they still install once). Local: .claude/settings.local.json for you in this repo only. Local overrides project overrides user. [source](https://code.claude.com/docs/en/plugins/install)

## Pricing and limits

- **Free:** $0. Limited usage every 5 hours and every week. Skills: Yes. Claude Code: No. [source](https://claude.com/pricing?mode=code)
- **Pro:** $17 per month with annual subscription discount ($200 billed up front); $20 if billed monthly. More usage than Free every 5 hours and every week (1x in compare table). Includes Claude Code and Skills. Claude Code shares the same usage pool as chat. [source](https://claude.com/pricing?mode=code)
- **Max:** $100. Everything in Pro plus 5x Pro usage every 5 hours and every week; Fable included up to half weekly limit; $100/month API credits. Claude Code and Skills included. [source](https://claude.com/pricing?mode=code)
- **Ultra:** $200. Everything in Max plus no 5-hour limit for verified accounts; 10x Pro usage every week; $200/month API credits. Claude Code and Skills included. [source](https://claude.com/pricing?mode=code)

## Recent changes

- 2026-09-07: Week 37 (2026-09-07–11): claude plugin eval runs plugin test cases with and without the plugin baseline; claude plugin eval init drafts cases and graders. --plugin-dir can point at a folder of plugins (subfolders with manifests). [source](https://code.claude.com/docs/en/whats-new/2026-w37)
- 2026-08-31: Week 36 (2026-08-31–09-04): /skill-doctor shows each skill's context cost and usage frequency (requires Claude Code v2.1.252+). [source](https://code.claude.com/docs/en/whats-new/2026-w36)
- 2026-05-25: Week 19 (May 25–29, 2026 digest index): plugins load from .zip via --plugin-dir and from URLs via --plugin-url for the current session. [source](https://code.claude.com/docs/en/whats-new)
- 2026-11-06: Docs state custom commands have been merged into skills; .claude/commands/ remains supported for compatibility. [source](https://code.claude.com/docs/en/skills)

## Alternatives

- **CLAUDE.md.** Always-loaded project/user guidance. Docs recommend moving long procedures out of CLAUDE.md into skills so the body loads only when used and costs almost nothing until needed. [source](https://code.claude.com/docs/en/skills)
- **Standalone skills / agents / hooks / MCP (no plugin).** Each works without a plugin for one project or personal use. Use a plugin when packaging several components for teammates, multi-project install, or versioned marketplace distribution. [source](https://code.claude.com/docs/en/plugins/overview)
- **.claude/commands/ custom commands.** Older flat Markdown command files; still work and share most frontmatter with skills except name and paths. Prefer skills for new work because of supporting files and auto-invocation controls. [source](https://code.claude.com/docs/en/skills)

## Traps

- Skill descriptions are always in context while full bodies load on invoke—so every listed skill costs tokens each turn. /skill-doctor reports unused skills and context cost (v2.1.252+). [source](https://code.claude.com/docs/en/skills)
- Malformed YAML frontmatter: Claude Code still loads the skill body with empty metadata, so /skill-name may work but auto-triggering fails. Check with claude --debug or claude plugin validate on the skills directory. [source](https://code.claude.com/docs/en/skills)
- Name collisions: personal overrides project for same-named skills; plugin skills are namespaced as /plugin:skill. Reserved folder name synced and names under anthropic-skills: are reserved for claude.ai sync. Do not name a skill folder synced. [source](https://code.claude.com/docs/en/skills)
- Only plugin.json belongs in .claude-plugin/. If skills/ is nested inside .claude-plugin/, the plugin loads but its skills are missing—move skills/ to the plugin root. [source](https://code.claude.com/docs/en/plugins/create)
- Project-scoped plugin enable in .claude/settings.json does not download the plugin for collaborators; each person must run claude plugin install @marketplace --scope project once. Cloud sessions do not load plugins from your machine or that settings file. [source](https://code.claude.com/docs/en/plugins/install)
- Plugin security: an enabled plugin's skill/agent names and descriptions are in context every turn; MCP servers run and hooks fire while enabled; what the plugin runs, it runs as you. Review the install pane (Will install / Context cost) before confirming. [source](https://code.claude.com/docs/en/plugins/overview)
- Community reports (GitHub #46952) argue skill auto-activation behaves more like keyword/token overlap on the description than deep semantic matching; authors should put literal user phrases in description. Official docs still say Claude uses the description to decide when to apply the skill. [source](https://github.com/anthropics/claude-code/issues/46952)
- Claude Code listing truncates combined description+whentouse at 1,536 characters—put the key use case and trigger words first. For side-effect skills (deploy, send message), set disable-model-invocation: true so Claude cannot run them on its own. [source](https://code.claude.com/docs/en/skills)

Author: [Andrey Reshetnikov](https://newruntime.com/owner-profile.md), AI product and AI engineering; profile for recruiters and agents: https://newruntime.com/owner-profile.json

## Continue in the graph

Next records for an agent, linked to their Markdown twins. Replace `.md` with `.json` for structured fields, including `next_reads`.

- topic hub: [Tools](https://newruntime.com/topics/tools.md): Explore the tools topic hub.
- topic hub: [Developer Tools](https://newruntime.com/topics/developer-tools.md): Explore the developer_tools topic hub.
- collection: [Analysis](https://newruntime.com/analysis.json): Open the latest authorial analysis.
- collection: [Sources](https://newruntime.com/sources/): See the original sources this archive cites.
- whole graph: [discovery graph](https://newruntime.com/discovery-graph.json) (typed nodes and edges) and [site index](https://newruntime.com/site-index.md)
