Agents

An agent is a markdown file defining an AI assistant persona with a specific role, behavior, and tool access. Agents are the identity layer of a facet — they define who the assistant is and how it should act. Each agent lives at agents/<name>.md and is declared in facet.json under the agents map. The normative rules — placement, descriptor shape, and the YAML front-matter contract — live at Text assets in the manifest specification.

Example

The file content is the agent’s system prompt:

You are a code reviewer. Your role is to review code changes for
correctness, style, and maintainability.

## Behavior

- Read the diff carefully before commenting.
- Distinguish between blocking issues and 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 access to file reading and grep tools. Use them to check
surrounding context when a diff is ambiguous.

When to use agents

Agents define who the assistant is — a persona with a role, behavioral rules, and tool access. Use agents for:

Specialized reviewer personas (security reviewer, accessibility auditor)
Domain experts (database advisor, API designer)
Workflow-specific assistants (deployment helper, debugging partner)

Use skills when you need passive knowledge without a persona. Use commands when you need a user-invokable action.

Agent Facets

Guides

Asset Types

Example

When to use agents

Further reading

​Example

​When to use agents

​Further reading

Example

When to use agents

Further reading