Skip to content

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."
}
}
Try in Playground

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
Try in Playground

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
Try in Playground

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
Try in Playground

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

PropertyRequiredPurpose
descriptionYesExplains when the platform should invoke the agent
contentNoDefines additional agent instructions
toolsNoAllows platform tools or tool categories
disallowedToolsNoDenies tools on platforms that support deny lists
modelNoSelects a platform model or inherits the parent model
reasoningEffortNoSelects supported reasoning level
specModelNoSelects a separate model for specification work
specReasoningEffortNoSelects reasoning level for specification work
permissionModeNoSelects target-native permission behavior
skillsNoPreloads or references named @skills
mcpServersNoGrants access to named top-level @mcpServers
sandboxModeNoSelects target-native sandbox policy
nicknameCandidatesNoProvides target-native display names
targetsNoOverrides fields for one target, see below

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.

Per-Target Overrides

targets.<target> sets agent fields for one target only. The fields in it replace the shared fields of the same name for that target. Other targets keep the shared fields:

@agents {
builder: {
description: "Build features end to end"
tools: ["Read", "Grep", "Glob", "Create", "Edit", "Execute"]
model: "gpt-5.3-codex"
targets: {
claude: {
tools: ["Read", "Grep", "Glob", "Write", "Edit", "Bash"]
model: "sonnet"
}
}
content: "Implement the change and run the tests."
}
}
Try in Playground

Any agent field can be overridden, for example tools, disallowedTools, model or content. The key is the target name from promptscript.yaml. PS033 reports an unknown target name and a targets value that is not an object of fields.

Tool Names Between Factory and Claude Code

Factory droids and Claude Code subagents name some tools differently. When tools or disallowedTools hold a name of the other tool, the Claude and Grok targets write the Claude Code name and the Factory target writes the Factory name. Duplicates made this way are dropped.

FactoryClaude Code
CreateWrite
ExecuteBash
FetchUrlWebFetch
ApplyPatchEdit
LSGlob

For the Factory target, Write, Bash and WebFetch map back, and Claude Code MultiEdit becomes Edit. ApplyPatch and LS have no own Claude Code tool, so they map only one way. Names that are the same in both tools (Read, Grep, Glob, Edit, WebSearch, TodoWrite, Task) and MCP tool names stay as written. Other targets get tools as before.

A Claude Code subagent can not start other subagents. When a Claude or Grok agent lists Task or Agent in tools, compilation reports PS4003. Set targets.claude.tools without it, or leave the agent out for that target.

Leaving Agents Out of a Target

includeAgents and excludeAgents in the target config choose which agents a target gets, the same way includeSkills does for skills:

targets:
- factory:
version: full
- claude:
version: full
excludeAgents: [orchestrator]

includeAgents: false emits no agents and a list emits only the listed ones. excludeAgents is applied after includeAgents. Both accept the source name (team.reviewer) or the native name (team-reviewer).

Field Support Matrix

Every canonical @agents field has an explicit status per native target. The matrix is machine-readable in @promptscript/core (agent-capabilities.ts) and drives the compiler diagnostics, so the table below cannot drift from what formatters actually emit:

  • emitted - written to the native agent file under the same name
  • transformed - written under a target-native name or representation
  • not supported - the native agent format cannot represent it
FieldGitHubClaudeCursorFactoryCodexOpenCodeAugmentAmpGrok
descriptionemittedemittedemittedemittedemittedemittedemittedemittedemitted
contentemittedemittedemittedemittedtransformedemittedemittedemittedemitted
toolstransformedemitted-emitted----emitted
modeltransformedemittedemittedemittedemitted---emitted
reasoningEffort---emittedtransformed----
specModeltransformed--emitted-----
specReasoningEffort---emitted-----
disallowedTools-emitted------emitted
permissionMode-emitted------emitted
skills-emitted--transformed---emitted
mcpServerstransformedemittedemittedemittedtransformed---emitted
sandboxMode----transformed----
nicknameCandidates----transformed----
handoffsemitted--------
maxTurns-emitted------emitted
memory-emitted------emitted
background-emitted------emitted
isolation-emitted------emitted

GitHub transformation examples: tools maps PromptScript and Claude Code tool names to Copilot aliases (Grep and Glob both become search), and model uses Copilot model names (sonnet becomes the newest Sonnet release, such as Claude Sonnet 5.5). Other targets keep the model field name but also get their native model names, see Models. Codex transformation examples: content becomes developer_instructions, reasoningEffort becomes model_reasoning_effort, and skills becomes the skills.config array.

Every other target has no native agent output: the whole @agents block is omitted and reported with a PS4003 warning instead of being dropped silently. The same diagnostic fires per field when a native target cannot represent authored data (for example tools on Cursor, or skills on GitHub), naming the agent, the field, the target, and which targets do support the field.

Native Output

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

TargetNative output
Claude Code.claude/agents/<name>.md
GitHub Copilot.github/agents/<name>.md
Cursor.cursor/agents/<name>.md
Factory AI.factory/droids/<name>.md
Codex.codex/agents/<name>.toml
OpenCode.opencode/agents/<name>.md
Augment.augment/agents/<name>.md
Amp.agents/agents/<name>.md
Grok Build.claude/agents/<name>.md (delegated to the Claude formatter)

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

Models

model and specModel values resolve against a built-in model catalog, and each target gets the model name it expects. Claude Code keeps floating aliases such as sonnet, GitHub Copilot gets display names such as Claude Sonnet 5, and Factory AI, Codex, and Cursor get model ids. The floating aliases opus, sonnet, haiku, and fable follow the newest release of their family in the catalog. Names the catalog does not know are written unchanged, unless the target spells them its own way: GitHub Copilot writes auto as Auto.

A target that cannot run the model’s provider, such as Codex with a Claude model, omits the field and reports PS4004 during compilation. The same happens to a name with a line break or control character.

PS041 reports agents pinned to deprecated or retired models, with the suggested replacement. When models.supported lists the models your instructions are written and tested for, PS041 also reports agents pinned to other models:

models:
supported: [opus, sonnet, gpt-5.3-codex]

The Model Catalog lists every built-in model, the current release behind each floating alias, and what each target writes. See Configuration: models for adding models that are not in the built-in catalog yet.

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."
}
}
Try in Playground

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."
}
}
Try in Playground

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

Codex also emits agent TOML files in multifile mode. Compiling a version that cannot emit agents reports PS4003 for the whole block instead of dropping it silently.

Agents and Commands as Markdown Files

Agents can also live as markdown files in .promptscript/agents/*.md, and commands in .promptscript/commands/*.md. The frontmatter is read with the same YAML parser as SKILL.md, so folded descriptions and lists work:

---
name: reviewer
description: >-
Reviews one module against its spec.
Produces: a findings list.
tools:
- Read
- Grep
model: inherit
---
Review the module.
  • tools (and disallowedTools) is a YAML list or a comma separated string such as Read, Grep, Bash(git add:*, git commit:*). A single name without commas, like read-only, stays a string. Any other value, for example a mapping or a number in the list, fails the build instead of giving the agent all tools.
  • A value with : inside must be quoted to be valid YAML. Old files that are not valid YAML still load one key: value per line, with a warning. When such a file also has a block list or a folded value, the build fails with the YAML error.
  • Command frontmatter is not copied into the command body. description and argument-hint reach Claude Code and Factory commands, and allowed-tools and model reach Claude Code commands.

Global Installs

output.baseDir (or prs compile --output) can point at a global root such as ${HOME}. To install only generated resources without unrelated root instruction files, select resource kinds:

Terminal window
prs compile --output "$HOME" --resources agents,skills

Valid kinds are agents, skills, commands, mcp, hooks, plugins, and main. Without main, root instruction files such as CLAUDE.md or AGENTS.md are omitted, so a global compile produces only directories like .claude/skills/, .claude/agents/, or .factory/droids/. The same selection can be pinned in config with output.resources.

Global output is guarded: compiling into the home directory without a resource selection prints a warning first, and protected personal override files (~/.factory/AGENTS.md today) are refused outright. Resource-only runs skip managed cleanup so unselected files are never treated as obsolete and deleted; run a full compile to prune stale generated files.

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.