Agents¶

The @agents block defines specialized AI workers as a core part of project configuration. Each agent can own a role, prompt, model, tool policy, skill set, and MCP access.

@meta {
  id: "agent-team"
  syntax: "1.4.0"
}

@agents {
  code-reviewer: {
    description: "Review changed code before merge"
    tools: ["Read", "Grep", "Glob", "Bash"]
    model: "sonnet"
    skills: ["security-review"]
    mcpServers: ["issue-tracker"]
    content: """
      Review the current diff.
      Report correctness, security, and contract issues with file references.
    """
  }

  debugger: {
    description: "Investigate failing tests and runtime errors"
    tools: ["Read", "Edit", "Bash", "Grep"]
    permissionMode: "acceptEdits"
    content: "Find root cause, implement the smallest fix, and run focused validation."
  }
}

Imported Agents and Namespaces¶

An aliased @use qualifies every imported agent with the alias. This lets multiple fragments define the same local agent name without overwriting one another:

@use ./frontend-team as frontend
@use ./backend-team as backend

If both fragments define reviewer, the resolved names are frontend.reviewer and backend.reviewer. An unaliased import keeps its original name when that name is unique:

@use ./shared-reviewer

The resulting agent remains reviewer. If an unaliased import conflicts with a local or another imported definition, compilation stops with a diagnostic that lists every source, import path, namespace, and the recommended alias or rename action. Definitions are never silently overwritten.

Inheritance applies the same rule: a child cannot redefine a parent agent with different content. Identical definitions are allowed.

Qualified names are mapped consistently for native output. Dots become hyphens, so frontend.reviewer becomes frontend-reviewer in filenames and native identifiers. If two qualified names map to the same native name, a deterministic numeric suffix keeps the output collision-free. Resolved programs expose this information through agentProvenance.

Nested aliases retain the full namespace. If team.prs imports inner-team.prs as inner, then an outer import as frontend resolves the inner team's reviewer agent to frontend.inner.reviewer:

# team.prs
@use ./inner-team as inner

# project.prs
@use ./team as frontend

Known agent references are rewritten with the same namespace. For example, an imported definition that contains agent: "reviewer" or a handoff entry targeting "reviewer" points to frontend.inner.reviewer after resolution. Native output then uses frontend-inner-reviewer consistently for both the agent file and handoff target.

Agent Properties¶

Validators check supported enum values and forbidden fields before formatters generate output. Target-specific fields are emitted only where the native agent format supports them.

Native Output¶

Targets with native agent systems receive dedicated files. Common examples:

Targets without a native agent contract still receive project instructions through their primary output. Check Target Platforms before depending on target-specific fields.

Agents and Skills¶

Agents reference reusable skills by name:

@skills {
  database-safety: {
    description: "Database change safety checks"
    content: "Review migrations, rollback behavior, locking, and data preservation."
  }
}

@agents {
  migration-reviewer: {
    description: "Review database migrations"
    skills: ["database-safety"]
    content: "Review proposed migrations before deployment."
  }
}

This separates reusable knowledge from agent orchestration. Multiple agents can use the same skill, and formatters choose the target-native representation.

Agents and MCP Servers¶

Define project MCP servers once, then reference them from agents:

@mcpServers {
  issue-tracker: {
    transport: "stdio"
    command: ["node", "./tools/issues.mjs"]
  }
}

@agents {
  product-owner: {
    description: "Validate work against product requirements"
    mcpServers: ["issue-tracker"]
    content: "Read active requirements and verify acceptance criteria."
  }
}

Agent-level MCP references only apply to targets whose native agent format supports them. Other targets continue using project-level MCP configuration.

Target Versions¶

Native agent files normally require a target's richest output mode:

id: native-agents-project
syntax: '1.4.0'

targets:
  - github:
      version: full
  - claude:
      version: full
  - cursor:
      version: full
  - factory:
      version: full
  - codex:
      version: full

Design Guidelines¶

• Give every agent one clear responsibility.
• Keep reusable domain instructions in @skills.
• Grant only required tools and MCP servers.
• Use disallowedTools, sandbox options, and permission modes where supported.
• Keep agent content platform-neutral unless the role is intentionally target-specific.
• Validate compiled output for every target used in CI.

Related Documentation¶

• Language Reference: @agents
• Agents Example
• Skills and Resources
• MCP and Plugins
• Supported Formatters