Agent Extensions
An Agent Extension package bundles reusable agent capability — skills
(SKILL.md), MCP server configs, verified plugin files — authored once,
then written into each harness’s native location: .mcp.json for Claude,
.codex/config.toml for Codex, .cursor/mcp.json for Cursor,
opencode.jsonc for OpenCode.
Three states, not one
Section titled “Three states, not one”The lifecycle is discover → install → resolve → materialize, and each arrow
crosses a real state boundary:
| State | What it is | Who owns it |
|---|---|---|
| Desired | The install record: id, source, enabled, targets, scope. | The package, per workspace. |
| Effective | Desired state filtered through policy overrides (user / workspace / org precedence) into a snapshot. | Your control plane decides policy; the package resolves it. |
| Materialized | Harness-native files written on a runtime host, from exactly the snapshot it was handed. | The runtime, during config apply. |
Two consequences that prevent real bugs:
- Installed ≠ active. A package can be installed but disabled for a workspace, or filtered out by policy before the snapshot is produced. Activation is a policy decision, separate from install.
- Materialization never fans out. The package writes files for the one snapshot it receives. Which connected runtimes receive a workspace’s snapshot is your control plane’s job — by design, so team-wide activation and authorization stay in your product.
Safe by ownership records
Section titled “Safe by ownership records”Materialization keeps an ownership record (.agent-extensions/materialized.json)
and refuses to overwrite files it doesn’t own. Uninstall and disable remove
only owned artifacts. GitHub-sourced packages are locked by resolved SHA and
verified against recorded digests before replay.
Install, quickstart code, the CLI, snapshot format, and the replay API.