Skip to content
Maestria

Installation & Setup

@maestria/claude-code is a declarative Claude Code plugin - a .claude-plugin/plugin.json manifest plus directories of agent, skill, and command files, all generated from the canonical core directives. It is a self-contained directory: there is no npm install, no build step, and no runtime code.

Status: Native candidate. This package validates cleanly with the official Claude Code CLI, but runtime behavior is not yet tested end to end. Persistent installation is available through the Maestria CLI; do not treat the candidate status as a production support promise.

Prerequisites

Section titled “Prerequisites”
  • Claude Code with the claude CLI on PATH - required for validation and local loading.
  • Node.js and npm - required when installing through maestria install claude-code.
  • Node.js and pnpm - only needed to regenerate files from the canonical core directives.

Persistent installation through the Maestria CLI

Section titled “Persistent installation through the Maestria CLI”

Install the published plugin at Claude Code’s user scope:

Terminal window
npx maestria install claude-code

The CLI downloads @maestria/claude-code from npm, stages it in a local marketplace under ~/.cache/maestria/, and delegates the actual install to Claude Code. This keeps plugin state and scope in the host runtime.

Check, update, or remove the installation with:

Terminal window
npx maestria status
npx maestria update claude-code
npx maestria uninstall claude-code

Claude Code’s marketplace update path selects the latest package. Exact version pinning is not available through maestria update claude-code --version.

Local validation (no install)

Section titled “Local validation (no install)”

Because the plugin is a self-contained directory, you can validate and load it from a checkout of this repository without any install step:

Terminal window
# From the repository root
claude plugin validate ./packages/claude-code --strict

--strict treats warnings as errors and is the recommended CI check. A clean run prints:

✔ Validation passed

Loading the plugin

Section titled “Loading the plugin”

Load the plugin for a session only - it is not installed or persisted:

Terminal window
claude --plugin-dir ./packages/claude-code

--plugin-dir loads the plugin for that session only. You can pass it multiple times to load several plugins.

Verify Installation

Section titled “Verify Installation”

  1. Validate the manifest

    Terminal window
    claude plugin validate ./packages/claude-code --strict

    Prints ✔ Validation passed.

  2. Start a session with the plugin loaded

    Terminal window
    claude --plugin-dir ./packages/claude-code

  3. Confirm the plugin and its components loaded

    Check the /plugin manager and the /context Custom Agents tab. Components are namespaced under the plugin name maestria:

    • Agents: @maestria:adventurer, @maestria:architect, @maestria:builder, @maestria:diagnose, @maestria:planner, @maestria:reviewer, @maestria:writer
    • Commands: /maestria:fein, /maestria:sonar, /maestria:blitz
    • Skills: /maestria:orchestrator (user-invocable). maestria:global-rules is auto-preloaded into every agent and is preload-only - it is not user-invocable.

  4. Check the read-only roles

    @maestria:adventurer, @maestria:planner, and @maestria:reviewer cannot call the Write or Edit tools (denied via disallowedTools).

What’s Inside

Section titled “What’s Inside”
Component Namespaced identifier Purpose
Agents @maestria:<agent> 7 specialist agents: adventurer, architect, builder, diagnose, planner, reviewer, writer
Skills /maestria:orchestrator, maestria:global-rules Routing methodology (user-invocable) and universal rules contract (preload-only)
Commands /maestria:fein, /maestria:sonar, /maestria:blitz Full pipeline, research-only, and fast implementation modes

Every agent is configured to preload the maestria:global-rules skill at startup. Runtime resolution of the plugin-scoped skill preload is not yet verified against a live session.

Tool Restrictions

Section titled “Tool Restrictions”

The only runtime enforcement in this package is disallowedTools: Write, Edit on adventurer, planner, and reviewer - the three read-only research and review roles. This is user-authorized. Everything else (skills, preloaded rules, role prompts) is advisory prompt guidance, not a security boundary.

Claude Code ignores the permissionMode, hooks, and mcpServers agent frontmatter fields for plugin-loaded agents for security reasons, so this plugin ships none of them. To enforce those fields you would need to copy an agent file into .claude/agents/ or ~/.claude/agents/.

The plugin does not ship a rules/ directory and does not write project or user CLAUDE.md files.

Uninstalling

Section titled “Uninstalling”

For a persistent CLI-managed installation:

Terminal window
npx maestria uninstall claude-code

For a session-only --plugin-dir load, stop passing the flag. The local staging directory is safe to remove after uninstalling:

Terminal window
rm -rf ~/.cache/maestria/claude-code-marketplace

Direct Claude Code marketplace installation

Section titled “Direct Claude Code marketplace installation”

The repository also exposes a Claude Code marketplace entry for users who prefer the host CLI:

Terminal window
claude plugin marketplace add agustinusnathaniel/maestria
claude plugin install maestria@maestria --scope user

Next Steps

Section titled “Next Steps”