> ## 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.

# plungeai-skills-plugins

> 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, how to look the ids up over REST (`GET…


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, how to look the ids up over REST (`GET /v1/discovery/search?kind=…`), and how to save your own skill (`POST /v1/skills/learn`). 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.

[Download zip](https://skills.plungeai.com/plungeai-skills-plugins.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-skills-plugins/SKILL.md)

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
  agent: one-agent
  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`](/skills/plungeai-skills-plugins/references/plugins).

## 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`](/skills/plungeai-skills-plugins/references/plugins)).

## Over the One API

A `type: harness` task rides the workflows plane; the One API has no separate capability route. Same `ozk_` key
(`plungeai-api-setup`).

| Job | REST | MCP | CLI `ocean-cli …` |
|---|---|---|---|
| find an id | `GET /v1/discovery/search?kind=skills\|experts\|personas\|backgrounds\|plugins\|connectors\|mcp-servers&q=` | `plungeai_list_agents {kind, search}` (kinds: `skills`, `experts`, `personas`, `connectors`, …) | `discovery search Q --kind skills` |
| read a card | `GET /v1/discovery/cards/{type}/{id}` (`skill`, `expert`, `digital_twin`, `background`, `plugin`, `mcp_server`, `connector`) | `plungeai_list_agents {agent_id}` | `discovery card TYPE ID` |
| declare them | a `type: harness` task in `POST /v1/workflows/execute`, in a `workflow:` on `POST /v1/execute`, or saved (`POST /v1/workflows`, `kind: agent`) | `plungeai_execute_workflow`; `plungeai_run_mission` takes only `persona` and `skills` | `missions run --persona --skills`; the rest in a workflow YAML |
| your own skills | `GET /v1/skills` → `{skills: [{id, description}], count}`; `POST /v1/skills/learn {name, body, description?}` → `201`; `DELETE /v1/skills/{id}` → `204` | `plungeai_learn` `list` / `learn` / `forget` | `learn list` / `add` / `forget` |

What builders get wrong:

- **`POST /v1/agents/{id}/execute` forwards only `persona`.** `skills`, `experts`, `backgrounds`, `plugins` and `mcp`
  sent there are ignored without an error: use a `type: harness` task for them.
- **`GET /v1/skills` lists only the skills you saved.** Platform skills, experts, personas and plugins come from
  discovery; a saved skill is injected like any other with `skills: [<name>]`. `POST /v1/skills/learn` stores the
  markdown you send (`409 skill_name_taken` for a platform skill's name) — distilling a source into a skill is
  `plungeai_learn`.
- Discovery kinds `personas` and `digital-twins` both return persona cards; `mcp-servers` and `connectors` list the
  servers a mission's `mcp:` can name. An MCP server that needs a credential the user has not connected answers a
  structured `needs_connection:<provider>` inside the run, not a failed request.

## 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`](/skills/plungeai-skills-plugins/references/skills) — declaring/creating skills, the eager budget, debugging.
- [`references/plugins.md`](/skills/plungeai-skills-plugins/references/plugins) — plugin expansion (skill index, MCP servers, script
  index), failure semantics.
- [`references/experts-personas.md`](/skills/plungeai-skills-plugins/references/experts-personas) — backgrounds, persona, experts: injection
  order, budgets, merge behavior.

## Reference pages

<CardGroup cols={2}>
<Card title="Experts, personas, backgrounds — shaping WHO the agent is in a run" icon="file-text" href="/skills/plungeai-skills-plugins/references/experts-personas">
Three capability kinds shape an agent's identity and framing (as opposed to skills, which shape its methods).
</Card>
<Card title="Plugins — bundles of skills, MCP servers, and scripts injected as one unit" icon="file-text" href="/skills/plungeai-skills-plugins/references/plugins">
A plugin is a Claude-Code-format bundle stored on the platform: a directory tree containing any number of SKILL.md skills, an optional .mcp.json (or manifest…
</Card>
<Card title="Skills — injectable instruction packs for agent runs" icon="file-text" href="/skills/plungeai-skills-plugins/references/skills">
A skill is a markdown instruction pack (the Agent Skills SKILL.md format: frontmatter name + description, then the body) stored on the platform and injected…
</Card>
</CardGroup>