How I introduced four custom agents during a real website modernization, corrected a review-scope problem, and learned when specialization was worth the overhead.
When I modernized yonka.dev, my professional website, I replaced an ASP.NET Core Razor Pages application with a static website built with Astro.
I used GitHub Copilot CLI throughout the project, from investigating the existing code to implementing and reviewing the new site. It was also my first opportunity to work with custom AI agents.
At first, I wondered whether I should create a designer, a developer, a tester, a code reviewer, and perhaps another agent to coordinate them all. But I was modernizing a personal website, not managing a software department. I wanted each custom agent to solve an actual problem, rather than create a team of specialists for its own sake.
I asked Copilot to investigate which built-in agents were already available and whether I needed additional custom agents for the project. After reviewing its findings, I decided to rely on the built-in agents where appropriate, keep the main Copilot agent responsible for implementation and coordination, and create just one custom agent initially.
Why I created site-reviewer
The new yonka.dev needed to present my products and make my technical writing and contributions easy to discover. It also needed consistent navigation, responsive layouts, English and German pages, and light and dark themes.
I recorded the website requirements in docs/modernization/product-discovery.md: what the website should become. The repository instructions in .github/copilot-instructions.md described how Copilot should work, including engineering conventions, verification expectations, and approval boundaries.
Copilot already had built-in code review capabilities. What I wanted in addition was a review of whether a completed change met the relevant website requirements, rather than only whether the code was technically sound. That became the single purpose of my first custom agent, site-reviewer.
In Copilot CLI, a custom agent is defined in a repository Markdown file with instructions and tool access. I configured mine in .github/agents/site-reviewer.agent.md to read and search the repository, report evidence-backed findings, and identify behavior that still needed browser verification. It was not allowed to modify the code it reviewed.
Its reviews covered applicable website requirements such as navigation, accessibility, localization, themes, and SEO.
When a full-site review became too broad for a smaller task
Before implementing the redesign, I tested site-reviewer against the original ASP.NET Core website. I deliberately requested a full-site assessment to understand the gap between the old site and the planned one.
The reviewer identified the missing contribution archive, the old .NET-focused homepage, and the absence of a persistent theme setting. It classified six findings as expected modernization gaps while also marking them “must fix for launch.” It also surfaced existing issues worth investigating, including accessibility labels that remained in English on German pages.
For that initial assessment, the broad scope made sense. These were requirements for the finished website, and I had asked the agent to evaluate the site as a whole.
The problem appeared later, when I used the reviewer on a smaller implementation task. Its report flagged missing features planned for future milestones as defects, even though they were not part of the task being reviewed. It was assessing the website against the overall target instead of distinguishing the smaller task from work scheduled for later.
For example, a review of completed mobile navigation should focus on whether the menu works, links reach the right destinations, and both languages behave correctly. An article archive scheduled for a later milestone should not be reported as a defect in that navigation task.
Refining the review instructions
The original instructions gave the reviewer the website's broader requirements and areas to assess, but did not make the boundary between the current milestone and future work clear enough. That was useful for the first full-site assessment, but not for reviewing a smaller completed task.
I updated the permanent instructions to make that boundary explicit. One of the actual additions was:
First identify the current task and milestone from its prompt
and acceptance criteria. Assess only requirements applicable
to that milestone, while checking that changes do not conflict
with the product brief.
Acceptance criteria are the conditions the current task must satisfy to count as complete. The product brief describes the wider target for the website. The reviewer needs both, but must report unfinished planned work separately from defects in the current task.
Here is a simplified version of the refined agent configuration, rather than the complete file:
---
name: site-reviewer
description: "Review a website change against current acceptance criteria"
tools: ["read", "search"]
include-custom-instructions: true
---
Identify the current task and its acceptance criteria.
Use the product brief for context, but distinguish defects in
this milestone from work intentionally scheduled for later.
Report findings with file locations, requirements, and evidence.
State which observations still require browser verification.
Do not edit implementation files or change acceptance criteria.
The read and search tools kept this reviewer focused on inspection, while include-custom-instructions: true let it use the repository's shared Copilot instructions. The added milestone rule defined which requirements to assess now and which planned work to leave for later. This is an illustrative shortened configuration, not a verbatim copy of the complete agent file.
Three more specialists, three different needs
As the modernization progressed, I encountered needs that called for different responsibilities. I added three specialists rather than expanding site-reviewer into an agent that designed, implemented, and tested its own work.
| Agent | Main responsibility | Boundary |
|---|---|---|
site-reviewer |
Check the current milestone against product requirements and user-facing expectations | Read-only assessment; identify what still needs browser review |
ui-designer |
Implement approved visual changes using the site's existing patterns | May edit components and styles, but not choose a new design direction independently |
code-quality-reviewer |
Check changed code against the project's architecture and conventions | Read-only; complements rather than duplicates general code review |
verification-engineer |
Run relevant checks and investigate actual generated or browser behavior | Reports evidence; does not change application code or weaken tests to obtain a pass |
ui-designer: consistency across pages
I didn't want every new page to arrive with a new set of styles. The ui-designer was instructed to inspect existing components, design tokens, typography, spacing, and interaction patterns, then reuse them when implementing approved visual changes.
It could edit Astro components and styles, but it was not authorized to invent a new visual direction or redesign approved pages on its own. Its job was to implement within an agreed design system. How I reached that visual direction is a separate design problem; the important point here is that a specialist's permission to edit did not give it permission to decide what the site should look like.
code-quality-reviewer: project-specific engineering checks
Copilot already offered general review capabilities. My custom code-quality reviewer had a narrower job: assess whether changes followed the architecture and conventions established for yonka.dev.
For example, did a change reuse shared Astro components and content collections? Did it follow the central localization approach? Had it introduced duplicate logic, obsolete CSS, or a regression risk for a directly affected page? The reviewer inspected changed code and its direct consumers, but remained read-only.
A change can be technically valid yet inconsistent with the architecture the project has agreed to maintain. That is what this reviewer was meant to catch, rather than repeat the site reviewer’s assessment of product requirements.
verification-engineer: look beyond the source
Astro builds source components and styles into static HTML, CSS, JavaScript, and assets in a dist/ directory. Those generated files are what eventually gets deployed and rendered in the browser.
The browser receives generated output, not the original Astro source files.
During the modernization, I encountered situations where the source appeared reasonable and automated checks passed, but the rendered page differed from expectations. One issue involved CSS cascade layers, which determine style priority, and PostCSS processing during the build. Inspecting the source alone wasn't enough to determine which styles the browser actually applied.
The verification-engineer could run checks appropriate to the change, including builds, CSS linting (static checks for stylesheet problems), checks of generated files, and automated tests in a headless browser. For a styling discrepancy, that meant comparing the source with the generated CSS and inspecting the browser’s computed styles: the final property values applied to the affected element. This gave the implementing agent evidence to investigate rather than another speculative CSS change.
I kept an important boundary: the verification agent was not supposed to edit application code or relax an assertion just to turn a failing result green. The implementation needed to be corrected separately. And a passing browser test still did not replace visual inspection: a test only establishes what its assertions actually check. I explore that limitation more closely in a separate article about a language-switcher test that passed without checking the intended requirement.
Coordination was useful; more reviews weren't always better
I did not manually invoke all four agents after every change. The main Copilot CLI agent could delegate to specialists according to the task and repository instructions. When a particular review mattered, I explicitly requested it.
Copilot could also run multiple agents concurrently. During one review, site-reviewer, code-quality-reviewer, and verification-engineer were active in the background:
The site-reviewer, code-quality-reviewer, and verification-engineer running concurrently during a code review.
Parallel reviews made sense when the agents examined different aspects of the same completed change: product requirements, code conventions, and executed verification. But different roles do not automatically mean independent conclusions. Agents operating in the same repository can rely on the same requirements, assumptions, or incomplete tests. Their reports still need to be checked against observable evidence.
There was also a practical cost. More agents produced more findings to evaluate and consumed more Copilot usage. A small content edit did not necessarily justify three parallel reviews. For a change to shared navigation or generated-site behavior, specialist checks could be more valuable.
I continued to make the scope, architecture, design, acceptance, commit, and deployment decisions. The agents could help investigate and execute approved work; their presence did not transfer responsibility for the result.
Key takeaways: When custom agents are worth creating
On another project, I would follow the same approach: start by investigating which built-in agents and capabilities Copilot already provides, then identify whether the project has specific needs that justify creating custom agents. I wouldn't create a complete team of specialists from the beginning.
Before introducing a custom agent, I would consider four things:
- Trigger: What kind of task should invoke it, and when is it unnecessary?
- Responsibility: What should it be responsible for, and how does that differ from the built-in agents or other specialists?
- Permissions: Does it need to modify files or execute tests, or should it only inspect and report?
- Evidence: What should it provide to support its findings, such as file locations, commands executed, test results, or behavior that still needs verification?
I would then try the agent on a real task and inspect its findings before making it part of the regular workflow. That first trial matters: an agent can identify valid issues without yet having the right boundaries for routine use.
During the modernization, four custom agents proved useful for different purposes. However, I wouldn't invoke all of them for every change. The value of a custom agent comes from the specific responsibility it fulfills, not from the number of agents involved.


Top comments (0)