# Packs: portable, verified capabilities for coding agents

> How Nested packages skills, subagents, formulas, and MCP servers into versioned packs, verifies them as untrusted input, and loads them into agents.

Published: 2026-09-16 · Updated: 2026-11-19 · Topics: Agents, Product · Canonical: https://nested.me/blog/packs-portable-agent-capabilities

## A capability is more than a prompt

When a team gets good results from a coding agent, the result usually depends on a pile of small things: a skill that explains how to run the test suite, a subagent tuned for code review, an MCP server that talks to the issue tracker, a setup script that installs the right CLI, a few paragraphs in `AGENTS.md` about house rules. Copy that pile by hand to the next agent and something always goes missing.

A **pack** is our answer: one versioned archive that carries all of it, gets verified before anything trusts it, and loads into an agent the same way every time.

## What is in a pack

A pack is a `.tar.gz` (or a source directory) with a `PACK.yaml` manifest at its root. Everything else lives in a fixed layout:

| Path | What it holds |
| --- | --- |
| `skills/<id>/SKILL.md` | Agent skills, with optional helper files |
| `subagents/<id>.md` | Specialist subagent definitions |
| `formulas/<id>.yaml` | Checked, multi-step playbooks (see [Formulas](https://nested.me/blog/formulas-checked-playbooks)) |
| `mcp/<id>.json` | MCP server declarations |
| `setup/<nn>-<name>.sh` | One-shot, idempotent setup scripts |
| `services/<nn>-<name>.sh` | Sidecar start scripts that run on every boot |
| `artifacts/` | Files copied or rendered into the home directory or workspace |
| `memory/<area>/readme.md` | Guidance for an area of the user’s memory |
| `guide/` | Fragments composed into the agent’s `AGENTS.md` and `CLAUDE.md` |
| `process.env` | Non-secret `KEY=VALUE` defaults |

Any other file at the root fails verification. A strict layout sounds fussy, but it means a reviewer can open any pack and know where to look.

Nested ships first-party packs for common roles and tools — a builder, a documenter, a debugger, and packs for Docker, Kubernetes, Ollama, n8n, and WireGuard. One pack, `nested-core`, is special: it is compiled into the agent binary and carries the platform’s own skills, so it never needs to be uploaded.

## Why packs are files, not code

Instructions, playbooks, and bootstrap scripts change much faster than the Go code that runs agents. If every new skill needed a platform release, nobody would write skills. So packs hold the Markdown, YAML, and shell, and the platform only does three things with them: verify, store, and load.

## Verification treats every pack as untrusted

A pack can come from anyone on your team, or from another team’s catalog entry. So verification is static, assumes the worst, and runs three times: when you build, when you upload, and again inside the agent before loading.

The checks include:

- The manifest schema, with unknown fields rejected rather than ignored.
- The layout allowlist, and a one-to-one match between what the manifest declares and what is on disk.
- No symlinks, no hard links, and no `..` paths in archives. Archive bombs are stopped by size caps: 100 MiB compressed and 200 MiB extracted.
- No embedded secrets. A literal token in an MCP declaration fails with `PACK_EMBEDDED_SECRET`, and `process.env` may not contain tokens or private keys.
- No platform placeholders in uploaded MCP declarations, so a pack cannot ask for another task’s token.
- Every formula compiles.

Secrets never travel inside a pack. Instead a pack declares the environment keys it needs and refers to them with `${VAR}` placeholders. When you deploy an agent, you bind your own secrets to those keys, and the agent receives them as a credential overlay. That is why the deploy wizard can ask exactly for the secrets your packs declared.

## Upload, revisions, and the catalog

On upload, the server verifies the archive again with its own limits and computes a SHA-256 content hash. If the content matches the latest revision, it returns that revision and stores nothing new — uploading the same pack twice is a no-op. Otherwise it writes the archive to the object store and commits a new numbered revision.

A pack’s identity is its team plus its name. The account that creates a name owns it; only the owner adds revisions, changes visibility, or deletes it, though team owners and admins can reassign it. Visibility is one of three levels:

| Visibility | Who can see and attach it |
| --- | --- |
| Private (default) | Only you |
| Team | Everyone in your team |
| Global | Listed in the catalog for every team |

The catalog is read-and-copy. To use another team’s pack, you copy its latest revision into your team as a new private pack that you own. Deployments never run another team’s pack directly, so nobody can change what your agents load by publishing a new revision somewhere else.

> [!WARNING]
> “Verified” means the archive passed the static checks above. There is no human review and no code signing for catalog packs today. Read a pack’s setup scripts before you attach it, as you would any shell script.

## How an agent loads its packs

An agent’s settings list the packs it uses, each pinned to a revision (or “latest”) and optionally a content hash. On every start, the agent:

1. Downloads each pack, extracts it safely, and verifies it again.
2. Evaluates each capability’s `when` condition. Conditions can test environment variables, settings, the attached knowledge centers, and the formulas available — for example, `nested-core` loads its formula skill only when `len(Formulas.Items) > 0`. Capabilities whose condition turned false since the last start are removed.
3. Copies skills and formulas, merges MCP servers (expanding `${VAR}` from the bound secrets), and installs subagents for the coding agent to use.
4. Runs setup scripts, skipping any whose version, file, and SHA-256 were already stamped. Then it starts service scripts; a failing service only warns.
5. Applies `process.env` without overwriting anything already set — not even an empty value.
6. Renders guide fragments into a generated section of `AGENTS.md` and `CLAUDE.md`, ordered by priority.

When two packs collide, the later one wins. And when a pack cannot be loaded at all, the agent does not start.

## Fail closed, on purpose

That last rule is the most argued-about decision in the design. An agent that starts without its review pack still looks healthy; it just quietly stops following your review rules. We would rather show a failed start you can fix than a running agent that is missing half of what you configured.

## Building packs without the command line

You can write packs by hand and use `packctl verify` and `packctl build`. Most people use the **Pack builder** in the Nested app instead. It starts from a description, a template, a pack file, or a published pack; imports skills from a git repository; and edits every section, including formulas on a visual canvas. An assistant can propose changes, but only as a reviewable patch — it never publishes or edits the draft until you apply it. When you are done, the builder assembles the archive, verifies it, and uploads it with the visibility you choose.

## Trade-offs we accepted

- **No signing yet.** Revisions are content-addressed and owned, but not signed. Copy-before-use limits the blast radius; it does not replace review.
- **Compatibility is advisory.** A pack can declare the minimum agent version it needs, and the field is validated, but it is not enforced.
- **Later wins.** Pack order matters when two packs define the same thing. We chose a simple rule over a merge language.

## Closing

Packs turn “the way our best agent is set up” into something you can version, review, share, and roll back. The [packs docs](https://nested.me/docs/packs) cover the format in detail, and the [Pack builder guide](https://nested.me/docs/pack-builder) walks through building one in the app.

## Questions

### What is a Nested pack?

A versioned archive with a `PACK.yaml` manifest that bundles skills, subagents, formulas, MCP servers, setup scripts, and guide text, so an agent can load a complete capability in one step.

### Can a pack contain API keys?

No. Verification rejects embedded secrets. A pack declares the environment keys it needs, and you bind your own secrets to them when you deploy the agent.

### What happens if a pack fails to load?

The agent does not start. Nested fails closed so an agent never runs with only part of the capabilities you attached.

### Are catalog packs reviewed or signed?

They pass the same static verification as every pack, but there is no human review or signing today. Copy a pack into your team and read its scripts before you attach it.
