Profile Packages

This page describes the intended direction of AgentStack, not the fully completed implementation.

Why move beyond one YAML file?

A single manifest works well as an index, but it is not a great long-term home for:

long-form instructions
provider-specific instruction files
large skills collections
custom MCP wrappers/scripts
env examples
docs, assets, and smoke tests

If all of that stays inline forever, the manifest either becomes too large or too vague.

Recommended canonical unit

The recommended long-term canonical unit is a profile package:

a standalone repo, or
a folder inside a monorepo

agentstack.yaml becomes the package manifest.

Target layout

profile/
  agentstack.yaml
  instructions/
    global.md
    codex/AGENTS.md
    claude/CLAUDE.md
    gemini/GEMINI.md
    opencode/SYSTEM.md
  skills/
  agents/
  mcps/
  providers/
  env/
  assets/
  tests/
  docs/

What is true today

Today, current v3 still stores most canonical content inline under profile inside agentstack.yaml.

That means profile packages are currently a product direction and execution plan, not yet the fully shipped default runtime model.

Why this still matters now

Even before v4 lands, the package model is useful because it clarifies the direction of travel:

AgentStack should own the repo/folder, not just one manifest file
instructions should live as files
skills should live as files
provider-specific instruction surfaces should live as files
MCP wrappers should be versioned assets

Recommended use right now

If you are designing team profiles today, treat your profile as if it were already package-first:

keep the manifest small and explicit
store long-form instructions in files next to the profile
store custom skills in versioned Markdown files
store MCP helpers/wrappers in versioned scripts
keep an env/.env.example or equivalent file in the repo