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

14.1 The six kinds

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 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). Install PlungeAI's own agent skills from the skills catalog (opens in a new tab). The ids on disk today (skills/):

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:

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:

- 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). A full example:

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

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

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); 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.