Hub Runtime

The current AgentStack runtime is not just a YAML parser. It also maintains a local hub under ~/.agentstack/.

Current layout

~/.agentstack/
  profiles/
    <name>/
      agentstack.yaml
  active-profile -> ~/.agentstack/profiles/<name>
  skills/
    agentstack-core/SKILL.md
    <mcp-id>/SKILL.md

What `profile activate` does

When you run:

agentstack profile activate <name>

the current implementation does all of this:

validates that the target profile exists
updates the active-profile symlink
parses the canonical profile
generates a core hub skill
generates one MCP companion SKILL.md per MCP
detects supported tool skill directories
creates managed symlinks from tool dirs back into ~/.agentstack/skills/
warns about missing env refs required by MCPs

Managed symlinks

AgentStack keeps a .managed-symlinks manifest so it knows which symlinks it owns and can safely clean up later.

That lets the runtime avoid deleting user-managed files accidentally.

Current provider activation coverage

The current hub activation path is wired for:

codex
claude
opencode

Gemini is not yet integrated at the same level in the hub activation/doctor path.

What `profile deactivate` does

agentstack profile deactivate

Today this removes the active-profile symlink and can optionally restore backups when the command is used with restore-backup behavior.

What the hub does not do yet

The current hub runtime does not yet mean complete provider convergence.

In particular:

it does not make every provider consume the exact same instruction-file format
it does not make apply and activate the same thing
it does not yet treat a full repo/folder package as the canonical unit everywhere