docs · manifest reference

`agents.yml`

The single file every pakx project commits. Lists what the project depends on; pakx resolves it across the federated index ( MCP Registry, Smithery, pakx) and writes a deterministic agents.lock next to it.

Top-level shape

name: my-project          # required. anything you want, used for error messages.
version: 1.0.0            # required. semver string for your project.
agents:                   # optional. restrict installation to a subset of agents.
  - claude-code
  - cursor
dependencies:             # optional. omit if the project is empty.
  mcp:
    - ...
  skills:
    - ...
  subagents:
    - ...
  prompts:
    - ...
  commands:
    - ...
  hooks:
    - ...

Dependency kinds

Each kind under dependencies is an array. Three forms are accepted per entry:

dependencies:
  mcp:
    # 1. bare canonical id — resolves against the federated index
    - io.github.bytedance/mcp-server-filesystem

    # 2. id + semver constraint
    - io.github.microsoft/playwright-mcp@^0.5

    # 3. explicit registry pin — bypasses federation
    - registry: official
      name:     io.github.modelcontextprotocol/server-fetch
      version:  ^1.0

The six recognised kinds map 1:1 to the package types the registry accepts: mcp, skills, subagents, prompts, commands, hooks.

Agent targeting

agents is optional. When present, only the listed agents receive installed dependencies. When absent, pakx installs into every detected agent on the machine.

agents:
  - claude-code
  - cursor
  - codex
  - copilot
  - windsurf

pakx doctorshows which agents pakx detected on the current machine; ids in this list that don't resolve to a detected agent are silently skipped.

Lockfile

agents.lock is generated by pakx install. JSON with a stable key order so it diffs cleanly. Commit it.

{
  "lockfileVersion": 1,
  "manifestHash": "sha256-<base64>",
  "entries": {
    "mcp/io.github.bytedance/mcp-server-filesystem@1.0.0": {
      "name":         "io.github.bytedance/mcp-server-filesystem",
      "type":         "mcp",
      "version":      "1.0.0",
      "resolvedFrom": "official-mcp:io.github.bytedance/mcp-server-filesystem",
      "registry":     "official-mcp",
      "integrity":    "sha256-<base64>",
      "agents":       ["claude-code"],
      "dependencies": []
    }
  }
}

integrity is an SRI string (sha256-<base64>) over the resolver-canonical install payload, so future installs of the same lockfile entry detect tampered upstreams.

Minimal example

name: hello-pakx
version: 0.1.0
dependencies:
  mcp:
    - io.github.bytedance/mcp-server-filesystem
    - io.github.microsoft/playwright-mcp

Run pakx install from a directory containing this file and pakx writes a matching .mcp.json for Claude Code (and the equivalent config for every other detected agent) plus an agents.lock.

agents.yml