Skip to content
Agent Tool Packager

Terminology

This page defines how Agent Tool Packager (ATP) describes storage areas and workflows. The same words appear in configuration files, CLI messages, and the rest of this manual.

ATP in one sentence

Section titled “ATP in one sentence”

ATP is the atp CLI for building distributable units of agent material (rules, prompts, skills, hooks, MCP servers, commands, similar payloads) and installing them into projects or user-level agent directories.

Station

Section titled “Station”

The Station is your local supply depot for ATP. By default it lives at ~/.atp_station and holds:

  • Station configuration (atp-config.yaml) — including agent-paths: where each supported agent expects files on disk (rules, prompts, skills, hooks, commands, etc.).
  • Package catalog (atp-catalog.yaml) — indices of standard and user packages.
  • Package payloads under standard_packages/ and user_packages/ — each package folder contains atp-package.yaml and a prepared package.tar.gz.

Set STATION_PATH to use a different Station directory (tests, multiple isolated catalogs). The Station also tracks which project Safehouses have registered (atp-safehouse-list.yaml) so ATP can relate projects to the catalog they use.

Safehouse

Section titled “Safehouse”

A Safehouse is the per-project ATP area: a directory .atp_safehouse at the project root (where ATP resolves the project base—usually alongside .git or .vscode, unless you override).

Inside it:

  • manifest.yaml — which catalog packages are installed for this project, with versions, install source, and binary scope metadata.
  • Local Safehouse configuration used when resolving installs.

Mental model: Station = shared infrastructure on the machine; Safehouse = “what this repo has installed right now.”

Catalog

Section titled “Catalog”

The catalog is the single index at the Station (atp-catalog.yaml). It has two lists: standard packages and user packages. If the same name appears in both, the user entry wins for listing and install resolution.

Each entry points at package material on disk (for example file:// paths) or follows Station layout conventions. There is no per-project catalog file—projects always install from the Station catalog.

Package

Section titled “Package”

A package is a versioned unit described by atp-package.yaml in the author’s working directory, later published under the Station’s package folders.

  • Modern: root type: Multi with a parts array; each part has type, usage, optional components and bundles.
  • Legacy: single root type with root-level usage, components, optional bundles, flat stage.tar.

ATP validates and installs both shapes. Staging collects files into stage.tar; publishing gzips it to package.tar.gz next to the manifest copy the installer reads.

Install scopes

Section titled “Install scopes”

When you install, you choose where prompt-like material and binaries go:

  • Project vs Station (user layer) for agent-facing files — flags such as --project and --station.
  • User bin vs project bin for bundle executables — --user-bin vs --project-bin (defaults are documented in the install manual).

Agent

Section titled “Agent”

An agent here is a product id ATP recognises: e.g. cursor, claude, gemini, codex, kiro. The Safehouse stores the selected agent for the project so install places files using the correct paths from agent-paths.

Whole-package lifecycle

Section titled “Whole-package lifecycle”

ATP installs and removes by whole catalog package name. There is no command to uninstall only one part of a multi-part package after install—you remove the entire package and reinstall if needed. (Editing parts is an authoring-time workflow in the package source directory only.)

← Manual index · Site home