> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfacets.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Portable agent definitions

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](/specification/manifest#text-assets) in the manifest specification.

## Example

The file content is the agent's system prompt:

```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/learn/skills) when you need passive knowledge without a persona. Use [commands](/docs/learn/commands) when you need a user-invokable action.

## Further reading

* [Text assets](/specification/manifest#text-assets) -- placement, descriptor shape, and front-matter rules
* [Create Your First Facet](/guides/create-your-first-facet) -- step-by-step guide including writing an agent