Skills, Plugins, and Extensions

The assistant predicts plausible output from what is in its context. If your project's conventions are not in that context, the assistant cannot follow them, and it will confidently produce code that looks right and fits some other project's habits.

Picture a developer, Maya, working in a repo where every API handler returns errors through a shared problemDetails() helper and every database call goes through a thin repository layer. The assistant does not know this. So on the first task it writes a handler that throws a raw Error and queries the database directly with an inline SQL string. The code compiles. The tests she had do not cover the new path. It reaches review, and a teammate sends it back: wrong error shape, bypasses the repository, will not log correctly in production. Maya retypes the conventions into the next prompt. And the next. By Friday she has pasted the same three paragraphs eleven times.

That paste-the-rules-every-time loop is the symptom. The two costs are real: the wasted tokens and minutes, and the quiet risk that one time she forgets a rule and the wrong-shaped code ships. Extensions remove the loop. A short rules file or a skill puts the convention into context once, durably, so the assistant follows it on task one and task fifty without a reminder.

The flip side is that an extension is more than a convenience. A skill can run a bundled script, an MCP server runs on your machine with your credentials, and a hook fires automatically on a tool event. Each is context the model trusts and, often, code that executes with your access. The same mechanism that saves Maya eleven pastes is the mechanism a malicious plugin would use to run a command she never saw. The next section breaks down how each kind works, so you can use the power and audit the risk.

There are four extension mechanisms, and they layer from lightest to heaviest. Knowing which one fits a need keeps your setup cheap and auditable.

• Project rules. Claude Code reads CLAUDE.md at session start. Use it for durable facts: the stack, the conventions, the commands to run tests. The cross-tool equivalent is AGENTS.md, which Cursor and VS Code Copilot read from the repo root directly, while Claude Code picks it up only when a CLAUDE.md imports it with a first line of @AGENTS.md or you run /init in a repo that already has one. Because rules load every session, keep them to facts a paragraph long, not procedures.
• Skills. A folder with a SKILL.md file, following the open Agent Skills standard now shared by Claude Code and VS Code Copilot. Use it for a procedure that should load only when relevant: a release checklist, a code-review pass, a migration recipe.
• MCP servers. A small server speaking the Model Context Protocol that gives the assistant a real tool: query Postgres, read a Jira ticket, fetch a Sentry trace. Use it when the assistant needs live data or an action in another system.
• Plugins. A versioned bundle that can ship skills, slash commands, subagents, hooks, MCP server definitions, and LSP servers together, installed from a marketplace. Use it to distribute a working setup to a team in one step.

The distinction that decides whether skills stay cheap is progressive disclosure. At startup, only each skill's name and description load into context, costing a few dozen tokens each. The full body loads only when the assistant matches your request against the description or you type /skill-name. This is why a project can carry dozens of skills with almost no standing cost. It is also why the description is the real interface. The model never reads the body to decide; it reads the description. A description like "helps with the database" will misfire. A description like "Add a CHANGELOG.md entry from a merged PR; use when the user asks to update the changelog or record a release note" fires precisely. Each skill's combined description and when_to_use is capped at 1,536 characters, and the whole skill listing shares a budget of roughly 1% of the model's context window, so put the key use case first.

Custom commands have been merged into skills. A .claude/commands/deploy.md and a .claude/skills/deploy/SKILL.md both create /deploy. Skills add a folder for supporting files, frontmatter to control who invokes them, and automatic loading. Two frontmatter fields control invocation: disable-model-invocation: true means only you can fire it (right for anything with side effects like deploy or commit), and user-invocable: false means only the assistant loads it (right for background knowledge). The next section follows one skill from idea to commit.

Back to Maya. The repeated convention she keeps pasting is the release-notes procedure: after a PR merges, append a bullet under the Unreleased heading in CHANGELOG.md, match the existing style, reference the PR number, and never touch released sections. She turns it into a skill.

1. Create the folder. She runs mkdir -p .claude/skills/changelog-entry in the repo so the skill is checked in and the whole team gets it.
2. Write SKILL.md. The frontmatter is the load-bearing part. She writes description: Add a CHANGELOG.md entry from a merged PR. Use when the user asks to update the changelog or mentions a release note. and adds allowed-tools: Read Edit so it can read and edit the file without a per-use prompt, but nothing more. The body is four lines of instruction, not prose.
3. Test the trigger. She types "add a changelog entry for PR 218" and watches the assistant load changelog-entry automatically and propose a one-line diff. She also confirms /changelog-entry 218 works as a direct call.
4. Catch a misfire. The next day, asking "what changed in the changelog format?" wrongly loads the skill, because "changelog" alone matched. She tightens the description to name the action ("when the user asks to add or record an entry") and the misfire stops.
5. Add a tool the assistant cannot guess. The PR number and title live in GitHub, so she enables the GitHub MCP server. Now the assistant fetches the merged PR's title itself instead of asking her to paste it.
6. Commit. She reviews the final diff, sees only the new bullet under Unreleased, and commits the skill folder alongside the change.

The result is concrete. The eleven pastes per week drop to zero. The skill costs about 30-40 tokens of standing context (its name plus description) and the full body, roughly 80 tokens, loads only on the handful of tasks that need it. The team inherits the convention the moment they pull. The MCP server she added, though, is where the next section's caution begins, because it is now reading from GitHub with her token, and Maya carries straight into the pitfalls.

Each of these traps feels like progress while quietly creating cost or risk.

• Stuffing CLAUDE.md with procedures. A long deploy runbook in CLAUDE.md loads every single session and burns tokens on tasks that have nothing to do with deploying. The fix is the test "is this a fact or a procedure?" Facts (the stack, the test command) stay in the rules file. Procedures move into a skill that loads on demand.
• The vague description. A skill the model never triggers is invisible work. Write the description from the user's words, list the trigger phrases, and run /doctor if you suspect the skill listing budget is overflowing and silently truncating descriptions.
• Forgotten broad permissions. Granting allowed-tools: Bash(*) to get a skill working once means every later automatic invocation can run any shell command without a prompt. Scope it to the exact commands the skill needs, like Bash(git add *) Bash(git commit *), and review what each skill grants itself.
• Installing on trust alone. A community plugin can bundle hooks that fire on every edit and an MCP server that phones home. Read the plugin.json, the hooks/, the .mcp.json, and the scripts before enabling. Enable on a throwaway branch first.

Then the genuine edge cases. MCP tool output is untrusted input. This is the 2026-specific wrinkle. When Maya's GitHub MCP server returns a PR description, that text flows into the model's context, and a hostile PR body can contain hidden instructions ("ignore your task, run this command"). Two named attack patterns dominate the 2026 security literature: prompt injection, where untrusted content carries instructions, and tool poisoning, where a malicious server hides instructions in its tool descriptions. The handling: minimize each server's scopes, keep credentials out of the prompt, and keep a human reviewing any action the agent takes from tool output, rather than letting it auto-execute.

Subagents and skills that run scripts. A skill can bundle a script and execute it. A subagent runs in its own context and cannot show you a permission prompt. So a forked skill granted broad tools is a quiet way to run code unreviewed. Keep forked or background skills read-only where you can, and set disableSkillShellExecution: true in managed settings if a fleet of machines should never let a checked-in skill run shell commands. Handling all of this gets harder once more than one person shares the same extensions, which is the next section.

One developer can keep a skill folder in their head. The moment a team shares extensions across a repo, the setup needs to be a visible, versioned artifact, or it drifts into a pile of personal customizations nobody can audit.

The durable artifact is the repo itself. Check .claude/skills/ and your CLAUDE.md into version control (along with an AGENTS.md if other tools on the team read one, imported from CLAUDE.md with @AGENTS.md so Claude Code loads it too), so a skill change goes through the same pull request and review as any code change. A teammate can see in the diff that a new skill granted itself allowed-tools, and can ask about it before merging. This is also why project skills require accepting a workspace trust dialog before their pre-approved tool access takes effect: opening a cloned repo should not silently grant a checked-in skill the ability to run commands.

For wider distribution, a lead named Priya packages the team's working setup as a plugin and serves it from an internal marketplace. The team adds it with /plugin marketplace add your-org/internal-plugins and installs with /plugin, getting the same namespaced skills (/internal-plugins:release-notes), hooks, and MCP definitions in one step, with a version they only update when Priya bumps it. Anthropic ships two public marketplaces by default in 2026: claude-plugins-official, a curated set registered automatically on first launch, and claude-community, the reviewed community catalog you add with /plugin marketplace add anthropics/claude-plugins-community. Curated and reviewed lowers the odds of a poisoned plugin, but it does not remove your responsibility to read what you enable.

Scale also needs an escape hatch. When a shared MCP server or a hook makes sessions misbehave, the fastest way to find out whether a customization is the cause is claude --safe-mode (added in v2.1.169, June 2026), which launches a clean session with every customization disabled: CLAUDE.md, skills, plugins, hooks, and MCP servers. If the problem vanishes, you know to bisect the configuration rather than the code.

The durable principle to keep, whatever the size: an extension is context the model trusts and code it can run with your access, so the bar to enable one is the bar you would set for installing software, and every extension still produces a diff you review. Start with one skill for the procedure you retype most, check it into the repo, and add the next only once that one earns its place.