Skip to content
maestria

Installation & Setup

@maestria/prime-agent ships two resource types that Prime discovers from the pi manifest key in package.json:

  • Skills (pi.skills: ["./skills"]): the 14 Agent Skills (skills/<name>/SKILL.md).
  • Extension (pi.extensions: ["./dist/extension.mjs"]): a compiled Prime/Pi extension with the workflow-mode slash commands (/fein, /sonar, /blitz, /mode-clear, /maestria-status) and mode prompt injection.

Prerequisites

Section titled “Prerequisites”
  • Prime Agent installed (see Prime’s getting started).
  • Node.js and pnpm are only needed to contribute to this repository; Prime installs registered packages itself.

Register the package (preferred, enables the extension)

Section titled “Register the package (preferred, enables the extension)”
Terminal window
prime-agent package install npm:@maestria/prime-agent

The package is recorded in global settings (~/.prime/agent/settings.json); add --local to record it in project settings (.prime/agent/settings.json), which Prime installs automatically at startup. Prime reads the package’s pi.extensions and pi.skills entries to discover the extension and the skills; this is the only documented install path that enables the extension automatically.

Git and local source installs are skills-only unless the package is built first: Prime clones the repository and runs npm install, but does not build, so dist/extension.mjs is absent. To use the extension from a source install:

Terminal window
pnpm --filter @maestria/prime-agent build
prime-agent package install local:/path/to/maestria/packages/prime-agent

Skills-only options (no extension)

Section titled “Skills-only options (no extension)”

To install only the skills, point the skills setting at the package’s skills/ directory in ~/.prime/agent/settings.json or .prime/agent/settings.json:

{
  "skills": ["/path/to/maestria/packages/prime-agent/skills"]
}

You can also copy or symlink the skill directories into a project or global skill location. To add the extension later, point the extensions setting at the compiled dist/extension.mjs (a source clone needs the build command above first).

Verify the installation

Section titled “Verify the installation”

  1. Start Prime Agent from the repository or project you want it to work in.

  2. Reload to rediscover skill metadata and extension registration:

    Terminal window
    /reload

  3. Confirm the skills appear. Run /skill:orchestrator or ask the agent to load the global-rules skill.

  4. Confirm the extension loaded. Run /maestria-status; it should report the current mode (none initially) and the verified/deferred subset. Try /fein, /sonar, /blitz, and /mode-clear.

Runtime checks in steps 3-4 are not yet verified end to end; see the runtime support matrix.

Uninstall

Section titled “Uninstall”
Terminal window
prime-agent package remove npm:@maestria/prime-agent

For a skills-only install, remove the settings skills or extensions entries or the symlink.

Next Steps

Section titled “Next Steps”