Customizing Agents
Relevant source files
The following files were used as context for generating this wiki page:
In the AI Dev Atelier project, agents are modular and customizable entities designed for AI-assisted development. Customization is achieved through a combination of structured "Skills," detailed agent persona definitions, and configurable workflow guardrails. This system allows for the creation of specialized agents that can perform tasks like code quality checks, documentation updates, and code reviews.
The core components for customization are the skills themselves, defined in SKILL.md files, and the agent definitions, such as the pr-comment-reviewer. These components are orchestrated by an agent runtime like OpenCode, which discovers and utilizes them based on configuration files and directory structures.
Sources: AGENTS.md:7-8, skills/README.md:3-5
Agent and Skill Architecture
The architecture is built around the concept of agents discovering and executing skills. Skills are self-contained units of capability that follow the Anthropic Agent Skills standard. Agents can also leverage MCP (Multi-purpose Co-pilot Protocol) servers for external functionalities like web search or academic research.
Sources: AGENTS.md:8, README.md:32-46
This diagram illustrates the relationship between agents, skills, and MCPs.
Sources: skills/README.md:78-87, AGENTS.md:10-16
Skill Discovery and Execution
Agents discover available skills by scanning a designated directory (e.g., ~/.opencode/skill) for directories containing a SKILL.md file. When a task requires a specific capability, the agent reads the SKILL.md to understand its purpose and how to execute it, typically by running an associated bash script.
The install.sh script is responsible for deploying skills to the correct location for the agent to discover.
Sources: skills/README.md:78-87, INSTALL.md:120-123
Defining and Customizing Skills
A skill is defined by a directory containing a SKILL.md file and an optional scripts/ subdirectory for executables. The SKILL.md file is the primary definition, containing YAML frontmatter and Markdown instructions.
Sources: skills/README.md:3-5, AGENTS.md:10-12
This diagram shows the standard directory structure for a skill.
Sources: AGENTS.md:10-16, 105-110
Available Skills
The repository provides a set of pre-defined skills for various development tasks.
| Skill | Description | Entry Point |
|---|---|---|
code-quality | Run comprehensive code quality checks including typecheck, lint, format, and markdown validation | scripts/finalize.sh |
docs-check | Analyze git diff to identify code changes requiring documentation updates | scripts/check-docs.sh |
docs-write | Write or update documentation with clear style, structure, visuals, API/ADR/runbook patterns | Workflow skill (no script) |
git-commit | Write clear git commits with Conventional Commits format | Workflow skill (no script) |
code-review | Review code changes using CodeRabbit - uncommitted files (task mode) or all PR files vs main (pr mode) | scripts/review-run.sh |
resolve-pr-comments | Multi-agent PR comment resolution for bot reviews (CodeRabbit, Copilot, Gemini) | scripts/pr-resolver*.sh |
search | Search the web and library documentation using Tavily and Context7 MCPs | MCP-based (no script) |
research | Conduct academic research using OpenAlex, PDF extraction, and paper search MCPs | scripts/research-*.sh |
ui-animation | Guide tasteful UI animation implementation with easing, springs, timing, and accessibility | Workflow skill (no script) |
Sources: skills/README.md:8-20, README.md:29-43
Defining and Customizing Agents
Beyond skills, individual agents can be defined with specific personas, instructions, and constraints. The pr-comment-reviewer is a prime example of such a specialized agent, defined entirely within agents/pr-comment-reviewer.md.
This file acts as a detailed instruction set for an AI model, outlining its role, scope, mindset, and strict behavioral rules (anti-patterns).
Sources: agents/pr-comment-reviewer.md:1-10
Example: The pr-comment-reviewer Agent
The pr-comment-reviewer is a subagent designed to validate and resolve PR review comments from automated bots. Its definition file provides a comprehensive guide for its operation.
Core Responsibilities
- Analyze: Understand the bot's claim.
- Validate: Determine if the issue is a false positive.
- Fix: Apply a minimal, correct fix if the issue is real.
- Verify: Ensure the fix does not introduce new problems.
- Execute Resolution: Run a script to close the corresponding GitHub thread.
Sources: agents/pr-comment-reviewer.md:65-75
Workflow
The agent follows a strict, multi-phase workflow for each comment cluster it processes. This ensures a consistent and reliable approach to resolving issues.
This flowchart visualizes the mandatory workflow for the pr-comment-reviewer agent.
Sources: agents/pr-comment-reviewer.md:86-297
Behavioral Guardrails (Anti-Patterns)
A critical part of an agent's definition is its "Anti-Patterns" section, which lists forbidden behaviors. These hard constraints are essential for safety and reliability.
| Anti-Pattern | What To Do Instead |
|---|---|
â Suppress type errors with as any, @ts-ignore | Fix the underlying type issue. |
| â Delete failing tests to make them pass | Fix the code to pass the test. |
| â Defer without researching first | Research deeply first; only defer if truly uncertain. |
| â Commit changes without explicit request | Only commit when the user explicitly asks. |
| â Refactor while fixing | Fix exactly what's requested, nothing more. |
| â Skip verification before resolving | Run diagnostics/tests BEFORE resolving the comment. |
| â Dismiss without evidence | Always search for evidence before dismissing. |
Sources: agents/pr-comment-reviewer.md:14-28
Enforcing Workflows with Hooks
The project uses PreToolUse hooks to enforce workflow guardrails by intercepting tool calls before execution. These are defined in hooks.json and installed by install.sh. This mechanism prevents agents from performing actions that conflict with established project workflows, such as using git push in a Graphite-managed repository.
Sources: AGENTS.md:49-52, 59-62
This sequence diagram shows how a PreToolUse hook intercepts and blocks a forbidden command.
Sources: AGENTS.md:54-57
Defined Hooks
| Hook ID | Matcher | Purpose |
|---|---|---|
graphite-block | Bash | Blocks git push, git checkout -b, gh pr create in Graphite-enabled repos. |
pr-comments-block | Bash | Blocks gh api calls fetching PR comments on current repo's open PRs. |
Sources: AGENTS.md:54-57
Conclusion
Customizing agents in AI Dev Atelier is a structured process centered on defining skills and agent personas. Skills are created as modular, discoverable packages with clear instructions in SKILL.md files. Agent behavior is shaped through detailed persona documents, like pr-comment-reviewer.md, which specify roles, workflows, and strict anti-patterns. Finally, workflow guardrails are enforced using PreToolUse hooks, ensuring agents adhere to project-specific conventions. This layered approach allows for powerful, specialized, and safe AI-assisted development.
Sources: AGENTS.md, skills/README.md, agents/pr-comment-reviewer.md