How to Define Custom Specialist Agents in Intent for Your Team's Workflow

Custom specialist agents in Intent are domain-specific agent definitions that extend Intent's built-in coordinator-implementer-verifier architecture, enabling teams to handle recurring tasks such as security scanning, documentation generation, or code migrations with purpose-built prompts, scoped tool access, and explicit behavioral constraints.

Intent's Coordinator-Implementer-Verifier Architecture

Intent, Augment Code's agentic development environment, organizes work through three roles: a Coordinator that plans, an Implementer that executes, and a Verifier that validates. Understanding this architecture is essential before extending it with custom agents.

The Coordinator analyzes the codebase using Intent's Context Engine, which semantically indexes repositories across 400,000+ files. It drafts a living spec as an evolving document, decomposes the spec into a dependency-ordered directed acyclic graph (DAG), and delegates subtasks to Implementers in parallel batches called waves. Developers can stop the Coordinator at any point to manually edit the spec before agents continue.

Implementers execute subtasks in isolated git worktrees, each with its own dedicated workspace. Multiple Implementers run simultaneously within each wave, and each runs its own reason-act-observe cycle within a scoped context. Intent ships with six built-in specialist personas: Investigate, Implement, Verify, Critique, Debug, and Code Review.

The Verifier checks each output against the living spec, not isolated diffs. The Verifier and Implementers have opposing goals by design: one optimizes for completing the task, the other for finding failures. Together, the Coordinator and Verifier form an outer control loop: plan, execute, verify, then replan.

These two loops operate at different scopes and serve different purposes, summarized below:

Custom specialist agents plug into this system as additional Implementers. The Coordinator can delegate domain-specific subtasks to a custom agent the same way it delegates to built-in personas, and the Verifier validates the output against the same living spec.

When Teams Need Custom Specialists

Custom specialist agents are not required for every workflow. The default trio handles most general-purpose development tasks effectively, including cross-service refactors, feature work with clear decomposition, and codebases where context management is the primary constraint.

Custom specialists become valuable when a clear pattern emerges. The threshold test is simple: the task should involve nondeterministic decisions rather than a fixed deterministic workflow, and it should recur often enough to justify prompt maintenance, tool scoping, and coordination overhead. A fixed workflow with almost no subjective decisions is better handled by a traditional tool.

Teams should consider creating a custom specialist when:

• A recurring domain task produces inconsistent results. Security reviews that miss the same vulnerability classes, documentation that drifts from code, or migrations that repeatedly introduce the same integration failures.
• The default agents lack domain-specific knowledge. General-purpose agents do not encode rules about a team's design token taxonomy, security threat model, or migration compatibility matrix.
• Tool access needs to be restricted or expanded. A read-only reviewer should not have write access. A security scanner may need access to a vulnerability database tool that general agents do not use.

Adding specialists introduces prompt maintenance, tool scoping decisions, and coordination overhead. Start with the default trio, observe where it falls short, and extract a specialist only when a repeatable pattern justifies the investment.

Defining Custom Agents with YAML-Frontmatter Markdown Files

Auggie CLI subagents are defined as Markdown files with YAML frontmatter, stored in one of two directories. This file-based mechanism is distinct from Intent custom specialists, which are configured through the Intent Settings UI.

The two directories differ in scope and version-control behavior:

Workspace-level agents in .augment/agents/ can be committed to version control and shared across a team. This makes agent definitions part of the codebase rather than personal configuration.

File Structure

Each agent file uses the following YAML frontmatter fields:

If both tools and disabled_tools are specified, disabled_tools takes precedence, and tools is ignored. If neither is specified, the subagent has access to all tools by default. The agent prompt is the main body of the Markdown file and supports headings, lists, code blocks, and standard Markdown formatting.

Available Tools for Restriction

For Intent custom specialist agents created through the Settings UI, refer to the Intent overview for the exact configuration options.

Creating a Security-Scanner Agent

A security-scanner agent addresses the gap between vulnerability detection and remediation. Traditional SAST tools flag issues but produce no fixes. A specialist agent can identify vulnerabilities, classify severity, and propose specific remediations within the constraints of a codebase.

The prompt should specify what the agent analyzes, what it does not cover, and how it handles uncertainty. Explicit negative scope statements prevent the agent from drifting into architectural suggestions or performance optimization.

---
name: security-scanner
description: Static security analysis agent for PR review
model: sonnet4.5
color: red
disabled_tools:
  - str-replace-editor
  - save-file
  - remove-files
  - launch-process
---

You are a static security analysis agent. Your sole function is to
identify security vulnerabilities in the code changes presented to you.

## Scope

Analyze: injection flaws, authentication bypass, insecure deserialization,
path traversal.

Do NOT: suggest architectural changes, refactor code, optimize performance,
or comment on non-security issues.

Analysis boundary: intra-procedural only.

## Output Format

For each finding:
- severity: CRITICAL | HIGH | MEDIUM | LOW
- cwe_id: [CWE identifier]
- location: file:line
- description: [what the vulnerability is]
- remediation: [specific fix]

If no findings: return NO_FINDINGS.

## Uncertainty Handling

If you cannot determine whether a pattern is vulnerable without runtime
context, return REQUIRES_MANUAL_REVIEW with your reasoning. Do not guess.

Tool restriction is the design principle at work here. The disabled_tools field removes write access entirely, making this agent read-only. Tool restriction shapes how an agent reasons, not just what it can do.

Creating a Documentation-Writer Agent

A documentation-writer agent addresses documentation drift by generating API documentation, inline comments, and README sections directly from source code. Research from Microsoft's DocAider project found that single-agent documentation design led to hallucinations and incomplete documentation; DocAider uses a multi-agent approach for documentation generation and revision.

---
name: doc-writer
description: Generates API documentation from source code
model: sonnet4.5
color: blue
disabled_tools:
  - str-replace-editor
  - remove-files
  - launch-process
---

You are a technical documentation agent. You generate API documentation,
inline code comments, and README sections from source code provided to you.

## Constraints

- Only document what the code explicitly does. Do not infer intent.
- If a function's behavior is ambiguous, output [NEEDS_CLARIFICATION: <question>].
- Do not document private/internal methods unless explicitly instructed.
- Do not include performance claims, security guarantees, or behavioral
  assertions not verifiable from the provided code alone.
- Output format style: JSDoc unless otherwise specified.

The disabled_tools configuration prevents the agent from editing existing files or running shell commands, limiting its scope to reading code and creating new documentation files.

Creating a Migration Specialist

A migration specialist handles large-scale transformations such as language version upgrades, framework replacements, or monolith decomposition. The critical design principle is that the migration agent should not decide what to migrate or in what order. It receives a pre-defined task from the Coordinator's plan and translates one file at a time. Google's research on agent-assisted migrations documents the same principle: provide agents with change locations rather than having agents discover changes autonomously.

---
name: migration-specialist
description: Translates files from source to target framework
model: sonnet4.5
color: yellow
tools:
  - view
  - codebase-retrieval
  - str-replace-editor
  - save-file
---

You are a code migration agent. You translate one file at a time according
to a pre-defined migration plan. You do not modify the plan and do not
discover additional files to migrate.

## Scope

Input: A single source file + its direct dependency context + migration rules.
Output: The translated target file only.

Do NOT: modify build configuration files, update dependency manifests,
migrate files not explicitly assigned in your task input, or make
architectural decisions about the target framework.

## Constraints

- Preserve all business logic exactly. Do not optimize during migration.
- If a source pattern has no direct equivalent, output
  [MIGRATION_NOTE: <description>] and preserve original logic as a commented block.
- If a dependency import path cannot be determined, output
  [DEPENDENCY_UNRESOLVED: <name>] rather than guessing.

Scoping Agent Behavior with the Rules System

The Rules System layers behavioral constraints onto agent definitions. Rules are distinct from agents but critical for controlling how agents operate across different parts of the codebase.

AGENTS.md and CLAUDE.md files placed in subdirectories enable directory-scoped rules. The system walks up the directory tree and loads all relevant rules along the path:

my-project/
  AGENTS.md                  ← Always included (workspace root)
  src/
    AGENTS.md                ← Included when working in src/ or subdirectories
    frontend/
      AGENTS.md              ← Included when working in src/frontend/
    backend/
      AGENTS.md              ← Included when working in src/backend/
  tests/
    AGENTS.md                ← Only included when working in tests/

Well-scoped rules reduce hallucination, unnecessary edits, and workflow noise. A security-scanner agent operating in src/backend/ automatically picks up backend-specific constraints, such as which authentication patterns are required, without those constraints cluttering the agent's base prompt. Rules also support two application modes through the type frontmatter field: always_apply, included in every prompt, and agent_requested, attached only when the agent determines relevance based on the rule's description.

Mixing Custom and Built-In Agents in a Single Workspace

Intent's architecture allows custom specialists to operate alongside the default coordinator-implementer-verifier trio without replacing them. The Coordinator decomposes tasks into a DAG, and any subtask can be routed to either a built-in persona or a custom specialist based on the task's requirements.

On a single feature task, the roles are typically split like this:

• The Coordinator drafts the spec and decomposes the work.
• The Implement persona handles standard feature code.
• A custom security-scanner agent reviews changes for vulnerabilities.
• A custom doc-writer agent generates documentation for new APIs.
• The Verifier checks all outputs against the living spec.

Intent keeps orchestration lightweight through wave-based delegation. The Coordinator fans work out in parallel batches, and each agent, built-in or custom, runs in an isolated git worktree with its own scoped context. This avoids the overhead of heavier multi-agent frameworks, particularly in peer-to-peer meshes, where communication pathways grow combinatorially as agents are added.

When using Intent's Context Engine, teams implementing mixed-agent configurations maintain coordinated context within the same semantic index, preventing the fragmentation that occurs when agents have independent, partial views of the codebase.

Key Decision Points When Defining Custom Agents

Several decisions shape how effective a custom agent will be. These are practical tradeoffs, not rigid rules.

• Single specialist vs. multiple specialists. Start with one agent per domain. A single security-scanner agent is easier to test and maintain than separate agents for injection detection, authentication review, and dependency scanning. Split into multiple specialists only when a single agent's prompt grows large enough to degrade reasoning quality.
• Prompt detail level. Follow the minimal sufficiency principle: include the smallest set of information that fully outlines expected behavior. Start with a minimal prompt using the best available model, then add instructions based on observed failure modes rather than anticipated ones. Hardcoding complex, brittle logic creates fragility; vague, high-level guidance fails to give the model concrete signals.
• Tool access scope. Tool access is the hard enforcement layer that prompt text alone cannot provide. An agent bound only to view and codebase-retrieval cannot modify files regardless of what its prompt says. Grant only the tools required for each agent's role, and treat tool restrictions as a reliability decision.

Common Failure Points and What Works

Teams that extend Intent with custom specialists encounter predictable failure modes in the early stages. The patterns below capture what consistently works and what creates avoidable complexity.

Agents hallucinating outside their context. When a prompt lacks explicit uncertainty handling, the agent guesses rather than flagging ambiguity. The mitigation: include escape hatches like "return REQUIRES_MANUAL_REVIEW with your reasoning" or "return UNKNOWN for any field you cannot determine from the provided source code."

Vague role boundaries are causing handoff loops. When two agents have overlapping scope, a security scanner that also suggests refactors, or a documentation writer that also fixes code, the Coordinator may route tasks ambiguously. State what the agent does not cover as explicitly as what it does.

Rubber-stamp verification. Verifier agents can systematically approve incorrect outputs because agreement is the path of least resistance. Mitigation: frame verification adversarially, requiring the Verifier to identify at least one specific problem before an approval is valid.

Prompt bloat over time. Agent prompts accumulate instructions, examples, and edge cases until they consume a significant amount of context space. Shopify's engineering team documented this pattern: as their tool inventory grew, their system prompt became "an unwieldy collection of special cases, conflicting guidance, and edge case handling that slowed the system down and made it nearly impossible to maintain." The solution is just-in-time instruction injection, dynamically loading only the instructions relevant to the current task.

What works well. Domain-specific prompts that encode vulnerability classes, token taxonomies, or migration patterns yield more accurate results than general-purpose agents. Chaining specialists through wave-based delegation speeds up PR cycles by running security reviews and generating documentation in parallel. Version-controlled agent definitions in .augment/agents/ let teams review, iterate, and share agent configurations like code. Editable prompts stored in Markdown files keep detection logic reviewable rather than buried in tooling.

Custom Specialists vs. Default Trio

Custom specialists improve fit for recurring domain tasks, but they add setup and maintenance overhead that the default trio avoids.

The table below contrasts both configurations across the dimensions that typically drive the decision:

Practical Tips for Custom Agent Development

Practical custom agent development depends on prompt discipline, narrow permissions, and iterative testing.

• Structure prompts with labeled sections: Use clear headers for Role, Scope, Constraints, Output Format, and Uncertainty Handling. Place hard behavioral constraints near the beginning.
• Test agents incrementally before production use: Run a new agent against a small set of representative tasks. Evaluate output quality, check for scope violations, and add prompt instructions only in response to observed failures.
• Version agent definitions over time: Store project guidance in the documented .augment/rules/ directory or AGENTS.md files in the workspace. Treat prompt changes with the same rigor as code changes: review them, test them, and track what changed.
• Limit tool access by default: Start with the minimum tools an agent needs, often just view and codebase-retrieval for read-only agents, and add tools only when the agent demonstrably needs them.
• Use the plugin system for cross-team distribution: Package agents into plugins that can include agent definitions, rules, commands, hooks, skills, and MCP server integrations.

Concrete Example of a Design Token Enforcer Workflow

A design token enforcer illustrates how a custom specialist fits into Intent's coordinator-specialist-verifier flow, from spec through human review before merge.

1. Spec creation. A developer writes a spec in Intent: "Audit src/components/ for hardcoded color values and replace them with design tokens from tokens/colors.json."
2. Coordinator decomposition. The Coordinator analyzes the codebase using the Context Engine, identifies all components that use hardcoded values, and decomposes the work into file-level subtasks ordered by dependency.
3. Specialist execution. A design-token-enforcer agent runs with scope limited to replacing values that have an exact match in the token files. It does not create new tokens, modify token files, or refactor component structure. When a hardcoded value has no exact token match, it outputs [TOKEN_MISSING: <value> in <file>:<line>] and leaves the original value unchanged.
4. Verification. The Verifier checks each modified file against the spec, confirming that all replacements reference valid tokens and that no hardcoded values remain in files the specialist processed. Any TOKEN_MISSING flags are surfaced for human review.
5. Human review and merge. The developer reviews the changes, resolves TOKEN_MISSING items, and creates a PR.

The living spec updates as agents complete tasks, so the developer can track implementation status in the agent workspace without manually checking each file. When using Intent's Context Engine, the token-enforcer agent maintains awareness of the full token taxonomy across the repository, preventing replacements that reference tokens from incorrect namespaces.

Start with One Specialist Today

The strongest custom agent workflows start small. So, start by defining one specialist for the domain task that causes the most friction, test it against real code, and revise the prompt only after observing concrete failure modes. That keeps the tradeoff clear: better fit for a recurring task, in exchange for prompt maintenance and tool-scoping overhead.

For most teams, the next step is simple: keep the default trio in place, identify the one recurring task where outputs stay inconsistent, and extract that task into a narrowly scoped specialist with explicit uncertainty handling.

Frequently Asked Questions About Custom Specialist Agents

Related Guides

• Top 5 AI Workflow Orchestration Platforms for DevOps
• 5 Autonomous Agents for End-to-End Feature Automation
• System-Wide AI Code Analysis: 4 Holistic Platforms
• 6 AI Tools for Distributed System Mapping
• 6 AI-Powered Code Linter Platforms for Quality Gate Automation