@maestria/agent-plugin

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

Choose portable when

You want the same skills across compatible clients and want the client to own discovery, permissions, activation, and session behavior. Choose a native integration when you need 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 before choosing an installation path.

The compatibility matrix records dated client checks. A check confirms package discovery and skill loading; it does not promise native agents, commands, hooks, permissions, or session behavior.

What You Get

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

The package contains 14 skills. Each one lives at skills/<name>/SKILL.md and uses the standard Agent Skills layout.

Install It

With the Maestria CLI

To stage and validate a published package:

npx maestria plugin install

The command prints the staged directory. Give that directory to the compatible client’s plugin installer or local-plugin setting.

To validate a local package without changing it:

npx maestria plugin validate /path/to/plugin

Use –json when another tool needs a machine-readable report. The CLI does not activate the package or modify 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:

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

Choose the directory containing plugin.json, not only its nested skills directory. A local checkout is useful when testing unreleased changes.

Use the Skills

Load global-rules for the full evidence, authorization, and review contract. Then load orchestrator to choose a route, or load the specialist that matches the work:

Need	Skill
Understand unfamiliar code	adventurer
Compare approaches	architect
Make a focused change	builder
Find a failure’s cause	diagnose
Plan multiple phases	planner
Check work independently	reviewer
Write documentation	writer

Use the client’s normal skill-loading mechanism. The package does not assume one invocation syntax.

Portable and Native Boundaries

Use portable skills when client-neutral guidance is enough. Use a native integration when you need platform-specific runtime features. The portable package and a native integration 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.
• If the staging destination exists, choose another destination.

Resources

Compatible clientsSee which clients support Agent Plugins and which components they implement.

Compatibility matrixSee dated smoke results and client-specific verification steps.

Agent Plugins v1 specificationRead the manifest, skills layout, and client-conformance rules.

Package sourceView the manifest, installation guide, and generated skills.