Skills and Plugins: How They Work Inside

Section 15 covered the basic idea of a skill. Here is the full mechanism: when and how Claude loads a skill, the frontmatter fields, arguments, scripts, and what happens from installing a plugin to loading it in a session. (Details follow the Claude Code docs.)

17.1 Skill lifecycle — what happens in one request

That is why description is the most important field. Claude does not have the skill's body until it loads it — it decides only by looking at the description. If the description does not clearly say "when to use", the skill will never trigger (or will trigger in the wrong place).

17.2 Where skills live and which has higher priority

• If names are the same, priority: Enterprise > Personal > Project.
• A skill overrides a .claude/commands/ file and a bundled skill of the same name.
• Plugin skills are always namespaced (/plugin-name:skill-name), so they never clash with anything.

17.3 SKILL.md frontmatter — important fields

17.4 Who can run it — invocation control

17.5 Arguments and variables

---
name: fix-issue
description: Takes a GitHub issue number and fixes it
argument-hint: [issue-number]
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS according to our coding standards.
1. Read the details with `gh issue view $ARGUMENTS`
2. Fix it, run the tests, commit

17.6 Supporting files and scripts

release-notes/
├── SKILL.md              # required — main instructions (keep under 500 lines)
├── reference.md          # read when needed
├── template.md           # read when needed
└── scripts/
    └── collect_commits.py   # RUN, not read — only its output enters the context

• Mention these files in SKILL.md ("see template.md for the format") so Claude knows when to open them.
• The script's code does not enter the context, only its output — so keeping big logic in a script saves tokens and is deterministic.
• To run a script without a permission prompt use allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/collect_commits.py *).

17.7 A complete example skill

---
name: release-notes
description: Creates user-friendly release notes from Git commits. Use when the user
  asks for release notes, a changelog, or "what's new in this release".
argument-hint: [from-tag]
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/collect_commits.py *)
---

# Release Notes

1. Run `${CLAUDE_SKILL_DIR}/scripts/collect_commits.py $ARGUMENTS` — it returns the commits as JSON.
2. Split the commits into Features / Fixes / Breaking Changes.
3. Follow `template.md` for the format.
4. Remove technical jargon; write for end users.

17.8 Limits and behaviours to remember

17.9 How to write a good description

17.10 What a plugin is and when you need one

A plugin is a folder containing skills, agents (subagents), hooks, MCP servers (and a few other components), plus a manifest .claude-plugin/plugin.json. Claude Code installs and loads it as one unit.

17.11 From plugin install to session — 3 stages

17.12 What happens to each component when a plugin loads

17.13 Cost of an enabled plugin

• Context: every skill/agent's name + description stays in context on every turn (even if unused) — it costs tokens. The full body only when used.
• Processes: the plugin's MCP servers run with every session; hooks fire on their events.
• Permissions: whatever the plugin runs, it runs with your user privileges — review before installing.
• Not using it? Disable instead of uninstalling: /plugin or claude plugin disable <id>.

17.14 Your first plugin — end to end

mkdir -p my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/skills/hello

// my-first-plugin/.claude-plugin/plugin.json
{
  "name": "my-first-plugin",          // required; becomes the prefix of every skill/agent, no spaces
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",                 // optional; if set, users stay on this exact version
  "author": { "name": "Your Name" }
}

<!-- my-first-plugin/skills/hello/SKILL.md -->
---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

claude plugin validate ./my-first-plugin      # "✔ Validation passed"
claude --plugin-dir ./my-first-plugin         # load for this session only (not installed)
# in the session:
/my-first-plugin:hello
/reload-plugins                               # edited the files? reload

Shortcut: claude plugin init my-tool → creates a starter plugin in ~/.claude/skills/my-tool/ that auto-loads in every session (my-tool@skills-dir). To turn an existing .claude/ setup into a plugin, copy commands/, agents/, skills/ and put the hooks object from settings into hooks/hooks.json.

17.15 Creating and sharing a marketplace

// my-marketplace/.claude-plugin/marketplace.json
{
  "name": "my-marketplace",
  "description": "Plugins for my team",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "my-first-plugin",                  // keep it the same as the name in plugin.json
      "source": "./plugins/my-first-plugin",      // path relative to the marketplace root
      "description": "A greeting plugin to learn the basics"
    }
  ]
}

claude plugin validate ./my-marketplace
claude plugin marketplace add ./my-marketplace          # or GitHub: owner/repo
claude plugin install my-first-plugin@my-marketplace     # id = <entry-name>@<marketplace>
claude plugin list                                       # Status: ✔ enabled
claude plugin details my-first-plugin                    # component inventory

17.16 Install scopes and settings

// .claude/settings.json — enable the plugin for the team
{
  "enabledPlugins": {
    "my-first-plugin@my-marketplace": true
  }
}

Precedence (low → high): --add-dir → user → project → local → --settings flag → managed. The project enabled it but you do not want it? Set it to false in .claude/settings.local.json.

17.17 The plugin ID tells you where it came from

17.18 Versions, updates and paths

• If you pin a version in plugin.json, users stay on it until you change the version string. If you do not, the git commit SHA becomes the version (every commit = an update).
• Auto-update: on by default for official marketplaces, off for others. After an update, /reload-plugins or restart.
• ${CLAUDE_PLUGIN_ROOT} = the plugin's installed version folder (changes with every version) — use it for script paths in hooks/MCP config.
• ${CLAUDE_PLUGIN_DATA} = a persistent data folder that survives updates — keep cache and config here.
• A plugin cannot load components from a path outside its own folder (../shared).

17.19 Debug checklist

1. claude plugin validate <path> — checks the manifest and every skill/agent frontmatter.
2. In the session /reload-plugins — applies edits; then run /plugin-name:skill and see.
3. /plugin → Installed tab (components list) and Errors tab (what did not load and why).
4. MCP server: status in /mcp. Hook: trigger the event and read the debug log.
5. Plugin loaded but Claude's behaviour did not change? Compare with/without the plugin using claude plugin eval.