# pm_capability
{{< badge content="Vanguard" color="blue" class="tier-badge" >}}

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

```text
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

```text
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

```json
{ "role": "core", "capability": "...prompt text..." }
```

Returns `capability: null` if no prompt is linked.

### Example

```text
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

```text
pm_capability { action: "help" }
```

## Related

- [pm_agent](../agents/) — agents are bound to capabilities
- [pm_prompt](../prompts/) — capabilities link to prompts for their content
- [Valdr Packs](/valdr/docs/valdr-packs/) — how capabilities are authored and shipped