# @maestria/agent-plugin

@maestria/agent-plugin packages Maestria's workflow methodology as standard [Agent Skills](https://agentskills.io/specification) for clients that support the [Agent Plugins v1 format](https://agent-plugins.org/).

**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](https://agent-plugins.org/compatible-clients) list. The [compatibility matrix](/agent-plugin/compatibility/) 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](/core/agents/) for roles. The package assumes no single invocation syntax.

## Install the package

### With the Maestria CLI

To stage and validate a published package:

<AllPackageManagers type="dlx" pkg="maestria@latest" args="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:

<AllPackageManagers type="dlx" pkg="maestria@latest" args="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:

```text
/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](/opencode/)       |
| Claude Code agents, commands, and restrictions      | [Claude Code](/claude-code/) |
| Codex CLI skills and native agents                  | [Codex CLI](/codex/)         |
| Cursor agents, rules, and commands                  | [Cursor](/cursor/)           |
| Pi or Oh My Pi dispatch and session behavior        | [Pi and OMP](/pi-omp/)       |
| Hermes trust and lifecycle integration              | [Hermes Agent](/hermes/)     |
| Prime Agent skills and extension subset             | [Prime Agent](/prime-agent/) |
| Kimi Code skills, commands, and session integration | [Kimi Code](/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 clients](https://agent-plugins.org/compatible-clients)
  [Compatibility matrix](/agent-plugin/compatibility/)
  [Agent Plugins v1 specification](https://agent-plugins.org/specification)
  [Package source](https://github.com/agustinusnathaniel/maestria/tree/main/packages/agent-plugin)