Alex: Welcome back. Bonus A is called Improve an Agent, and it is exactly what it sounds like: you take an existing agent and make one focused, useful improvement.

Jamie: I like that this is not asking everyone to invent something from scratch. Sometimes the best contribution is noticing that an existing tool could be clearer, safer, or more complete.

Alex: Yes. The goal is an accessibility-purpose improvement that a maintainer could review. It might be a new responsibility, a clearer guardrail, a better description, or a small fix that helps the agent behave more reliably.

Jamie: And this bonus has a place in the larger workshop path, right?

Alex: Right. Challenge 15 is the browse-first agent discovery challenge. Completing Challenge 15 unlocks Challenge 16, the Capstone Project, plus Bonus Challenges A through E. You do not have to complete the capstone before starting Bonus A, but this bonus can absolutely feed into your capstone evidence.

---

Jamie: Before we talk workflow, can we define what an agent is in this context?

Alex: An agent is usually a Markdown file with instructions for an AI assistant. In these repos, agent files often end in .agent.md, and they describe the agent's purpose, responsibilities, limits, and response style. Those limits are often called guardrails, which means instructions about what the agent should not do or when it should ask for human review.

Jamie: So improving an agent is not just changing words. You are changing the instructions that guide future behavior.

Alex: Exactly. And the course principle still applies: skill first, agent second. If an agent reviews pull requests, you should have read diffs and PR conversations by hand. If an agent checks accessibility, you should understand the manual accessibility skill well enough to judge whether the agent output is useful.

Jamie: That keeps the AI from becoming a mystery box. You are still the reviewer.

Alex: Yes. You should already have the basics from the workshop: GitHub account, Git, VS Code or another editor, Copilot access if you plan to test in chat, and the Day 1 contribution workflow from the Learning Room repository. That Learning Room work gave you the issue, branch, commit, pull request, and merge pattern you will reuse here.

Jamie: And the target repo does not have to be only one place.

Alex: Correct. Accessibility Agents is a strong default because it is a living catalog of accessibility, GitHub workflow, and developer tool agents. GLOW is another good path if you care about document accessibility, large print, Office files, web apps, or conversion workflows. You can also choose another meaningful repository if it already uses agents or would benefit from one.

---

Alex: Start by browsing. Open the repository you want to help, look for its agent folders, and read two or three .agent.md files before choosing one.

Jamie: That sounds simple, but I can imagine opening a catalog and thinking, there are too many choices. What should I listen for while reading?

Alex: Listen for purpose, scope, and boundaries. What is this agent supposed to help with? What inputs does it expect? What kind of answer does it produce? And just as important, where could it overreach?

Jamie: So I am not trying to find a broken agent. I am trying to find a place where the instructions could serve users better.

Alex: Exactly. Good candidates include a vague responsibility, a missing guardrail, a typo that could confuse readers, an unclear description, or a new responsibility that clearly fits the agent's mission. A small wording change can be valid if you can explain why it improves clarity or accessibility.

Jamie: That is reassuring. I think people sometimes assume a contribution has to be dramatic.

Alex: In this challenge, dramatic is usually a warning sign. One focused change is easier to review, easier to test, and more respectful of the original author's choices.

---

Alex: Once you have an agent, make a working branch. A common branch name is agent-improve slash the agent name, for example agent-improve slash aria-specialist.

Jamie: Do I always need a fork?

Alex: Use whatever contribution path the repository allows. If you do not have write access, you will usually work from a fork. If you do have access, you might create a branch in the repository. Either way, keep the branch focused on this one improvement.

Jamie: Then the edit is inside the agent file itself?

Alex: Usually, yes. Edit the .agent.md file and make the improvement clear. If the agent uses YAML frontmatter at the top, be careful with indentation and punctuation. Below that, look for sections such as purpose, responsibilities, domain knowledge, guardrails, or response guidelines.

Jamie: What would the commit look like?

Alex: Use a commit message that names the agent and the specific change. For example: Improve aria-specialist: add live region review. Then push your branch so it has a URL you can share.

Jamie: And then comes the review path.

Alex: If the project accepts pull requests, open one against the original repository and explain why the change makes the agent better. If a workshop pull request is not appropriate, a review-ready branch or contribution plan is still valid evidence. The key is that someone else could understand your change and review it.

---

Jamie: Can we walk through the sample improvement? I always learn faster when I can hear one concrete case.

Alex: Sure. The sample target is aria-specialist.agent.md. The improvement adds a responsibility for checking aria-live regions in dynamic content. The existing agent covered static ARIA roles and states, but it did not call out live regions.

Jamie: Quick definition: aria-live is what lets screen readers hear updates that happen after the page has already loaded, right?

Alex: Yes. Search results, notifications, form validation messages, and status updates can change without a full page reload. If those updates are not announced properly, a screen reader user may miss critical information. So an ARIA-focused agent should know to review live regions and the politeness level, such as polite or assertive.

Jamie: What changed in the responsibilities?

Alex: Before, the responsibilities included checking interactive elements for correct ARIA roles and verifying that ARIA states match the visual state of components. The added line says to review aria-live regions for appropriate politeness levels on dynamic content updates. That is one clear addition, not a rewrite of the whole agent.

Jamie: And the pull request explanation would say why that gap matters.

Alex: Exactly. It would say that dynamic updates need to be announced to screen readers, and that the agent already checks static ARIA but did not mention live regions. That explanation turns the edit from a preference into a reasoned accessibility improvement.

---

Alex: The challenge evidence is short, but it should be specific. You will describe the repository, the agent you improved, what you changed, why it is an improvement, and a link to the pull request, branch, or contribution plan.

Jamie: So not just, I updated an agent. More like: I improved this agent, in this repo, by adding this guardrail, because it prevents this kind of bad output.

Alex: Exactly. The evidence should show your judgment. Maintainers need to know the problem you saw and why your fix is scoped well.

Jamie: The criteria are specific, justified, and respectful, right?

Alex: Yes. Specific means change one thing well. Justified means explain why the change helps. Respectful means you are improving an existing design, not treating the original work like it was careless.

Jamie: That respect piece feels important in open source.

Alex: It is. Maintainers are more likely to engage when the pull request shows care for the project, its conventions, and its users.

---

Jamie: How much testing should someone do for a text-only agent change?

Alex: Do a practical check. Open the repository in VS Code or github.dev, read the edited file from top to bottom, and make sure the instructions still make sense. If you have Copilot Chat available, run the agent with a small prompt and see whether the output reflects your change.

Jamie: For example, if I added a live region responsibility, I could ask it to review a component with a status message that updates after a form submission.

Alex: Exactly. Then compare the output against what you know manually. Does the agent notice the dynamic update? Does it avoid making unsupported claims? Does it suggest a reasonable fix?

Jamie: And if the output gets worse?

Alex: Narrow the instruction. A lot of agent problems come from language that is too broad. You can improve reliability by adding a guardrail, giving an output format, or saying when the agent should ask for more context instead of guessing.

Jamie: Where do the different platforms fit here?

Alex: Use the platform that lets you work comfortably and verify the change. GitHub Copilot Chat in VS Code is the most common workshop path, and the VS Code Agents window can help manage agent sessions. Some teams use GitHub.com task mode, Claude Code, Gemini CLI, Claude Desktop, or other supported tools. The important repo detail is that custom agents usually live with the project, often under .github slash agents, so the instructions can travel with the repository.

---

Jamie: What if every agent looks perfect?

Alex: Read for clarity, scope, and guardrails. Ask whether a new contributor would understand what the agent can do, what it should not do, and what kind of output to expect. A small clarification is fine when it helps future users.

Jamie: What if I am not sure my change really counts as an improvement?

Alex: Try to explain it in one sentence. If you can say who benefits and what confusion or risk it reduces, you probably have a valid improvement. If you cannot explain it, keep reading until you find a clearer gap.

Jamie: And if I need to check current facts?

Alex: Use the current project docs, official GitHub Docs, GitHub Copilot docs, VS Code docs, and the GitHub Changelog when platform behavior matters. Counts, feature names, and platform support can change, so avoid baking fragile numbers into your contribution unless you have just verified them.

Jamie: After review, do I need a merged pull request to count this bonus?

Alex: No. A merged pull request is wonderful, but workshop evidence can be a pull request, a review-ready branch, or a contribution plan. For Challenge 16, the Capstone Project, those same kinds of review-ready drafts and plans are also valid when they show purpose, responsibilities, guardrails, and a meaningful repository impact.

---

Jamie: Let me see if I have it. Bonus A asks me to choose an existing agent, understand its current instructions, make one focused accessibility-related improvement, and explain the value clearly.

Alex: That is it. Browse first, pick carefully, change one thing, test enough to trust it, and leave a reviewable trail. If your work helps an agent become clearer, safer, or more useful for real accessibility workflows, you have done the work this bonus is asking for.