Package format reference
In short
- A harness is a
harness/folder at the package root: an Agent Plugins 1.0 plugin plus thedev.harnesspmextension. - Every file is optional except
plugin.json. - Every unit has an ID,
<plugin name>:<kind>/<name>, which projects use to exclude, replace or patch it.
The specification’s chapters on the package format and executables, on GitHub, have every rule.
harness/
├── plugin.json Agent Plugins manifest (required)
├── skills/
│ └── acme-ui-review/
│ └── SKILL.md Agent Skills
├── mcp.json Agent Plugins MCP configuration
└── dev.harnesspm/ harnesspm extension folder
├── rules/
│ └── usage.md
├── patches/
│ └── acme-colors-usage.patch.md
├── agents/
│ └── acme-ui-reviewer.md
├── scripts/
│ └── tokens.mjs
├── hooks.json
└── permissions.json{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "acme-ui",
"description": "Rules, docs and tools for building UIs with @acme/ui",
"extensions": {
"dev.harnesspm": {
"extends": ["@acme/colors", "@acme/styles"],
"docs": "../docs",
"scripts": {
"tokens": {
"file": "./dev.harnesspm/scripts/tokens.mjs",
"description": "Find a color token by a part of its name, with its light and dark values",
"allow": true
}
},
"exclude": ["acme-styles:hooks/check-edit"],
"replace": { "acme-styles:rules/components": "./dev.harnesspm/rules/components.md" },
"patch": { "acme-colors:rules/usage": "./dev.harnesspm/patches/acme-colors-usage.patch.md" }
}
}
}| Field | Required | Meaning |
|---|---|---|
$schema |
Yes | The Agent Plugins schema. |
name |
Yes | The plugin name: lowercase letters, digits, - and .. It starts every unit ID. |
version |
No | Defaults to version in package.json. |
description, author, homepage, repository, license, keywords |
No | Agent Plugins metadata. |
| Field | Type | Meaning |
|---|---|---|
extends |
string[] | Packages whose harness this one passes on, resolved from this package’s folder. |
exclude |
string[] | Units or packages to drop from what it passes on. |
replace |
object | Unit ID → a file that takes the unit’s place. |
patch |
object | Rule ID → a patch that changes some of its sections. |
docs |
string | The docs folder, relative to harness/, inside the package. |
scripts |
object | Script name → { file, description?, allow? }. |
projects |
object | Git remote → a folder with units for that repository. Read only in added harnesses. |
harnesspm check fails on an unknown field, so typos do not ship.
| Kind | Location | ID |
|---|---|---|
| Rule | dev.harnesspm/rules/<name>.md |
acme-ui:rules/<name> |
| Skill | skills/<name>/SKILL.md |
acme-ui:skills/<name> |
| Sub-agent | dev.harnesspm/agents/<name>.md |
acme-ui:agents/<name> |
| Docs | The folder in docs |
acme-ui:docs |
| Script | scripts in plugin.json |
acme-ui:scripts/<name> |
| Hook | dev.harnesspm/hooks.json, by id |
acme-ui:hooks/<id> |
| MCP server | mcp.json, by server name |
acme-ui:mcp/<name> |
| Permissions | dev.harnesspm/permissions.json |
acme-ui:permissions |
Commands name scripts and MCP servers as <plugin>:<name>: npx harnesspm run acme-ui:tokens. Agents see an MCP server as <plugin>-<server>, such as acme-ui-docs.
| Frontmatter | Activation |
|---|---|
| None | Always on. The text goes into the managed block. |
paths, with or without description |
File-scoped. Active when the agent works on matching files. |
description only |
On demand. Listed with its description. |
paths are globs from the project root. A pattern without a leading / also matches at any depth. Start it with /, such as /harness/**, to match only at the root.
---
remove: ["Contrast"]
---
## Where colors come from
- In an app on Acme UI, colors are Acme UI tokens: follow the Acme UI rule.A section is a heading and everything up to the next heading of the same or a higher level. A section in the patch replaces the one with the same heading and level, or is added at the end. remove lists sections to remove.
---
name: acme-ui-reviewer
description: Reviews UI changes against the Acme UI rules. Use for UI pull requests.
claude: { tools: "Read, Grep, Glob", model: "sonnet" }
codex: { model_reasoning_effort: "medium" }
---
Review the change like an owner. Do not edit files.name, description and the body are portable. Settings for one agent go under its own key.
| Field | Required | Meaning |
|---|---|---|
file |
Yes | Path inside harness/, starting with ./. |
description |
No | Shows the script to agents. Without it, only hooks and MCP servers use it. |
allow |
No | Asks that agents may run it without a prompt, in projects that trust the package. |
The runner sets PLUGIN_ROOT, PLUGIN_DATA, HARNESSPM_PROJECT_DIR and HARNESSPM_AGENT. It runs .js, .mjs and .cjs files with node, .sh files with sh, and other files directly.
{
"hooks": {
"PostToolUse": [
{ "id": "check-styles", "matcher": { "claude": "Edit|Write" }, "run": "check-styles", "timeout": 30 }
]
}
}| Field | Required | Meaning |
|---|---|---|
id |
Yes | The unit name. |
run |
Yes | A script name from scripts. |
matcher |
No | A string for both agents, or an object with claude and codex keys. |
timeout |
No | Seconds. |
Events: SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SubagentStart, SubagentStop, Stop. A hook script reads the agent’s JSON on stdin, exits 0 to continue and 2 to block, with the reason on stderr.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"docs": { "type": "stdio", "command": "node", "args": ["${PLUGIN_ROOT}/dev.harnesspm/scripts/docs-mcp.mjs"] },
"figma": { "type": "streamable-http", "url": "https://example.com/mcp" }
}
}stdio servers start through npx harnesspm mcp <plugin>:<server>. Remote servers are written as they are. Never put secrets in mcp.json.
{
"deny": [["git", "push", "--force"]],
"ask": [["npm", "publish"]]
}Deny and ask rules are command prefixes. They pass through from any package. Allow rules come only from "allow": true on a trusted package’s own scripts.