claude-vault

Claude-Vault

Meta-plugin for per-project activation of dormant plugins and MCP servers from a personal vault.

Mitigates the user-level eager skill-description loading problem (see Claude-Vault-Idea for the full write-up): plugins enabled at user level inject all their skill descriptions into every session's system prompt. With many plugins installed, that adds up. The vault pattern keeps everything installed-but-dormant and activates only what each project needs, by editing project-level .claude/settings.json and .mcp.json.

This is a workaround for a current Claude Code limitation, not a permanent design.

Status

Functional: list-vault, list-active, activate-plugin, activate-mcp, deactivate-plugin, deactivate-mcp, activate-bundle, update-vault, vault-search. Stubs: setup-workspace, bundle-create.

Progressive discovery

The discovery problem with dormant plugins: once skills are off, you stop knowing they exist. Claude-Vault solves this with a single always-on skill, vault-search, that greps a flat skill-index across every dormant plugin in the vault. Ask "is there something for trimming silence?" — vault-search finds the candidate skill, names its parent plugin, and offers to activate it. The full skill descriptions never enter context until you opt in.

The index is generated by update-vault from the inventory's per-plugin skills metadata (or by best-effort scanning of installed SKILL.md files when metadata is absent). Format is one pipe-delimited line per skill — see skills/_shared/skill-index.md.

Install

claude plugin install Claude-Vault

(Or clone and add via your local marketplace.)

Then create the vault inventory file (see Vault inventory format below). Resolve the path as:

• $CLAUDE_USER_DATA/claude-vault/inventory.json if CLAUDE_USER_DATA is set
• else $XDG_DATA_HOME/claude-plugins/claude-vault/inventory.json if XDG_DATA_HOME is set
• else ~/.local/share/claude-plugins/claude-vault/inventory.json

(Plugin data must not live under ~/.claude/ — that's Claude Code's own config surface and gets clobbered on plugin updates.)

Skills

Skill	Status	What it does
vault-search	✅	Find a dormant skill or plugin by keyword (progressive discovery)
list-vault	✅	Enumerate plugins, MCP servers, and bundles in the inventory
list-active	✅	Show what's currently enabled in the current project
activate-plugin	✅	Enable a vault plugin in the current project's .claude/settings.json
activate-mcp	✅	Add a vault MCP server to the current project's .mcp.json
activate-bundle	✅	Apply a named bundle (plugins + MCP servers) in one shot
deactivate-plugin	✅	Disable a plugin in the current project (symmetric to activate-plugin)
deactivate-mcp	✅	Unmount an MCP server from the current project
update-vault	✅	Pull plugin updates and regenerate the skill-index for vault-search
setup-workspace	🚧	Bootstrap a new project with a chosen template + tools
bundle-create	🚧	Save the current project's tool set as a reusable bundle

Vault inventory format

Inventory file (resolved per the path rules above):

{
  "plugins": [
    {
      "name": "podcast-production",
      "marketplace": "danielrosehill",
      "description": "Tools for podcast editing and publishing",
      "tags": ["podcast", "audio"],
      "skills": [
        { "name": "trim-silence", "description": "Trim leading and trailing silence from an audio file" },
        { "name": "denoise", "description": "Remove background noise from an audio recording" }
      ]
    }
  ],
  "mcpServers": [
    {
      "name": "greeninvoice",
      "description": "Israeli invoicing API",
      "config": {
        "command": "npx",
        "args": ["-y", "@greeninvoice/mcp-server"],
        "env": { "GREENINVOICE_API_KEY": "${GREENINVOICE_API_KEY}" }
      },
      "tags": ["finance", "israel"]
    }
  ],
  "bundles": [
    {
      "name": "podcast",
      "description": "Full podcast production stack",
      "plugins": ["podcast-production"],
      "mcpServers": []
    }
  ]
}

Plugins must already be installed on your system (cloned from a marketplace). The vault is an activation layer, not an installer — it does not fetch plugins.

The optional skills array per plugin entry is what powers vault-search. It's optional: if absent, update-vault will best-effort scan the plugin's installed SKILL.md files. Carrying the metadata in the inventory is faster and more reliable.

Workflow