What a Claude Code skills plugin actually is

No. A skill is a folder containing a single SKILL.md (plus optional scripts and resources) that Claude Code loads dynamically when its frontmatter description matches the active task. A plugin is the shipping container: a directory with a .claude-plugin/plugin.json (or marketplace entry) that can include one or more skills, plus any combination of MCP servers, slash commands, hooks, output styles, and subagents. The plugin format exists so that a single /plugin install command pulls down a whole capability bundle instead of cloning seven repos by hand. If a tool only adds one SKILL.md, the plugin format is overkill; if it adds a SKILL.md, an MCP server config, and a few slash commands together, the plugin format is what holds them together.

It looks up the named plugin in the local marketplace cache, downloads the plugin's directory tree from its git source, copies it into ~/.claude/plugins/cache/<marketplace>/<plugin>/, and registers it in your user-scope settings under enabledPlugins. Each skill the plugin contains becomes addressable as /<plugin-name>:<skill-name>, each slash command becomes a top-level slash command, each MCP server is registered, and each hook is wired into the relevant lifecycle event. If you install while a Claude Code session is open, you also need to run /reload-plugins to pick up the new skills/commands/hooks/servers without restarting. The cache directory is the reason "files not found after installation" errors show up when a plugin references files outside its own folder: only the files inside the plugin directory get copied.

It's a built-in marketplace named claude-plugins-official, automatically registered on first run. It includes three main families: code intelligence plugins that wire up Language Server Protocol for clangd, gopls, pyright, rust-analyzer, sourcekit-lsp, typescript-language-server, and friends (each is a separate plugin); external-integration plugins that bundle pre-configured MCP servers for github, gitlab, atlassian, asana, linear, notion, figma, vercel, firebase, supabase, slack, and sentry; and development workflow plugins like commit-commands, pr-review-toolkit, agent-sdk-dev, and plugin-dev. The full catalog is browsable inside Claude Code with /plugin (Discover tab) or on the web at claude.com/plugins.

Yes, because Fazm runs the real Claude Code under the hood via @agentclientprotocol/claude-agent-acp 0.29.2 (pinned in /Users/matthewdi/fazm/acp-bridge/package.json line 15). The agent loop is not a reimplementation; it's the same Node.js process that the claude CLI spawns, just driven through ACP and rendered in a native SwiftUI window. Slash commands like /plugin install, /plugin marketplace add owner/repo, and /reload-plugins all work because they're handled by Claude Code itself, not by the wrapper. The wrapper adds a sidecar layer (custom MCP servers for browser and accessibility-API control, persistent windows, no auto-compact) on top of that loop, but it never replaces the Claude Code primitives.

Both end up in the same place (~/.claude/skills/<name>/SKILL.md), and Claude Code does not distinguish between them at load time. The delivery channel differs. A marketplace plugin is fetched over the network from a git source the first time you run /plugin install, cached under ~/.claude/plugins/cache/, and refreshed when you run /plugin marketplace update or when auto-update fires at startup. A Fazm bundled skill ships inside the signed .app bundle at Contents/Resources/BundledSkills/<name>.skill.md, is installed to ~/.claude/skills/<name>/SKILL.md on first launch, and is reconciled on every subsequent launch via a SHA-256 checksum compare (SkillInstaller.swift lines 118-122). The practical implication: bundled skills update when you accept a Fazm app update (via Sparkle), marketplace plugins update when you run /plugin marketplace update or have auto-update on for that marketplace.

Yes. The minimum viable plugin is a directory with a .claude-plugin/plugin.json declaring the plugin's name and a skills/ subfolder with one or more <skill-name>/SKILL.md files. Drop it into a directory you control, run /plugin marketplace add ./path/to/your-marketplace (the marketplace can be the same directory if it also has a .claude-plugin/marketplace.json file listing the plugin), then /plugin install <plugin-name>@<marketplace-name>. The plugin-dev plugin in the official marketplace ships scaffolding for this. The /plugin marketplace add command also accepts a direct path to a marketplace.json file or a GitHub owner/repo shorthand.

If you only need to teach Claude one repeatable workflow, dropping a SKILL.md is the smaller and more transparent option: one file, no manifest, no marketplace. Plugins start being worth the overhead when you need to ship more than just instructions: MCP server configurations, slash commands (so the user can type /yourthing:command instead of asking Claude to do something), hooks (pre-tool-use and post-tool-use callbacks), subagent definitions, or output style overrides. Plugins are also versioned and updatable through the marketplace; loose SKILL.md files are not. Most users land somewhere in the middle: a few personal skills as loose ~/.claude/skills/ folders, and one or two heavier capabilities as installed plugins.

The two namespaces don't share names by default. Marketplace plugins install skills under their plugin namespace: /<plugin-name>:<skill-name>. Bundled and hand-installed skills live at ~/.claude/skills/<skill-name>/SKILL.md and are addressed by Claude without a prefix. So a plugin named pdf-toolkit that ships a pdf skill becomes /pdf-toolkit:pdf and does not collide with Fazm's bundled pdf skill at ~/.claude/skills/pdf/SKILL.md. If you do install a loose SKILL.md with the same name as a bundled one, Fazm's SkillInstaller will reconcile it back to the bundled version on next launch via the SHA-256 compare, which is the documented tradeoff: bundled skills are treated as first-party app resources, not user data.

Two ways. Inside Claude Code, run /plugin and go to the Installed tab. Plugins with load errors or unresolved dependencies appear at the top of the list; disabled plugins are folded under a collapsed footer. The Errors tab shows specific load failures (most commonly an LSP plugin whose required binary isn't on $PATH). From the shell, the cache lives under ~/.claude/plugins/cache/<marketplace>/<plugin>/, and the user-scope manifest is at ~/.claude/settings.json under enabledPlugins. If a skill in a plugin isn't firing, the usual fixes are /reload-plugins (picks up changes without restarting), clearing the cache with rm -rf ~/.claude/plugins/cache and reinstalling, or checking that the skill's frontmatter description matches the kind of task you're asking about.

On top. Plugins are a packaging and distribution format; MCP is still the transport for tools that need to call out to external services or run code. A plugin like github@claude-plugins-official ships a pre-configured MCP server entry inside its plugin.json, so installing the plugin registers the MCP server automatically. You can also still configure an MCP server manually via mcp servers in your settings.json, no plugin required. The plugin format is the easier on-ramp; the manual MCP path is what power users still use when they need to run a server with custom env vars or a non-standard command line.