# Packs

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

Section: Platform · Updated: 2026-11-19 · Canonical: https://nested.me/docs/packs

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

| Path | Contents |
|---|---|
| `skills/<id>/SKILL.md` | Skills, with optional helper files |
| `subagents/<id>.md` | Specialist subagent definitions |
| `formulas/<id>.yaml` | Formula documents. See [Formula reference](https://nested.me/docs/formula-reference) |
| `mcp/<id>.json` | MCP server declarations |
| `setup/<nn>-<name>.sh` | One-time, idempotent setup scripts |
| `services/<nn>-<name>.sh` | Sidecar scripts started on every boot |
| `artifacts/` | Files copied or rendered into the home directory or workspace |
| `memory/<area>/readme.md` | Guidance for a memory area |
| `guide/*.md` | Fragments composed into the agent’s `AGENTS.md` / `CLAUDE.md` |
| `process.env` | Non-secret `KEY=VALUE` defaults |
| `README.md`, `LICENSE` | Optional 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](https://nested.me/docs/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.

| Visibility | Who sees it |
|---|---|
| **Private** (default) | Only the owner |
| **Team** | Everyone in the team |
| **Global** | Every 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](https://nested.me/docs/pack-builder), and attach several packs to one agent in [Agent settings](https://nested.me/docs/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.

## Related

- [Pack builder](https://nested.me/docs/pack-builder)
- [Formula reference](https://nested.me/docs/formula-reference)
- [Deploy an agent](https://nested.me/docs/deploy)
- [Secrets](https://nested.me/docs/secrets)
