Authoring Profile Assets

This guide is intentionally split between current reality and recommended direction.

Current reality

Today, the canonical v3 schema stores most portable data inline inside agentstack.yaml.

That means:

• instructions.global is inline text
• instructions.project_overrides is an array of strings
• skills are references with id, source, path, enabled
• agents are not yet first-class in the canonical schema
• MCP definitions live in profile.mcp_servers

Recommended authoring model

Even before package-first v4 lands, author your profile as if it were a small package:

profile/
  agentstack.yaml
  instructions/
  skills/
  agents/
  mcps/
  env/

This keeps the content reviewable and makes the future migration much easier.

Instructions

Today

Current v3 supports:

• profile.instructions.global
• profile.instructions.project_overrides

Recommended practice

• keep the source text in versioned files under instructions/
• copy or derive the canonical global text from those files
• treat project_overrides as references to project-local instruction sources

Note

Current v3 does not yet provide a first-class file reference model for instructions. The package-first direction exists because inline-only instructions are too limiting long term.

Skills

Current v3 skill entries look like this:

skills:
  - id: core-review
    source: local
    path: ./skills/core-review.md
    enabled: true

Recommended practice:

• store local skills under skills/
• keep one skill per file
• use stable ids
• prefer small, composable skills over giant prompt blobs

Agents

agents are part of the product direction, but not yet part of the current v3 canonical schema.

If you already need agent-specific prompt files today:

• store them under agents/
• version them like any other asset
• treat them as design-time assets until v4 adds first-class schema support

MCP wrappers

MCP servers in v3 are declared inside profile.mcp_servers, but wrapper scripts themselves should live as normal files.

Recommended pattern:

mcps/
  github-wrapper.ts
  postgres-wrapper.ts

Then keep the canonical MCP entry focused on wiring:

mcp_servers:
  - id: github
    transport: stdio
    command: node
    args:
      - mcps/github-wrapper.ts
    env_refs:
      - GITHUB_TOKEN
    enabled: true

Caution

Current runtime behavior around relative file paths still depends on the execution flow you use. Keep wrapper paths stable and easy to resolve.

Env references

Do not inline secrets into the manifest.

Use env_refs in MCP entries and keep example values in versioned files such as:

env/
  .env.example
  secrets.schema.yaml

Authoring checklist

• keep manifest small
• move long text into files
• give skills stable ids
• keep MCP wrappers versioned with the profile
• avoid provider-only prompt files unless you document why
• document which parts are current runtime inputs vs future package assets