> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills, plugins & capability injection

> The platform does not ship one agent per behaviour. It ships one agent — one-agent, whose loop mode runs the mission (see Agents plane) — into which capabilities are injected per run. *Capability injection* is the six kinds below: skills, experts, persona, backgrounds, plugins, and MCP servers. …


The platform does not ship one agent per behaviour. It ships **one agent** — `one-agent`, whose
loop mode runs the mission (see [Agents plane](/one-api/agents)) — into which
**capabilities are injected per run**. *Capability injection* is the six kinds below: skills,
experts, persona, backgrounds, plugins, and MCP servers. You declare them on a `type: harness` task
and the loop host resolves them in one parallel pass before the run
(`core/core-base/pack-enrich.ts`). Base URL is `https://api.plungeai.com`; runs use an `ozk_` key
([Authentication](/one-api/authentication)).

## 14.1 The six kinds

| Kind | What it injects | Where it comes from | Eager limit | Field |
|---|---|---|---|---|
| **backgrounds** | always-on ambient context, prepended **first** | registry card `prompt_format` | 3 | `backgrounds: [id, …]` |
| **persona** | identity / voice, prepended | persona-memory | 1 (one voice per run) | `persona: id` (aliases `digital_twin`, `personas[0]`) |
| **experts** | labelled `## EXPERT: <id>` sections | expert-memory | 3 | `experts: [id, …]` |
| **skills** | an `## ADDITIONAL INSTRUCTIONS` body | skill-memory, else the registry skill card | 5 | `skills: [id, …]` |
| **plugins** | a bundled SKILL.md index + script index (never MCP ids) | plugin-memory | — | `plugins: [id, …]` |
| **mcp** | remote MCP tools, connected for the run and exposed under the fence | mcp-executor (secrets resolved server-side) | — | `mcp: [id, …]` |

Injection order into the system prompt: **backgrounds → persona → experts**, then the skill body
under `## ADDITIONAL INSTRUCTIONS`. Plugin **scripts** become available to the `run_python` tool;
plugin **skills** are advertised by name + description and pulled on demand with `load_skill`. MCP
ids are connected by the loop host through the mcp-executor (the same machinery as the
[MCP plane](/one-api/mcp) outbound runs) and their tools appear as `mcp__<server>__<tool>` under the
mission's fence.

## 14.2 Limits & degradation

- **Total eager budget** across backgrounds + persona + experts + skills is `EAGER_BUDGET_BYTES` =
  **24 KiB** (`pack-enrich.ts`). Over budget, later items are **listed by id + description instead of
  injected** — the agent pulls them on demand via `load_skill` (progressive disclosure).
- **Per-kind caps:** `skills` 5, `experts` 3, `backgrounds` 3 (`MAX_EAGER`). Ids beyond the cap are
  deferred to `load_skill` the same way.
- **Fail-soft:** a missing or unresolvable capability degrades to a **warning lane**, it does not
  fail the run. A missing MCP credential surfaces as a structured `needs_connection:<provider>`.
- **Arrays replace, they don't union** — the most specific layer wins per key (14.4).

## 14.3 The skill catalog

Skill sources live in `skills/<id>/SKILL.md`; the runtime injects the published **registry skill
card**. The live catalog is the source of truth — discover it with
`GET /v1/discovery/search?kind=skills` ([Discovery](/one-api/discovery)). Install PlungeAI's own agent
skills from the [skills catalog](https://skills.plungeai.com). The ids on disk today (`skills/`):

| id | one line |
|---|---|
| `web-search` | search the web and cite sources |
| `report` | structure findings into a clean report |
| `refactor` | refactor code toward a smaller, clearer shape |
| `code-review` | review a diff for correctness and simplification |
| `debug` | systematic root-cause debugging |
| `file-ops` | read/write/search files in the workspace |
| `prd` | draft a product requirements document |
| `qa` | test-and-verify discipline |
| `thinking` | structured reasoning before acting |
| `workflow` | author a CNL workflow |
| `biotech` | biotech-domain research helper |

```bash
curl -s "https://api.plungeai.com/v1/discovery/search?kind=skills&q=web-search&limit=5" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"
```

**Plugins** are bundled SKILL.md indexes + runnable scripts (not MCP servers). Discover them with
`kind=plugins`; **MCP servers** (the `mcp:` kind) with `kind=mcp-servers`:

```bash
curl -s "https://api.plungeai.com/v1/discovery/search?kind=mcp-servers&limit=5" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"
```

> The discovery kinds `personas` and `experts` return cards (live-verified 2026-10-05: 20 of each on
> a first page of `GET /api/registry/search?kind=personas&q=assistant`, same for `kind=experts`;
> persona cards have `type: digital_twin`). The card is the catalog entry; persona/expert text is
> still resolved from the persona-memory / expert-memory services at run time.

## 14.4 Pre-built agent cards — `mission_ref` / `pack`

A **pre-built agent** is a registry `agent` card whose `prompt_format` holds one portable markdown
document: YAML frontmatter (a typed capability pack) plus a body that *is* the system prompt,
compiled on read by `core/core-base/agent-markdown.ts`. Reference it instead of writing the mission
inline:

```yaml
- type: harness
  agent: one-agent
  mission_ref: research-analyst      # canonical; `pack:` is an alias; a single-token `mission:` also works
```

Frontmatter keys the compiler reads: `name`, `description`, `model`, `effort`, `tools`, `skills`,
`experts`, `persona`, `backgrounds`, `plugins`, `mcp`, `agents` (named sub-agents), `permissions`,
`success_criteria` — plus the body. Unknown keys are ignored with a warning (forward-compatible);
ownership/visibility are stamped server-side, never read from frontmatter. **Merge order (per key,
last wins): pre-built card → workflow root → task**; arrays replace. So a card can define the base
mission and the task can override `model` or clear `skills: []`.

## 14.5 How to run it

**Workflows plane (recommended)** — a `type: harness` task carries the mission and its capability
fields; run it inline or save it (see [Workflows plane](/one-api/workflows)). A full example:

```yaml
workflow:
  name: sourced-brief
  tasks:
    - type: harness
      id: brief
      agent: one-agent
      goal: "Write a one-paragraph brief on the latest Anthropic model; every claim a source URL."
      mission: "You are a research analyst. Produce sourced, factual briefs."
      allowed_tools: [web_search, web_fetch, task_complete]
      success_criteria:
        - "Every factual claim is followed by a source URL."
      max_iterations: 8
      skills: [web-search, report]
      experts: [python-pro]
      persona: analyst
      backgrounds: [acme-corp]
      plugins: [finance-bundle]
      mcp: [brave-search]
```

`allowed_tools` is the fence (fail-closed — a tool not listed never executes); `max_iterations`
(alias `max_turns`) is the loop cap; `effort` (`quick`/`standard`/`deep`) sets a default cap when no
explicit number is given.

**Agents plane** — `POST /v1/agents/:id/execute` forwards **only `persona`** among the capability
fields (`routes/agents.ts`); `skills`, `experts`, `backgrounds`, `plugins`, `mcp`, `goal`,
`allowed_tools` are **ignored** there. To inject skills/plugins/MCP, use the `type: harness` task on
the workflows plane, or the [MCP plane](/one-api/mcp) `plungeai_run_mission`.

A minimal harness run with a real skill injected, capped at 2 iterations:

```bash
curl -s "https://api.plungeai.com/v1/workflows/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"workflow":{"name":"cap-demo","tasks":[{"type":"harness","id":"h1","agent":"one-agent","goal":"Reply with the single word pong, then call task_complete.","mission":"You are a terse assistant. Answer in one word.","allowed_tools":["task_complete"],"max_iterations":2,"skills":["report"]}]}}'
```

## 14.6 Seeing what was injected

The enrichment pass reports what it resolved and what degraded (`pack-enrich.ts`): capabilities that
could not be resolved appear as **warning lanes**, and those dropped for the eager budget/cap are
reported as **deferred** (loadable with `load_skill`). These surface in the run's result metadata and
in the trace spans ([Traces & observability](/one-api/traces-observability)); a missing skill shows up as
a warning rather than silently absent behaviour. For the full runtime model — tool fence, memory,
delegation, recursion guard — see `orchestration/HARNESS-README.md`.