pm_capability
{"content":"{{\u003c badge content=\"Vanguard\" color=\"blue\" class=\"tier-badge\" \u003e}}\n\nThe `pm_capability` tool manages capabilities — the markdown instruction blocks that define agent behavior. Capabilities are the building blocks of workflows: an agent's system prompt composes its identity with one or more capabilities to control what it does and how.\n\n## Actions\n\n`create`, `get`, `list`, `update`, `delete`, `ensure`, `prompt`, `help`\n\n---\n\n## create\n\nCreate a new capability.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `key` | string | Yes | Unique capability key (e.g., `\"review.quality-gate\"`) |\n| `role` | string | Yes | `core`, `workflow`, `constraints`, `context`, `validation`, or `integration` |\n| `id` | string | No | Explicit ID override |\n| `name` | string | No | Human-readable name |\n| `category` | string | No | Grouping category |\n| `promptId` | string | No | Linked prompt ID |\n| `pack` | string | No | Pack this capability belongs to |\n\n### Example\n\n```text\npm_capability {\n action: \"create\",\n key: \"review.quality-gate\",\n role: \"core\",\n name: \"Quality Gate Enforcement\",\n category: \"review\",\n promptId: \"01HPROMPT...\"\n}\n```\n\n---\n\n## get\n\nFetch a capability by ID or key.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `id` | string | One of |\n| `key` | string | One of |\n\n---\n\n## list\n\nList capabilities with optional filters.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `search` | string | No | Search text |\n| `category` | string | No | Filter by category |\n| `promptIds` | string[] | No | Filter by linked prompt |\n| `limit` | number | No | 1–1000 |\n\n---\n\n## update\n\nUpdate a capability. Pass `null` to clear optional fields like `category`, `promptId`, or `pack`.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `id` | string | Yes |\n| `key` | string | No |\n| `name` | string | No |\n| `category` | string \\| null | No |\n| `promptId` | string \\| null | No |\n| `role` | string | No |\n| `pack` | string \\| null | No |\n\n---\n\n## delete\n\nDelete a capability.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `id` | string | Yes |\n\n---\n\n## ensure\n\nCreate or update a capability by key (upsert). Useful for registration flows where you want to re-run the same call safely.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `key` | string | Yes |\n| `name` | string | No |\n| `category` | string | No |\n| `promptId` | string | No |\n| `role` | string | No |\n| `pack` | string | No |\n\n### Example\n\n```text\npm_capability {\n action: \"ensure\",\n key: \"review.quality-gate\",\n name: \"Quality Gate Enforcement\",\n role: \"core\",\n promptId: \"01HPROMPT...\"\n}\n```\n\n---\n\n## prompt\n\nFetch the linked prompt content for a capability. This is the **hot-load** action — agents call this on demand when they need to load a capability into context.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `key` | string | Yes |\n\n### Returns\n\n```json\n{ \"role\": \"core\", \"capability\": \"...prompt text...\" }\n```\n\nReturns `capability: null` if no prompt is linked.\n\n### Example\n\n```text\npm_capability {\n action: \"prompt\",\n key: \"review.quality-gate\"\n}\n```\n\nThis is how agents load capabilities on demand without inflating their base system prompt. Hot-load the capability, use it, move on.\n\n---\n\n## help\n\nReturn the structured action reference from the running MCP server.\n\n```text\npm_capability { action: \"help\" }\n```\n\nThe help payload is a read-only contract for capability registry automation:\n\n| Field | Contents |\n|-------|----------|\n| `actions` | Every accepted `pm_capability` action: `create`, `get`, `list`, `update`, `delete`, `ensure`, `prompt`, and `help` |\n| `whenToUse` | Action-by-action guidance for registry lookup, idempotent synchronization, mutation, deletion, and runtime prompt hot-loading |\n| `examples` | Representative calls such as listing workflow capabilities, ensuring a capability key, and hot-loading a capability prompt |\n| `cautions` | Guardrails for missing linked prompts, using `ensure` for repeatable sync, and treating `promptId` as a prompt record ID |\n| `compatibility` | Notes that structured help is additive and does not change existing inputs, action names, validation, or non-help result shapes |\n\nUse `help` when building pack importers, agent launchers, or docs that need to reflect the current capability surface. Because the structured help schema is additive, older clients can ignore it while newer agents use it to choose `ensure` versus `create` and `prompt` versus `get`.\n\n## Related\n\n- [pm_agent](../agents/) — agents are bound to capabilities\n- [pm_prompt](../prompts/) — capabilities link to prompts for their content\n- [Valdr Packs](/valdr/docs/valdr-packs/) — how capabilities are authored and shipped","description":"Create and manage capabilities — reusable instruction blocks that define how agents behave.","title":"pm_capability"}
Vanguard
The pm_capability tool manages capabilities — the markdown instruction blocks that define agent behavior. Capabilities are the building blocks of workflows: an agent’s system prompt composes its identity with one or more capabilities to control what it does and how.
Actions
create, get, list, update, delete, ensure, prompt, help
create
Create a new capability.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
key | string | Yes | Unique capability key (e.g., "review.quality-gate") |
role | string | Yes | core, workflow, constraints, context, validation, or integration |
id | string | No | Explicit ID override |
name | string | No | Human-readable name |
category | string | No | Grouping category |
promptId | string | No | Linked prompt ID |
pack | string | No | Pack this capability belongs to |
Example
pm_capability {
action: "create",
key: "review.quality-gate",
role: "core",
name: "Quality Gate Enforcement",
category: "review",
promptId: "01HPROMPT..."
}get
Fetch a capability by ID or key.
Parameters
| Field | Type | Required |
|---|---|---|
id | string | One of |
key | string | One of |
list
List capabilities with optional filters.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
search | string | No | Search text |
category | string | No | Filter by category |
promptIds | string[] | No | Filter by linked prompt |
limit | number | No | 1–1000 |
update
Update a capability. Pass null to clear optional fields like category, promptId, or pack.
Parameters
| Field | Type | Required |
|---|---|---|
id | string | Yes |
key | string | No |
name | string | No |
category | string | null | No |
promptId | string | null | No |
role | string | No |
pack | string | null | No |
delete
Delete a capability.
Parameters
| Field | Type | Required |
|---|---|---|
id | string | Yes |
ensure
Create or update a capability by key (upsert). Useful for registration flows where you want to re-run the same call safely.
Parameters
| Field | Type | Required |
|---|---|---|
key | string | Yes |
name | string | No |
category | string | No |
promptId | string | No |
role | string | No |
pack | string | No |
Example
pm_capability {
action: "ensure",
key: "review.quality-gate",
name: "Quality Gate Enforcement",
role: "core",
promptId: "01HPROMPT..."
}prompt
Fetch the linked prompt content for a capability. This is the hot-load action — agents call this on demand when they need to load a capability into context.
Parameters
| Field | Type | Required |
|---|---|---|
key | string | Yes |
Returns
{ "role": "core", "capability": "...prompt text..." }Returns capability: null if no prompt is linked.
Example
pm_capability {
action: "prompt",
key: "review.quality-gate"
}This is how agents load capabilities on demand without inflating their base system prompt. Hot-load the capability, use it, move on.
help
Return the structured action reference from the running MCP server.
pm_capability { action: "help" }The help payload is a read-only contract for capability registry automation:
| Field | Contents |
|---|---|
actions | Every accepted pm_capability action: create, get, list, update, delete, ensure, prompt, and help |
whenToUse | Action-by-action guidance for registry lookup, idempotent synchronization, mutation, deletion, and runtime prompt hot-loading |
examples | Representative calls such as listing workflow capabilities, ensuring a capability key, and hot-loading a capability prompt |
cautions | Guardrails for missing linked prompts, using ensure for repeatable sync, and treating promptId as a prompt record ID |
compatibility | Notes that structured help is additive and does not change existing inputs, action names, validation, or non-help result shapes |
Use help when building pack importers, agent launchers, or docs that need to reflect the current capability surface. Because the structured help schema is additive, older clients can ignore it while newer agents use it to choose ensure versus create and prompt versus get.
Related
- pm_agent — agents are bound to capabilities
- pm_prompt — capabilities link to prompts for their content
- Valdr Packs — how capabilities are authored and shipped