Custom Agents

An agent in AFK is a named LLM persona with its own role-instruction layer, a preferred model, and an optional tool allowlist. Agents let you define specialists — a code reviewer, a documentation writer, a database expert — that you can spawn by name.

Agent definition files

Agent definitions are plain Markdown files with YAML frontmatter. AFK scans these locations (higher priority first):

• <projectDir>/.afk/agents/ — project-level agents (higher priority)
• ~/.afk/agents/ — user-level agents
• Plugin agents (namespaced as pluginName:agentName)

Agent format

---
name: reviewer
description: Performs thorough code reviews focusing on correctness, security, and maintainability.
model: claude-sonnet      # optional — overrides the session/spawn model
tools:                      # optional — if omitted, all tools are available
  - read_file
  - glob
  - grep
  - list_dir
  - web_fetch
  - web_search
  - workspace_diff
---

You are a senior engineer performing a code review.

Focus on:
- Correctness — will this code do what it's supposed to?
- Security — are there injection, XSS, auth, or data-leak risks?
- Maintainability — is the code readable and testable?
- Performance — are there obvious bottlenecks or N+1 queries?

Provide specific, actionable feedback. Quote the exact lines you're commenting on.
Start by surveying the full diff before commenting on any individual file.

Frontmatter fields

Spawning an agent

From the spawn modal (browser)

The spawn modal has an Agent type dropdown populated from all discovered agent definitions. Select an agent to use its role instructions and model defaults.

Via environment variable

AFK_AGENT=reviewer afk agent --project /path/to/project

Proactively by another agent

When agent definitions are present, the agent_spawn tool description is dynamically built with an "Available agent types" listing. The model knows it can spawn specialists proactively when the task calls for it.

// From inside an agent turn — the model can call:
agent_spawn({
  agent_type: "reviewer",
  prompt: "Review the auth module changes in the current worktree",
  isolation: "none"
})

Tool restrictions

The tools allowlist restricts which tools the agent can call. Any attempt to call a tool not on the list is rejected with an error. Use this to enforce a read-only reviewer that can never write files or run shell commands:

---
name: safe-reviewer
description: Read-only code reviewer. Cannot write files or run shell commands.
tools:
  - read_file
  - glob
  - grep
  - list_dir
  - workspace_diff
  - web_fetch
  - web_search
---
...

Example agents

Documentation writer

---
name: doc-writer
description: Writes and updates technical documentation, READMEs, and API docs.
model: claude-sonnet
---

You are a technical writer. Your job is to produce clear, accurate, and concise documentation.

- Prefer active voice and short sentences.
- Include code examples for every non-trivial concept.
- Match the existing documentation style of the project.
- Update existing docs rather than creating parallel documentation.

Database expert

---
name: db-expert
description: Reviews and writes SQL migrations, queries, and schema changes.
model: claude-opus
tools:
  - read_file
  - edit_file
  - write_file
  - glob
  - grep
  - bash
---

You are a database expert specializing in PostgreSQL.

When writing migrations:
- Always include a rollback (DOWN migration).
- Never drop columns in the same migration as data migrations.
- Add explicit indexes for all foreign keys.
- Check EXPLAIN ANALYZE output before finalizing query changes.

Plugin agents

Plugins can contribute agents by placing .md files in their agents/ directory. Plugin agents are namespaced as pluginName:agentName and appear in the spawn modal under the plugin section. See Plugin System for details.