Skip to main content

Skills, Plugins & Marketplaces Explained

There's a lot of confusion around skills, plugins, and marketplaces in Claude Code. This guide clears it up with a practical lens — including how SpecWeave uses all three at scale.

TL;DR

Skill = a markdown file with instructions for Claude. Plugin = a package of skills + agents + hooks. Marketplace = a catalog of plugins. Command = the old name for skills. Every skill can be invoked three ways: natural language, slash command (sw:name), or CLI keyword (name).

The 4 Concepts​

ConceptWhat It IsFileAnalogy
SkillA SKILL.md file with instructionsSKILL.mdAn app
PluginA directory bundling skills + agents + hooks + MCPplugin.jsonAn app bundle
MarketplaceA JSON catalog listing available pluginsmarketplace.jsonAn app store
CommandLegacy name for skills (.claude/commands/*.md)*.mdSame as skill

The hierarchy: Marketplace contains Plugins, each Plugin contains Skills.

Skills — The Building Block​

A skill is a SKILL.md file with instructions — Claude adds it to its toolkit, uses it automatically when relevant, or you invoke it directly with /skill-name. It's a detailed playbook written in markdown.

Where Skills Live​

Where you store a skill determines who can use it:

LocationPathScope
Personal~/.claude/skills/<name>/SKILL.mdAll your projects
Project.claude/skills/<name>/SKILL.mdThis repo only
Plugin<plugin>/skills/<name>/SKILL.mdWhere plugin is installed
EnterpriseManaged settingsEntire organization

Higher-priority locations win: Enterprise > Personal > Project. Plugin skills use namespacing (/plugin:skill), so they never conflict with other levels.

Anatomy of a SKILL.md​

Every skill has two parts: YAML frontmatter (configuration) and markdown body (instructions).

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash, Read
model: opus
context: fork
agent: Explore
argument-hint: "[environment]"
hooks:
  PostToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: echo "Deploy completed"
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Frontmatter Fields​

FieldWhat It Does
nameDisplay name, becomes the /slash-command
descriptionTells Claude when to auto-activate this skill
disable-model-invocationtrue = only YOU can invoke (Claude cannot auto-trigger)
user-invocablefalse = hidden from / menu (background knowledge only)
allowed-toolsRestrict which tools Claude can use
modelWhich model to use (opus, sonnet, haiku)
contextfork = runs in an isolated subagent
agentWhich agent type for the fork (Explore, Plan, etc.)
argument-hintAutocomplete hint shown in UI
hooksLifecycle hooks scoped to this skill

Three Invocation Methods​

Skills can be triggered three ways:

1. Natural language (easiest) — just describe what you want and Claude matches the right skill. 2. Slash command (precise) — type /skill-name in Claude Code. 3. CLI keyword (cross-tool) — type the skill name in Cursor, Copilot, and other AI tools.

"Let's design the authentication architecture"

Controlling Who Can Invoke​

FrontmatterYou Can InvokeClaude Can InvokeUse Case
(default)YesYesMost skills
disable-model-invocation: trueYesNoDangerous ops (deploy, commit)
user-invocable: falseNoYesBackground knowledge

Arguments and Dynamic Context​

Arguments — use $ARGUMENTS (or $0, $1 for positional):

---
name: fix-issue
description: Fix a GitHub issue
---

Fix GitHub issue $ARGUMENTS following our coding standards.

Running /fix-issue 123 sends "Fix GitHub issue 123..."

Dynamic context injection — Claude Code's built-in !`command` syntax runs shell commands before Claude sees the content:

---
name: pr-summary
description: Summarize a pull request
---

PR diff: !`gh pr diff`
Changed files: !`gh pr diff --name-only`

Summarize this pull request.

The shell output replaces the placeholder. Claude only sees the final rendered prompt.

Supporting Files​

Skills can include a directory of files, not just SKILL.md:

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output
└── scripts/
    └── validate.sh    # Script Claude can execute

Reference them from SKILL.md so Claude knows when to load them.

Commands = Legacy Skills​

Files in .claude/commands/review.md and .claude/skills/review/SKILL.md both create /review and work the same way. Commands are the old format — skills are recommended because they support directories with supporting files and additional frontmatter features.

Plugins — The Distribution Package​

A plugin bundles multiple skills + agents + hooks + MCP servers into one installable package.

Plugin Structure​

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Manifest (required)
├── skills/                  # Skills (SKILL.md files)
│   ├── code-review/
│   │   └── SKILL.md
│   └── deploy/
│       └── SKILL.md
├── agents/                  # Custom subagent definitions
├── hooks/                   # Event handlers
│   └── hooks.json
├── .mcp.json                # MCP server configs
├── .lsp.json                # LSP server configs
└── settings.json            # Default settings
Common Mistake

Don't put skills/, agents/, hooks/ inside .claude-plugin/. Only plugin.json goes there. Everything else lives at the plugin root.

Plugin Manifest​

The manifest at .claude-plugin/plugin.json defines your plugin's identity:

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Namespacing​

Plugin skills are always prefixed with the plugin name to prevent conflicts:

/my-plugin:code-review     ← skill "code-review" from plugin "my-plugin"
/my-plugin:deploy           ← skill "deploy" from plugin "my-plugin"

If two plugins both have a "deploy" skill, they become /plugin-a:deploy and /plugin-b:deploy. No collision.

Testing Locally​

Use --plugin-dir to load a plugin during development without installing it:

claude --plugin-dir ./my-plugin

Marketplaces — The Distribution Channel​

A marketplace is a JSON catalog that lists plugins and tells Claude Code where to download them.

Marketplace File​

Create .claude-plugin/marketplace.json in your repository root:

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "review-plugin",
      "source": "./plugins/review-plugin",
      "description": "Code review tools",
      "version": "1.0.0",
      "category": "development"
    },
    {
      "name": "deploy-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation"
    }
  ]
}

Plugin Sources​

Each plugin entry specifies where to fetch it from:

Source TypeFormatExample
Relative path"./plugins/my-plugin"Plugin in same repo
GitHub{ "source": "github", "repo": "owner/repo" }Any GitHub repo
Git URL{ "source": "url", "url": "https://gitlab.com/...git" }Any Git host
npm{ "source": "npm", "package": "pkg-name" }npm registry

The User Flow​

Claude Code native plugins (Claude Code only):

# Step 1: Add the marketplace (registers the catalog)
/plugin marketplace add owner/repo

# Step 2: Browse what's available
/plugin                          # opens interactive UI

# Step 3: Install a plugin
/plugin install plugin-name@marketplace-name

# Step 4: Use the skills
/plugin-name:skill-name

vskill (works across 49 AI agents — Claude Code, Cursor, Copilot, etc.):

# Install a plugin from a marketplace repo
npx vskill install --repo anton-abyzov/vskill --plugin mobile

# Install a standalone skill from GitHub
npx vskill install anton-abyzov/vskill
tip

The Claude Code native plugin system and vskill serve complementary roles. Native plugins integrate deeply with Claude Code's UI. vskill provides cross-agent installation with security scanning. See the Installing Skills guide for the full walkthrough, and the vskill CLI Reference for all commands.

Official Marketplace​

The official Anthropic marketplace (claude-plugins-official) comes pre-configured. It includes:

  • Code intelligence — LSP plugins for TypeScript, Python, Rust, Go, etc.
  • External integrations — GitHub, Slack, Jira, Figma, Vercel, Sentry
  • Workflow tools — commit commands, PR review toolkit

Where Installed Plugins Live​

~/.claude/plugins/
├── installed_plugins.json     # Registry of what's installed
└── cache/                     # Cached plugin files
    └── marketplace-name/
        └── plugin-name/
            └── version/
                ├── .claude-plugin/plugin.json
                └── skills/...

Real-World Example: SpecWeave​

SpecWeave is delivered as Claude Code plugins through two marketplaces. Here's what that looks like at scale.

The Marketplaces​

SpecWeave marketplace (anton-abyzov/specweave) ships 1 unified plugin with 44 skills:

PluginSkillsDomain
sw (unified)44Core lifecycle, PM, Architect, TDD, team orchestration, GitHub/JIRA/ADO sync, release management, diagrams, AI media

vskill marketplace (anton-abyzov/vskill) provides 5 additional domain plugins:

PluginSkillsDomain
mobile1App Store Connect automation
skills1Skill discovery and evaluation (scout)
marketing3Social media posting, Slack messaging, Chrome automation
productivity1Expert network survey automation
google-workspace3Google Workspace CLI (Gmail, Drive, Sheets, Docs, Calendar)

Beyond these bundled plugins, 100,000+ community skills are available via the verified-skill.com registry.

Simple vs Complex Skills​

A simple domain skill has minimal frontmatter — just description and tools:

---
description: Node.js/TypeScript backend developer for Express, Fastify, NestJS...
allowed-tools: Read, Write, Edit, Bash
model: opus
---

When building Node.js APIs, follow these patterns:
[detailed instructions...]

A complex workflow skill uses hooks, dynamic context, and subagent forking:

---
description: Plan and create SpecWeave increments
argument-hint: "<feature-description>"
context: fork
model: opus
hooks:
  PreToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: bash hooks/guards/template-enforcement.sh
  PostToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: bash hooks/guards/duplicate-guard.sh
---

Skill Chaining​

Skills invoke other skills for multi-step workflows:

sw:increment "user auth"
    → sw:pm skill activates (Product Manager writes spec)
        → sw:architect skill activates (designs the system)
            → backend:nodejs activates (implements)

Dynamic Context Injection​

SpecWeave skills inject project-specific overrides at load time using dynamic context injection blocks:

## Your Project's Customizations
!`for d in .specweave/skill-memories .claude/skill-memories; do
  [ -f "$d/pm.md" ] && cat "$d/pm.md"
done`

This loads "skill memories" — corrections you've made that persist across sessions. You tell Claude "use React Hook Form" once, and it remembers next time the PM skill activates.

Plugins Load On-Demand​

Domain plugins load based on what you're working on:

  • Say "mobile app" → mobile activates
  • Say "post on social media" → marketing activates
  • Say "Google Drive" → google-workspace activates

Key Takeaways​

  1. Skill = just a SKILL.md file -- instructions for Claude in markdown
  2. Plugin = a package -- bundles skills + agents + hooks with a plugin.json manifest
  3. Marketplace = a catalog -- lists plugins and where to download them via marketplace.json
  4. Commands = old name for skills -- .claude/commands/ still works, but skills are the current standard
  5. Namespacing prevents conflicts -- plugin skills become /plugin:skill
  6. Three invocation methods -- natural language (auto-trigger), slash command (sw:name), or CLI keyword (name in other AI tools)
  7. Real scale -- SpecWeave ships 44 skills in 1 unified plugin, plus 5 domain plugins via vskill and 100,000+ community skills

Next Steps​