Core Concepts

Think about AgentStack in three layers.

1. Canonical manifest

The canonical source inside AgentStack is the profile manifest stored at:

~/.agentstack/profiles/<name>/agentstack.yaml

Current code supports:

legacy-compatible v3 projection for existing runtime consumers
staged v4 parsing for package-first evolution

2. Hub runtime

The hub lives under ~/.agentstack/.

agentstack profile activate <name> currently:

switches active-profile
generates hub SKILL.md files
materializes local package skills into the hub skill store
creates managed symlinks into provider skill dirs

3. Provider materialization

agentstack apply --to <provider> currently:

writes native provider config files
writes enabled local package skills into provider skill directories

Current schema reality

The current runtime still exposes a v3-style nested compatibility view through parseCanonicalProfile(), while the parser also understands the staged package-first v4 manifest.

That is how AgentStack is evolving without breaking the existing runtime all at once.

Direction: profile packages

The target model is a profile directory/repo where agentstack.yaml is the manifest and long-form assets live as files next to it.

See: