Statement#

• A plugin folder holds .claude-plugin/plugin.json (name, version, description, author), skills/<name>/SKILL.md, commands/<name>.md, hooks/hooks.json and .mcp.json. A marketplace is a folder with .claude-plugin/marketplace.json (name, owner, metadata.description, plugins[] with name and source: "./plugins/<name>").
• A folder marketplace works offline: claude plugin marketplace add <folder>, then claude plugin install <plugin>@<marketplace>. After a change: claude plugin marketplace update <marketplace> and claude plugin update <plugin>@<marketplace>, then restart Claude Code.
• A version like 0.1.0+<hash> works: update sees a new hash, and the cache folder becomes cache/<marketplace>/<plugin>/0.1.0-<hash>.
• claude plugin validate <folder> warns when plugin.json has no author or the marketplace has no metadata.description.
• Plugin commands and skills are namespaced: /<plugin>:<name>. A plugin MCP server's tools are named mcp__plugin_<plugin>_<server>__<tool>.
• Claude Code adds model-visible tools only through MCP servers. Hooks and plugins cannot add tools on their own, and plugins cannot set permissions: permissions.ask and permissions.allow stay in settings.json.
• Installed state is in ~/.claude/plugins/installed_plugins.json (plugins["<plugin>@<marketplace>"][0].version) and known_marketplaces.json; claude plugin list --json gives id, version, installPath.

Evidence#

Tried with a throwaway HOME and a demo plugin: install and +hash update worked offline. The rkb plugin passed claude plugin validate with no warnings after adding author and metadata.description, and loaded in a new session with /rkb:retro and the four mcp__plugin_rkb_rkb__* tools. The layout, naming and permission facts come from code.claude.com/docs/en/plugins.