@maestria/agent-plugin

@maestria/agent-plugin packages maestria’s workflow methodology as standard Agent Skills for clients that support the Agent Plugins v1 format.

When to choose the portable package

Choose it when you want the same skills across compatible clients with client-owned discovery, permissions, activation, and sessions. Choose a native integration for host features such as native subagents, hooks, commands, or tool controls.

Before You Install

You need a client that supports Agent Plugins v1 and its skills component; check the compatible clients list. The compatibility matrix records dated client checks: a pass confirms package discovery and skill loading, not native agents, commands, hooks, permissions, or session behavior.

What You Get

Group	Skills	Use
Coordination	global-rules, orchestrator, handoff, iteration-limits	Set expectations, route, transfer context, bound long tasks
Specialists	adventurer, architect, builder, diagnose, planner, reviewer, writer	Understand, design, build, debug, plan, review, document
Modes	fein, sonar, blitz	Choose full, research-only, or fast work

All 14 skills live at skills/<name>/SKILL.md. Load global-rules for the full contract, then orchestrator or the specialist that matches the work; see the Specialist Reference for roles. The package assumes no single invocation syntax.

Install the package

With the maestria CLI

To stage and validate a published package:

npm

npx maestria@latest plugin install

yarn

yarn dlx maestria@latest plugin install

pnpm

pnpx maestria@latest plugin install

bun

bunx maestria@latest plugin install

deno

deno x maestria@latest plugin install

ni

nlx maestria@latest plugin install

The command prints the staged directory for the client’s plugin installer or local-plugin setting. To validate a local package without changing it:

npm

npx maestria@latest plugin validate /path/to/plugin

yarn

yarn dlx maestria@latest plugin validate /path/to/plugin

pnpm

pnpx maestria@latest plugin validate /path/to/plugin

bun

bunx maestria@latest plugin validate /path/to/plugin

deno

deno x maestria@latest plugin validate /path/to/plugin

ni

nlx maestria@latest plugin validate /path/to/plugin

Use –json for a machine-readable report; the CLI never activates the package or modifies client configuration.

In a Compatible Client

1. Open the client’s plugin or extension installer.
2. Install @maestria/agent-plugin, or select the directory printed by maestria plugin install.
3. Reload installed skills or start a new session.

The exact activation command depends on the client: Agent Plugins standardizes the package shape, while each client decides how packages are discovered, installed, trusted, updated, and enabled.

The command is intentionally namespaced as maestria plugin ...: maestria install manages runtime integrations, while maestria plugin manages portable artifacts.

From a Local Checkout

Point a client that accepts local plugins at the directory containing plugin.json rather than its nested skills directory:

/path/to/maestria/packages/agent-plugin/

A local checkout is useful when testing unreleased changes.

Portable and Native Boundaries

Use portable skills for client-neutral guidance, and a native integration for platform-specific runtime features. The two can coexist.

Need	Native guide
OpenCode agents, rules, and compaction	OpenCode
Claude Code agents, commands, and restrictions	Claude Code
Codex CLI skills and native agents	Codex CLI
Cursor agents, rules, and commands	Cursor
Pi or Oh My Pi dispatch and session behavior	Pi and OMP
Hermes trust and lifecycle integration	Hermes Agent
Prime Agent skills and extension subset	Prime Agent
Kimi Code skills, commands, and session integration	Kimi Code

The package provides instructions and workflow resources. It does not provide:

• native subagent registration
• slash commands or lifecycle hooks
• MCP servers or tool interception
• permissions, sandboxing, or trust decisions
• session state or scheduled automation

Read-only roles are guidance, not a security boundary; the consuming client remains responsible for tool access and execution safety.

If Skills Do Not Appear

• Confirm the selected directory contains plugin.json and skills/.
• Reload the client’s plugins or start a new session.
• Check the client’s supported Agent Plugins components and trust settings.

Resources

Compatible clientsSupported clients and their implemented components.

Compatibility matrixDated smoke results and client-specific verification steps.

Agent Plugins v1 specificationManifest, skills layout, and client-conformance rules.

Package sourceManifest, installation guide, and generated skills.