Anthropic just shipped plugins for Claude Cowork and Claude Code. 11 official plugins at launch, an open plugin format based on markdown files, and a marketplace system for distribution.
I built one over the weekend — an SEO content engine with 8 slash commands and 5 auto-loading skills. Here's everything I learned about the plugin system.
What Plugins Actually Are
A plugin is a folder. Inside: markdown files that tell Claude how to behave. No compiled code. No API keys. No Docker containers.
The folder structure:
| Directory | Purpose |
|---|---|
.claude-plugin/plugin.json | Identity: name, version, description |
commands/ | Slash commands users invoke manually |
skills/ | Knowledge that auto-loads based on context |
agents/ | Custom sub-agents with specific tool access |
hooks/ | Event triggers (run code after file edits, etc.) |
.mcp.json | External tool connections (APIs, databases) |
That's it. Five concepts. All file-based. All versionable with git.
Step 1: The Manifest
Every plugin starts with .claude-plugin/plugin.json:
{
"name": "my-plugin",
"description": "What it does in one sentence",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
The name field becomes your namespace. If you name it seo-tools, your commands become /seo-tools:draft, /seo-tools:keywords, etc. Pick a short, descriptive name.
Step 2: Commands (Slash Commands)
Create commands/hello.md:
---
description: Greet the user and explain what this plugin does
disable-model-invocation: true
---
# Hello
Greet the user warmly. Explain that this plugin provides
SEO tools for blog content. List available commands.
The filename becomes the command name. hello.md → /my-plugin:hello. The description field shows up in the command menu.
The $ARGUMENTS placeholder captures user input:
---
description: Generate SEO keywords for a topic
---
Generate keywords for: $ARGUMENTS
Now /my-plugin:keywords kubernetes vs docker passes the topic to Claude.
Step 3: Skills (Auto-Loading Knowledge)
Skills are the magic. They're context that Claude loads automatically — no slash command needed. Put them in skills/topic-name/SKILL.md:
---
name: writing-rules
description: Writing quality rules. Auto-loads when drafting content.
---
# Writing Rules
- Max 3 sentences per paragraph
- Numbers over adjectives ("15 tokens/sec" not "very fast")
- Active voice, direct address ("you" not "the user")
- Every article needs a verdict section
When Claude detects you're writing content, it pulls in these rules automatically. You don't invoke skills — they invoke themselves.
Key difference: Commands are explicit (/do-this). Skills are implicit (Claude decides when they're relevant).
Step 4: Agents (Optional)
Custom agents get specific tool access. Create agents/researcher.md:
---
name: researcher
description: Research agent with web access only
tools:
- WebSearch
- WebFetch
- Read
---
You are a research agent. Search the web for current information
about the given topic. Return facts, not opinions.
This creates a sub-agent that can only search and read — no file editing, no code execution. Useful for separating concerns.
Step 5: Hooks (Event Automation)
Hooks run shell commands when Claude does something. Create hooks/hooks.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "echo 'File modified' >> plugin.log"
}]
}
]
}
}
This logs every file write. You could lint code, run tests, send notifications — any shell command.
The Complete Structure
Here's what a real plugin looks like:
seo-blog-engine/
├── .claude-plugin/
│ ├── plugin.json # Identity
│ └── marketplace.json # Distribution catalog
├── commands/
│ ├── draft.md # /seo-blog:draft
│ ├── keywords.md # /seo-blog:keywords
│ ├── titles.md # /seo-blog:titles
│ └── setup.md # /seo-blog:setup
├── skills/
│ ├── seo-fundamentals/
│ │ └── SKILL.md # Auto-loads for keyword work
│ ├── writing-engine/
│ │ ├── SKILL.md # Auto-loads for writing
│ │ ├── good-examples.md # Reference material
│ │ └── bad-examples.md # Anti-patterns
│ └── voice-defaults/
│ ├── SKILL.md # Tone rules
│ └── forbidden-phrases.md
└── README.md
Weekly insights on AI Architecture. No spam.
8 commands, 5 skills, zero compiled code. The full source is on GitHub.
Distribution: Three Paths
Path 1: Upload to Cowork (Easiest)
- ZIP your plugin folder
- Open Claude Desktop → Cowork tab
- Click Plugins → Upload Plugin
- Select the ZIP
Done. Your commands appear immediately.
Path 2: GitHub Marketplace (Share with Everyone)
Add a marketplace.json to your .claude-plugin/ folder:
{
"name": "seo-blog-engine",
"owner": { "name": "Your Name" },
"plugins": [{
"name": "seo-blog-engine",
"source": ".",
"description": "SEO content engine"
}]
}
Push to GitHub. Anyone installs with:
/plugin marketplace add your-username/repo-name
/plugin install plugin-name@marketplace-name
Path 3: Official Anthropic Directory
Submit at clau.de/plugin-directory-submission. Anthropic reviews for quality and security, then lists it in their official plugin directory.
This gets you the verified badge and maximum visibility.
What Makes a Good Plugin
After building one and studying the official plugins, here's what works:
Do one thing well. The best plugins are focused. "SEO content engine" beats "everything content tool." Users install specific solutions, not Swiss Army knives.
Skills over commands. Commands require the user to remember syntax. Skills auto-load when relevant. A good plugin is 80% skills, 20% commands.
Include examples. Skills with good-examples.md and bad-examples.md files produce dramatically better output than abstract rules alone.
Ship a setup command. If your plugin needs configuration (blog niche, voice, language), build a /setup command that asks questions conversationally. First impressions matter.
What I Built
The SEO Blog Engine generates complete article packages from any topic:
/seo-blog:draft "topic"→ Full article with keywords, FAQ schema, social copy/seo-blog:keywords "topic"→ SEO keyword predictions/seo-blog:faq "topic"→ FAQ with JSON-LD schema markup/seo-blog:optimize→ Audit and improve existing articles
I use a version of this system to write every article on this blog. The plugin is the open-source, portable version — install it, configure it for your niche, start writing.
The Verdict
Claude's plugin system is markdown files in folders. That's the entire architecture. No SDK, no build step, no API keys.
If you can write a markdown file, you can build a plugin. If you can push to GitHub, you can distribute it.
The system is new — Cowork plugins launched as a research preview. The marketplace is sparse. If you build something useful now, you're first. That's the same first-mover playbook that works for SEO content — except now it's plugin distribution.
Start with a single command that solves a real problem. Ship it. Iterate.