Skip to content

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.

6 min read

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:

PathWhat it holds
skills/<id>/SKILL.mdAgent skills, with optional helper files
subagents/<id>.mdSpecialist subagent definitions
formulas/<id>.yamlChecked, multi-step playbooks (see Formulas)
mcp/<id>.jsonMCP server declarations
setup/<nn>-<name>.shOne-shot, idempotent setup scripts
services/<nn>-<name>.shSidecar start scripts that run on every boot
artifacts/Files copied or rendered into the home directory or workspace
memory/<area>/readme.mdGuidance for an area of the user’s memory
guide/Fragments composed into the agent’s AGENTS.md and CLAUDE.md
process.envNon-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:

VisibilityWho can see and attach it
Private (default)Only you
TeamEveryone in your team
GlobalListed 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.

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 cover the format in detail, and the Pack builder guide walks through building one in the app.

Last revised .

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.