AnalysisNov 11, 20268 min read13 sources

Claude Code skills and plugins: how to write your own

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

In one minute

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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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

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
  • 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
  • Plugin skill. Path plugin/skills/name/SKILL.md. Invoked as /plugin-name:skill-name wherever the plugin is enabled. source
  • 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

Pricing and limits

  • Free: $0. Limited usage every 5 hours and every week. Skills: Yes. Claude Code: No. source
  • 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
  • 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
  • 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

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
  • 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
  • 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
  • 2026-11-06: Docs state custom commands have been merged into skills; .claude/commands/ remains supported for compatibility. source

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
  • 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
  • .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

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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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

Evidence / sources

  1. 1code.claude.com/docs/en/skills
  2. 2code.claude.com/docs/en/plugins/overview
  3. 3code.claude.com/docs/en/plugins/create
  4. 4code.claude.com/docs/en/mcp
  5. 5code.claude.com/docs/en/hooks
  6. 6code.claude.com/docs/en/sub-agents
  7. 7code.claude.com/docs/en/plugins/anthropic-marketplaces
  8. 8code.claude.com/docs/en/plugins/install
  9. 9claude.com/pricing?mode=code
  10. 10code.claude.com/docs/en/whats-new/2026-w37
  11. 11code.claude.com/docs/en/whats-new/2026-w36
  12. 12code.claude.com/docs/en/whats-new
  13. 13github.com/anthropics/claude-code/issues/46952
All Analysis

Next reads

Read next

Open the graph
  1. 01topicToolsExplore the tools topic hub.
  2. 02topicDeveloper ToolsExplore the developer_tools topic hub.
  3. 03archiveAnalysisOpen the latest authorial analysis.
  4. 04sourcesSourcesSee the original sources this archive cites.
Who read this page?Machine requests, hidden until opened

Loading the privacy-safe route aggregate...

Open the JSON contract