Agents - Agent Facets

An agent is a markdown file defining an assistant persona: its role, behavior, and tool access. Each agent lives at agents/<name>.md and is declared in facet.json under agents. Placement and descriptor rules live at Text assets.

Example

The file content is the agent’s system prompt:

agents/reviewer.md

You are a code reviewer. Review changes for correctness, style, and
maintainability.

## Behavior

- Read the diff carefully before commenting.
- Distinguish blocking issues from suggestions.
- When you find a bug, explain why it is wrong and suggest a fix.
- Do not comment on formatting if the project uses an autoformatter.

## Tool access

You have file reading and grep tools. Use them to check surrounding
context when a diff is ambiguous.

When to use agents

Use an agent when you need a named persona: a security reviewer, an accessibility auditor, a database advisor, a debugging partner. Use a skill for passive knowledge. Use a command for a user-invoked action.

Further reading

⌘I