What is a Claude plugin and how is it different from a skill or an MCP?
A Claude plugin is a self-contained workflow package — typically a .plugin directory with a manifest, one or more skill files, prompt templates, and optional resource files — that bundles a multi-step process Claude Code can install, version, and re-run. A skill is one instruction. A plugin is an entire workflow. An MCP is a tool the workflow uses. I’ve shipped 6 plugins in the last 4 months. The most-used is a custom one that builds a 17-section ICP Bible end-to-end (sources verbatims from forums, drafts each section, validates with Hormozi GOOD scoring, exports to PDF). It compresses what used to be 30-50 hours of manual work into ~12 hours. This article is the format, the boundary between skills/plugins/MCPs, and the build process for your first plugin.
When should you build a plugin vs. a skill vs. an MCP?
Three layers of abstraction. Pick the one that matches the work.
| Layer | What it is | When to use | Example |
|---|---|---|---|
| Skill | A single instruction (3-100 lines of plain English in SKILL.md) | One discrete task you re-run daily | The 3-line email auto-responder |
| Plugin | A workflow with multiple steps, optional sub-skills, prompt templates, resource files | A multi-stage process with branches and outputs | An ICP Bible builder, a content factory pipeline, an SEO audit suite |
| MCP | A tool server (separate process) that exposes specific functions | When you need to call an external API or service | Gmail MCP, Notion MCP, Stripe MCP, Bright Data MCP |
The decision rule: can you describe the task in 3 sentences without losing fidelity? If yes, it’s a skill. If you need branches (“if X then Y else Z”), step ordering, or persistent state, it’s a plugin. If you need to call a service, it’s an MCP — and you’ll likely use the MCP inside a skill or plugin.
“The mistake everyone makes is reaching for a plugin when a skill would do, or building an MCP when a plugin would do. Always start one layer below where you think you need to be. Half the time, you’ll never need to upgrade.” — Build heuristic I use on every new automation
What does the .plugin format look like?
The minimum viable plugin is one directory with one file. The full-featured plugin is one directory with 5-10 files. Let me show both.
The minimum viable plugin
my-first.plugin/
└── plugin.yamlplugin.yaml:
name: my-first
version: 0.1.0
description: A minimal plugin that does one thing
author: maxime
entry: |
Read the file the user provides.
Summarize it in 5 bullet points.
Save the summary to ./summary.md.That’s it. Drop the directory in ~/.claude/plugins/, and claude --plugin my-first /path/to/file.txt runs it. For most simple workflows you don’t need anything more.
The full-featured plugin
When the workflow has branches, multiple stages, prompt templates, and reference data:
icp-bible-builder.plugin/
├── plugin.yaml # Manifest
├── README.md # Human-readable docs
├── skills/
│ ├── interview-mining.md # Sub-skill: extract verbatims from interview transcripts
│ ├── forum-mining.md # Sub-skill: extract verbatims from forum threads
│ └── hormozi-score.md # Sub-skill: compute the /30 GOOD score
├── prompts/
│ ├── section-3-psychographics.md # Prompt template for the 7-dim section
│ ├── section-11-before-after.md # Prompt template for the transformation map
│ └── section-13-objections.md # Prompt template for the objection encyclopedia
├── resources/
│ ├── hormozi-rubric.md # The /10 scales for Pain, Buying Power, Easy-to-Find
│ └── voice-guide.md # Tone guide for the output
└── outputs/ # Plugin writes its outputs here
└── .gitkeepplugin.yaml for the full version:
name: icp-bible-builder
version: 2.0.0
description: Build a 17-section ICP Bible from interviews + forum mining
author: maxime
inputs:
- name: niche
description: The niche you're researching (e.g., "French freelance digital-marketing consultants")
required: true
- name: interview_transcripts_dir
description: Directory containing 5-10 interview transcripts (.md files)
required: false
- name: forum_urls
description: 3-5 forum or Reddit URLs to mine for verbatims
required: false
stages:
- name: gather_verbatims
skills:
- interview-mining
- forum-mining
output: outputs/verbatims.md
- name: draft_sections_1_to_5
prompts:
- section-1-identity
- section-2-demographics
- section-3-psychographics
- section-4-pains
- section-5-desires
output: outputs/sections-1-5.md
- name: draft_sections_6_to_11
prompts:
- section-6-journey
- section-7-comms
- section-8-day-in-life
- section-9-targeting
- section-10-jtbd
- section-11-before-after
output: outputs/sections-6-11.md
- name: validate
skills:
- hormozi-score
output: outputs/score.md
- name: assemble
output: outputs/icp-bible.mdThe plugin runs claude --plugin icp-bible-builder --niche "..." --interview_transcripts_dir ./interviews/. Each stage runs in order. State is passed file-to-file via the outputs/ directory.
What goes inside a sub-skill file?
A sub-skill is just a regular SKILL.md scoped to the plugin. Example: skills/forum-mining.md:
---
name: forum-mining
description: Extract verbatim quotes from forum threads
---
For each forum URL provided:
1. Fetch the thread (via the bright-data MCP if available, otherwise web fetch)
2. Read all comments
3. Extract any quote that matches one of the 7 psychographic patterns:
- Identity statements ("I'm a...")
- Value rankings
- Belief statements ("I think... is true")
- Fear verbatims ("I'm scared that..." / "What if...")
- Aspiration verbatims ("I want to...")
- Self-talk ("I keep telling myself...")
- Status statements ("I don't want to be like..." / "I look up to...")
4. Save to outputs/verbatims.md with format:
- Quote (verbatim)
- Source URL
- Pattern type (one of the 7 above)
- Date postedThat’s a sub-skill. Plain English. The plugin runner invokes it during the gather_verbatims stage.
What goes inside a prompt template?
Prompt templates are the part of a plugin that’s not a free-form skill — they’re a reusable, parameterized prompt for a specific output. Example: prompts/section-3-psychographics.md:
You are drafting Section 3 — Psychographics (7 dimensions) — for an ICP Bible.
INPUTS:
- Niche: {{ niche }}
- Verbatims: read outputs/verbatims.md (filter to pattern types matching each dimension)
OUTPUT FORMAT:
For each of the 7 dimensions, write:
- Header (the dimension name)
- One-paragraph description (3-5 sentences)
- 3-5 bullet verbatims directly quoted from outputs/verbatims.md
- A "Hook seed" — one ad opener that uses the dimension
DIMENSIONS, in order:
1. Core Identity
2. Values (ranked)
3. Beliefs
4. Fears (with intensity 1-10)
5. Aspirations (with intensity 1-10)
6. Self-Talk
7. Status & Belonging
CONSTRAINTS:
- No invented verbatims. Every quote must trace to a line in outputs/verbatims.md.
- Voice: direct, founder-to-founder. No "leverage" or "unlock."
- Each section ends with the Hook seed.The plugin runner substitutes {{ niche }} from the CLI input, reads the file path, and runs the prompt against Claude.
How to actually build your first plugin (90 minutes)
A 90-minute build path for someone who’s already shipped a Claude skill:
| Step | Time | What you do |
|---|---|---|
| 1. Pick the workflow | 10 min | Choose a workflow you re-run weekly. Must have ≥3 distinct stages. |
| 2. Sketch the stages | 15 min | Draw the stages on paper. Inputs → outputs of each stage. State passed via files in outputs/. |
| 3. Create the directory | 5 min | mkdir my-plugin.plugin && touch plugin.yaml README.md |
4. Write plugin.yaml | 15 min | Manifest, inputs, stages, outputs |
| 5. Write the first stage | 20 min | One SKILL.md or one prompt template |
| 6. Test the first stage | 10 min | claude --plugin my-plugin --stage 1 — does it produce the expected output? |
| 7. Add the second stage | 15 min | Same pattern. Test. |
After 90 minutes you have a plugin with 2 working stages. Each subsequent stage is 15-25 minutes. A 5-stage plugin like the ICP Bible builder is a 4-6 hour build for v1, plus another 4-6 hours of iteration once you run it on real inputs.
Why bother with a plugin instead of just a longer skill?
Three reasons that justify the upgrade:
- Versioning. A plugin has a version number. You can pin v1.2 in production while you experiment with v2.0 in a branch. A skill is just a file; you can’t safely iterate.
- Composability. Sub-skills can be re-used by other plugins. The
forum-miningskill works for the ICP Bible plugin AND for a separate “competitor analysis” plugin. Without the plugin layer, you’d duplicate it. - Stage isolation. If stage 3 fails, the plugin runner re-runs only stage 3 (the inputs are in
outputs/sections-1-5.mdfrom the prior run). With a single long skill, a failure in step 7 means re-running steps 1-6 from scratch.
The break-even point in my experience: if a workflow has ≥3 distinct stages AND you re-run it ≥monthly, build a plugin. Below that, a skill is fine.
A complete worked example: the ICP Bible builder
The plugin I use most. Used to build the worked example in the 17-section ICP Bible article.
Inputs
- Niche definition (one paragraph)
- 5-10 interview transcripts in
./interviews/ - 3-5 forum URLs
Stages
- Gather verbatims — runs
forum-miningandinterview-miningsub-skills. Output:outputs/verbatims.mdwith 200-400 quotes. - Draft sections 1-5 — Identity, Demographics, Psychographics, Pains, Desires. Output:
outputs/sections-1-5.md. - Draft sections 6-11 — Journey, Comms, Day-in-life, Targeting, JTBD, Before/After. Output:
outputs/sections-6-11.md. - Draft sections 12-17 — Validation, Objections, Influencer Map, Triggers, Fit Scoring, Update Protocol. Output:
outputs/sections-12-17.md. - Validate — runs the
hormozi-scoresub-skill. Computes Pain × Buying Power × Easy-to-Find /30. Output:outputs/score.md. - Assemble — concatenates all sections + score into a single
outputs/icp-bible.md.
Output
- A 25-35 page Markdown file ready to convert to PDF.
- A
score.mdsaying e.g. “Pain 8 / Buying Power 6 / Easy to Find 9 = 23/30 GOOD.”
Time
- v1 (manual): 30-50 hours
- With this plugin: 10-14 hours (mostly the 5-10 customer interviews, which the plugin can’t do for you)
The plugin doesn’t replace the human work that has to be human (interviews, judgement calls). It compresses everything else.
What you should NOT do with a plugin
Honest limits:
- Don’t put secrets in the plugin. API keys, OAuth tokens, customer PII — those go in environment variables or in MCP servers, never in the plugin manifest.
- Don’t make the plugin too rigid. If every stage demands a specific prompt template, you’ve built a script, not a plugin. Leave room for Claude to use judgement.
- Don’t re-implement an MCP. If the plugin needs Gmail data, use the Gmail MCP. Don’t write web-scraping logic inside the plugin.
- Don’t ship a v1 with 10 stages. Start with 2-3. Add stages as you discover real friction. Most plugins I’ve shipped settled at 4-6 stages after iteration.
Frequently asked questions
Where do I get the official .plugin format spec?
Anthropic publishes the format reference in the Claude Code docs. As of writing, the format is still evolving — pin a specific Claude Code version when you ship a plugin to a teammate. The shape I’ve shown above is what works in Claude Code Max as of 2026-05.
Can I share my plugins publicly?
Yes — there’s a growing community plugin index. Format-wise, anything in a .plugin directory is a single shareable unit. Sanitize secrets and inputs before publishing.
Can plugins call each other? Not directly in v1. The pattern that works: plugin A writes its output to a known file path; plugin B reads from that path. Not elegant, works.
How do plugins compare to LangChain agents or CrewAI crews? LangChain and CrewAI are Python-side orchestration frameworks; plugins are Claude-Code-native and require zero Python. If your team is already on LangChain, stay there. If you’re a solo founder running everything inside Claude Code, plugins are the simpler path.
What’s the upgrade path from a skill to a plugin?
Take your SKILL.md, paste it into a plugin.yaml entry: field, save in a .plugin directory. You now have a 1-stage plugin. Add stages from there.
How do I test a plugin without burning Claude Code Max quota?
Run individual stages: claude --plugin my-plugin --stage 1 --dry-run. The --dry-run flag (where supported) shows the prompt that would be sent without actually calling the model. Saves quota during iteration.
Should I write the plugin in Markdown or YAML or JSON? Plugin manifest: YAML (more readable). Sub-skills: Markdown. Prompt templates: Markdown. Resource files: whatever fits the data (Markdown for prose, YAML for structured config, CSV for data tables).
Where to start tomorrow
Three steps:
- Take a workflow you ran 3+ times last month manually. Sketch the stages on paper.
- Create a
.plugindirectory with a 1-stageplugin.yaml. Run it. - Add a second stage tomorrow. By Friday, you have a working 3-stage plugin saving you 1-2 hours a week.
For a simpler starting point — a 3-line skill that runs your morning inbox — see the email auto-responder skill. For the broader stack of plugins, skills, and MCPs I run daily, see the $500K AI Stack.