---
name: plungeai-skills-plugins
description: "Declare and understand PlungeAI's capability-injection fields on a type: harness task or plungeai_run_mission — skills, experts, persona, backgrounds, plugins, and MCP servers — including eager-vs-deferred budgets and degrade-to-warning failure semantics. Use when the user wants an agent to follow a house style or method, adopt an identity/voice, get standing company context, or wire in a domain toolkit or MCP server. For authoring the mission itself use `plungeai-missions`; for saving a skill from this chat use `plungeai-memory`'s plungeai_learn."
---

# PlungeAI Skills, Experts, Personas, Backgrounds, Plugins, MCP

Six capability kinds shape a `type: harness` task (or `plungeai_run_mission`) beyond
its goal: **skills** (methods — HOW), **experts** and **personas** (identity —
WHO), **backgrounds** (ambient truth), **plugins** (bundled domain toolkits), and
**mcp** (connected servers). All six are resolved by one enrichment pass at run
start.

## Prerequisites

- A self-service `ozk_` API key from **Dashboard → One API → Keys**
  (https://dashboard.plungeai.com), or an MCP client connected to
  `https://mcp.plungeai.com/v1`.
- **Discover every id before declaring it** — a missing id never fails the run, it
  degrades to a silent warning: `plungeai_list_agents {kind: "skills"|"experts"|
  "personas"|"connectors", search: "<topic>"}` (REST: `GET
  /v1/discovery/search?kind=…&q=…`). Never guess.

## Declaring capabilities

```yaml
- type: harness
  goal: "Build a valuation snapshot for {input}"
  mission: |
    You are a buy-side analyst.
  persona: analyst
  experts: [securities-law]
  skills: [dcf-modeling-method]
  backgrounds: [acme-corp]
  plugins: [finance-bundle]
  mcp: [daloopa]
```

Injection order into the system prompt is fixed: `BACKGROUND` (verbatim, first) →
persona text → `EXPERT` sections → skill bodies under `ADDITIONAL INSTRUCTIONS` →
free-text `instructions:` (always appended, last word).

## The eager budget — the thing that trips people up

All eager identity/instruction text shares **one 24 KB budget**: at most 3
backgrounds, 1 persona, 3 experts, 5 skills load eagerly; the rest **defer** to an
`## AVAILABLE ON DEMAND` index the agent can pull mid-run with `load_skill`. Order
your lists by importance — must-follow items go first or into `instructions:`
(which always lands, never defers). A plugin's bundled skills are always indexed,
never eagerly injected, regardless of count — see `references/plugins.md`.

## Which to declare

| You have | Declare |
|---|---|
| One instruction pack (method, house style) | `skills: [id]` |
| An identity/voice for the whole run | `persona: id` (exactly one) |
| A domain judgment lens | `experts: [id]` (up to 3 eager) |
| Standing company/product context for every run in a family | `backgrounds: [id]` |
| A coherent toolkit (several skills + scripts, versioned together) | `plugins: [id]` |
| One MCP server the agent should call directly | `mcp: [server-id]` — plugins never add this for you |

Do not unbundle a plugin into individual `skills:` entries to force eager injection
— you lose its script index and blow the shared budget. A plugin's `.mcp.json` /
manifest `mcpServers` documents the connectors its skills were written for; it is
NOT auto-connected — declare that server's id yourself in `mcp:` alongside the
plugin (`references/plugins.md`).

## Gotchas

- Arrays REPLACE, never union, across mission-card merge (last wins: card →
  workflow root → task) — a task-level `experts: [x]` replaces the card's whole
  list.
- Only the FIRST entry of `personas: [x]` (plural) is used — you never get a blend.
- Missing/bad ids degrade to a warning, never a hard failure — a run that "lost its
  voice" or ignored a skill almost always has one in its warnings
  (`plungeai-results-traces`).
- A plugin declaration never fails the run even if it can't be expanded — a bad id
  degrades to a warning and the plugin's skills/scripts are simply absent.

## Related skills

- `plungeai-missions` — the harness task these fields attach to, and the merge
  order (card → workflow root → task).
- `plungeai-memory` — `plungeai_learn` distills a chat session into a new skill.
- `plungeai-results-traces` — where a degraded-capability warning shows up.
- `plungeai-tools-connectors` — MCP server ids for the `mcp:` field.

## Reference

- `references/skills.md` — declaring/creating skills, the eager budget, debugging.
- `references/plugins.md` — plugin expansion (skill index, MCP servers, script
  index), failure semantics.
- `references/experts-personas.md` — backgrounds, persona, experts: injection
  order, budgets, merge behavior.