Skip to content
Browse the docs

Packs

The pack format: skills, subagents, formulas, MCP servers, setup scripts, and guides in one verified, versioned archive you attach to agents.

Updated 3 min readView as Markdown

What a pack is#

A pack is a portable .tar.gz archive with a PACK.yaml manifest at its root. It bundles what an agent knows and can do, so the same capability can be versioned, verified, shared, and attached to many agents. Instructions and playbooks live in Markdown, YAML, and shell inside packs; the platform only verifies, loads, and enforces.

What a pack can contain#

PathContents
skills/<id>/SKILL.mdSkills, with optional helper files
subagents/<id>.mdSpecialist subagent definitions
formulas/<id>.yamlFormula documents. See Formula reference
mcp/<id>.jsonMCP server declarations
setup/<nn>-<name>.shOne-time, idempotent setup scripts
services/<nn>-<name>.shSidecar scripts started on every boot
artifacts/Files copied or rendered into the home directory or workspace
memory/<area>/readme.mdGuidance for a memory area
guide/*.mdFragments composed into the agent’s AGENTS.md / CLAUDE.md
process.envNon-secret KEY=VALUE defaults
README.md, LICENSEOptional docs

Any other entry at the root fails verification.

The manifest#

A trimmed manifest from the first-party documenter pack:

yaml
apiVersion: nested.ai/pack/v1
name: standard-documenter
version: 0.2.0
description: >-
  Documents, presentations, spreadsheets, PDFs, and copy.
setup:
  - install-doc-tools.sh
contents:
  skills: [docx, pdf, pptx, xlsx, copywriting]
  subagents: [content-editor, content-presentation-designer]
  formulas: [copy-write, document-create, presentation-create]
  setup: [install-doc-tools.sh]

The name is a DNS-safe slug. version is an optional label.

Secrets stay out of packs#

A pack declares the environment variables it needs under env: and refers to them as placeholders in MCP declarations. It never contains the values. When you deploy an agent, you bind your secrets to those keys, and the agent receives them as a credential overlay.

Conditions#

Every capability can carry a when condition, evaluated when the agent loads its packs. Conditions read environment variables, agent settings, attached knowledge, and the agent’s formulas — for example, load a skill only when len(Formulas.Items) > 0. A capability whose condition turns false disappears on the next restart.

Verification#

Packs are treated as untrusted input. Verification runs on your machine (packctl verify), again on upload, and again when an agent loads the pack. It rejects:

  • Unknown manifest fields, unexpected files, and mismatches between the manifest and the disk.
  • Symlinks, hard links, and .. paths in archives.
  • Archives over 100 MiB compressed or 200 MiB extracted.
  • Literal secrets in MCP declarations, and private keys or tokens in process.env.
  • Formulas that do not compile.

Publishing, revisions, and visibility#

A pack is identified by its team and name. Each upload that changes content becomes a new numbered revision; uploading identical content returns the existing revision. Only the pack’s owner adds revisions, changes visibility, or deletes it; team owners and admins can reassign it.

VisibilityWho sees it
Private (default)Only the owner
TeamEveryone in the team
GlobalEvery team, in the catalog

The catalog is read-only. To use a global pack from another team, Copy to my team — the copy becomes a private pack you own. Agents never run another team’s pack directly. There is no separate review or signing step: a revision exists only if it passed verification.

You can author packs by hand or in the Pack builder, and attach several packs to one agent in Agent settings.

How an agent loads packs#

On every start, the agent:

  1. Downloads each attached pack revision, extracts it safely, and verifies it again.
  2. Copies enabled skills and formulas and merges MCP servers, removing anything whose condition is now false.
  3. Runs setup scripts — skipping ones already run with the same content — then starts service scripts.
  4. Applies process.env, filling only variables that are not already set.
  5. Installs subagents and writes guide fragments into the agent’s instructions.

Later packs win on conflicts. If an attached pack cannot be loaded, the agent does not start, rather than start with missing capabilities.

First-party packs#

Nested ships nested-core built into every agent, plus packs for building software, documentation, debugging, Docker, Kubernetes, Ollama, n8n, and WireGuard.

Questions

Can a pack contain API keys?
No. Verification rejects literal secrets. A pack declares the variables it needs, and you bind secret values per agent when you deploy it.
How do I share a pack with another team?
Set its visibility to Global. It then appears in every team’s catalog, where they copy it into their own team.
What happens if a pack fails to load?
The agent does not start. Nested refuses to run an agent with only part of its declared capabilities.