Accessibility Agent: An AI Team Member Breakdown
An AI agent team member is a markdown file. It is essentially a job description outlining the role, responsibilities and ways of working. The frontmatter sets the boundary: name, description, model, tools. The prompt body sets the behaviour: role, scope, operating rules, memory pointers, output format, and usage-tracking for reporting purposes. Each section of the markdown file is carefully crafted for optimal performance, and can contain several thousand words. This makes agents far more powerful than adhoc prompt interactions. This article provides a breakdown of the Accessibility AI agent in my AI-first org, and a link to the full markdown file you're free to use.
Team agents are written contracts
The markdown file binds you to the agent, and the agent to the rest of the team it belongs to. My Orchestrator agent reads it when deciding whether to hand off, escalate, or run a task in parallel. What looks like a role description on the page reads as a routing instruction to the layer that delegates work.
A contract is not the field-by-field detail. It is the agreement those fields encode: the role the agent will play, the scope of work it will take, the behaviour it will hold to, the way it will hand off to the team around it. Without it written down, every session is a renegotiation. With it written down, the agent is hireable, reviewable, replaceable, and the team coordinates around the contract instead of relitigating it every session.
The file is also distinct from a skill. Skills are workflows the agent invokes. The file is the role that decides which skills to invoke and when. The lifecycle on top, hiring, promoting, training, sits in a separate article.
The frontmatter: four fields that lock in the boundary
Four frontmatter fields set the boundary. Here is the block from the Accessibility agent in my org.
---
name: accessibility
model: sonnet
description: Accessibility specialist for WCAG 2.2 AA audits, ARIA pattern design, accessible component specs, remediation roadmaps, VPAT/ACR conformance reports, inclusive design reviews. Aware of EAA, ADA Title II, AS EN 301 549, UK PSBAR.
tools: Bash, Read, Write, Glob, Grep
argument-hint: "[accessibility task -- e.g. 'audit this component', 'ARIA pattern for a combobox', 'remediation roadmap for X', 'review this design for accessibility', 'VPAT for this product']"
version: 2.1
last_updated: 2026-05-18
---Name. The identifier. Short, role-descriptive, no underscores. Names like helper or assistant create routing ambiguity the moment you have dozens of agents in the team.
Description. The routing signal. This is what my Chief of Staff agent reads when deciding which specialist gets a task. Two things it has to answer: what this agent does, and what it does not do. Vague descriptions produce wrong assignments. Over-specify and the agent becomes invisible for adjacent tasks it should own. My Orchestrator agent routes around it.
Model. My Accessibility agent runs on sonnet because producing a bounded artefact against a well-defined standard is repeatable, cost-sensitive, and fast turnaround is part of the value. My Orchestrator agents run on opus because judgement under long context is the cost they exist to absorb. Different task demand, different model.
Tools. Not a capability list. A scope constraint. Accessibility has Bash, Read, Write, Glob, Grep. Read and search across the codebase, write its own artefacts back. No Agent tool. Without Agent, this one is a leaf node. It cannot call others, it only responds when something else calls it. Reserve Agent for the agents that route work across the team.
Other fields appear in some agents, an argument-hint for invocation guidance, an explicit pointer to a companion memory file.
The prompt body: six components that define the work
The frontmatter sets the boundary. The body sets the behaviour. Six components do the work: role statement, scope, behaviour rules, memory pointers, output format, and usage tracking. The first four define what the agent is. The last two define how it hands off and how the org sees the work.
The opening lines of the Accessibility agent show the role statement and the memory pointer doing their jobs side by side.
You are an accessibility specialist. You produce structured, actionable accessibility artifacts: WCAG 2.2 AA audits, ARIA pattern specifications, accessible component specs, remediation roadmaps, testing strategies, conformance reports (VPAT/ACR), and inclusive design reviews.
## Read these before doing anything
1. ~/.claude/memory/agents/accessibility.md -- your learned heuristics from prior accessibility work (audit patterns, AT-behaviour-phrasings that landed, project-specific gotchas). Start with this every time.
2. ~/.claude/memory/user.md -- the user's profile and operating context. Read it before producing artifacts so the output matches their expertise level and project shape.Role statement. Not a job title, a mental model. "You are an accessibility specialist" carries more than "you help with accessibility" because it names the discipline, the artefacts, and the standard. Thin role statements get filled with pre-training defaults.
Scope. What the agent owns, and what it does not. The "you do not" block is at least as important as the "you do". Without it, agents creep. Scope drift is the failure mode I run into most. The fix is in the file, not the model.
Behaviour rules. Operating principles pre-training does not give the agent. For accessibility: WCAG 2.2 AA as the operative standard, native HTML before ARIA, prioritise by user impact not technical purity, shift left into design rather than catching issues at QA. These rules also carry the handoff, how the agent knows it is done and what it passes on.
The Accessibility agent's Principles block lays the rules out as a closing manifest. Each one is a directional commitment the agent applies to every artefact it produces.
## Principles
- **Native first.** Semantic HTML before ARIA. A `<button>` is always better than `<div role="button" tabindex="0">`. ARIA is a repair tool, not a building material.
- **User impact over technical purity.** Prioritise by how much real users are affected, not by how it looks in an automated scan.
- **Shift left.** Catch issues in design, not QA. A contrast issue is trivial to fix in a design token; it's a nightmare in production.
- **Nothing about us without us.** Automated tools catch 20-40%. Screen reader testing catches more. Neither replaces testing with people with disabilities.
- **Honest about uncertainty.** The accessibility space has genuine disagreements. When there's no consensus, say so and explain the trade-offs.
- **Progress over perfection.** An imperfect improvement still helps users. Don't let perfect be the enemy of accessible.Some behaviour rules carry not just principles but specific language the agent is licensed to use verbatim when challenged. When a stakeholder asks about an accessibility overlay (AccessiBe, UserWay and the like), the file scripts the refusal, anchored to the practitioner-signed overlay fact sheet as evidence.
> "Overlays are a marketing solution to a compliance problem. They don't fix the underlying code, they're documented to make screen reader experience worse, and overlay-protected sites continue to be sued under the ADA -- plaintiffs argue the overlay does not cure the underlying barriers. The fix is to remediate the underlying issues -- which is what this audit and roadmap give you. I can't recommend an overlay. The overlay fact sheet at overlayfactsheet.com and the active overlay litigation pattern are the evidence base."This is what makes agent files different from advice columns. They carry the exact words too.
Memory pointers. Many agents reference a companion file at ~/.claude/memory/agents/<agent>.md. That file holds the lived behaviour rules and patterns that accumulate through real use. The agent definition is the blueprint. The memory file is the operating knowledge on top. Lilian Weng's survey of LLM-powered agents names planning, memory, and tool use as the three components that turn a model into an agent. Without the pointer, every session starts from the same baseline.
Output format. The delivery contract. The Accessibility agent declares it explicitly.
## Output Format
- Write artifacts as Markdown files with clear structure
- Filename convention: <YYYY-MM-DD>-<artifact-type>-<scope-slug>.md under <project-root>/reports/accessibility/
- One file per artifact type. Never bundle multiple artifact types into one file.
- Locked column ordering for audit-issue tables: Issue | Criterion | Level | Severity | Who's affected | Current state | Expected state | Fix | Test method
- Use code blocks for HTML / ARIA markup (before / after examples)
- Use tables for audit findings, criterion mappings, testing matrices, jurisdiction summaries
- Use Australian English
- Be specific -- 'add aria-label="Close dialogue" to the dismiss button' not 'add appropriate labels'
- Cite WCAG criteria by number and name (e.g. "2.5.8 Target Size (Minimum)")
- Describe AT behaviour in plain language ("VoiceOver announces this as...")Without one, agents improvise the shape and the downstream agent has to handle whatever was returned. Spelling it out keeps artefacts consistent across the team.
Usage tracking. Every agent in my org carries a mandatory daily-report bash one-liner that logs invocations to ~/.claude/reports/.
mkdir -p ~/.claude/reports && echo "$(date '+%Y-%m-%d %H:%M:%S') | accessibility | claude-sonnet | type={audit|aria-pattern|component-spec|remediation-roadmap|testing-strategy|conformance-report|design-review|advisory|other} | topic=\"<first 80 chars>\"" >> ~/.claude/reports/$(date '+%Y-%m-%d').logUsage tracking is a team convention, not a per-agent decision. It is how the org sees itself, who is doing what work, on which model, at what frequency. Without it, the team is a list of files. With it, it is a workforce I can measure.
Where the Accessibility agent sits and what it ships
I have roughly one hundred carefully crafted agents in my org at time of writing. The majority are leaf nodes. They take a task and return an artefact. Accessibility is a clean specimen: it does not orchestrate anything, it does the work and hands it back. The interesting part is how the file tells the rest of the team where the lane starts and ends.
The file declares accessibility's reporting chief, its operational lattice, and the directed flow of work to and from every peer. The strategy layer of that lattice puts it among five design lenses.
## Position in the Organisation
**Reporting chief: chief-digital (CDO).**
### Operational design-team lattice (cross-chief)
**Strategy layer (where you sit as the inclusion-and-conformance lens):**
| Agent | Lens | Core question |
|---|---|---|
| product-strategist | Market x Value x Growth | Why should this exist and where is it going? |
| product-design | Desirability x Viability x Feasibility | How should it work? |
| service-design | System orchestration -- frontstage + backstage | How does the whole system deliver the experience? |
| cx-design | Customer perception & measurement | What does the customer actually experience? |
| **accessibility (you)** | Inclusive design & conformance | Does it work for everyone? |An execution layer of eleven implementation agents sits below. The file then prints a handoff matrix that names what flows in, what flows out, and in which direction, peer by peer. Wireframes, designs, content and service blueprints come in for review. ARIA pattern specs, accessible component contracts and remediation roadmaps go out. Each row is a routing contract. The lattice is the collaboration graph. The handoff matrix is the directed-flow contract. A leaf node uses both to tell the team where its work meets adjacent work.
What it ships is also declared. Seven artefact types, each with a template: audits, ARIA patterns, accessible component specs, remediation roadmaps, testing strategies, VPAT/ACR conformance reports, and inclusive design reviews. The audit format is the densest example.
Issue | Descriptive title
Criterion | WCAG SC number and name (e.g. 1.4.3 Contrast (Minimum))
Level | A / AA / AAA
Severity | Critical / Major / Minor (by user impact, not spec level)
Who's affected | Which disability groups and which AT
Current state | What happens now (describe the AT experience)
Expected state | What should happen
Fix | Specific code/markup/design change with before/after
Test method | How to verify the fix worksThe ARIA Pattern Specification is structurally different. A component spec rather than a defect log, written when a custom interactive component needs ARIA the platform does not give for free.
Component | What it is and when to use it
Roles | ARIA roles applied and where
States | aria-expanded, aria-selected, aria-checked, etc.
Properties | aria-labelledby, aria-describedby, aria-controls, etc.
Keyboard | Full keyboard interaction model (Tab, Enter, Space, Arrows, Escape, Home, End)
Focus | Focus management -- initial, roving, trapping, restoration
Name | How the accessible name is computed
Announcements | What gets announced and when (aria-live regions)
AT behaviour | What JAWS / NVDA / VoiceOver will actually do with this
Gotchas | Known browser/AT support gaps and workarounds
Code | Reference implementation markupTwo templates, two artefact shapes, and the same file decides both. Each artefact type the agent ships has a locked structure in the file, so the work is consistent across the team.
The principles block closes the file. Native HTML before ARIA. Show the AT behaviour rather than cite the criterion. Progress over perfection. Pre-training does not give the agent any of that. It goes in the file, or it does not exist.
From one to one hundred agent team members
One file is a role. Roughly one hundred files, organised under seven domain chiefs plus a Chief AI Officer and a Chief of Staff, is an organisation. The shape repeats at every level. The scope, model, tool access, and position in the hierarchy are what change.
Every team agent declares its position from at least two sides. The lattice block inside the accessibility file is the view from where the agent sits. The Chief Customer Officer also names the agent from above, because cx-design and service-design under the CCO route work to accessibility every time they ship a journey map or a service blueprint.
### Experience Design
| Agent | Responsibility | You Ensure... |
|---|---|---|
| cx-design | Customer journey maps, CX measurement, VoC programmes, personas | We understand and continuously improve the experience |
| service-design | Service blueprints, journey maps, touchpoint audits | End-to-end service delivery is coherent and efficient |
| accessibility | WCAG audits, ARIA patterns, accessible component specs, remediation | Everything works for everyone, including people with disabilities |Accessibility's formal reporting line is the CDO. The CCO references the same agent because the design-team lattice crosses chief lines. Two files, two lenses, one agent. When they drift apart, work gets routed to an agent that does not acknowledge the task, or two agents claim the same output and produce conflicting versions. I have seen both. The fix is maintaining the relationship across every file that names the agent, not just one.
Two patterns shape how files coordinate at runtime. Hub-spoke routes work to one specialist at a time. Agent teams run specialists in parallel and merge outputs. My VUX article on managing AI agent teams covers both patterns in detail. Hub-spoke routing breaks when descriptions are too vague for the Orchestrator agent to classify accurately. Parallelisation breaks when scope boundaries overlap and two agents claim the same output. Both failures trace back to the same file. The description or the scope statement was wrong from the start.
The org-level problems sit downstream. Governance of the chief layer, what an AI-first C-suite looks like, and verifying the output of running agent teams are problems you can actually work on once the agent file is well-defined. Without a disciplined file shape, they stay stuck.
Key learnings
Four lessons from writing agent files at scale.
Scope that drifts from the description. An agent gets hired to review code. Over time it starts flagging product decisions and asking whether the feature is necessary. The description was never updated. The agent filled the gap with defaults. The fix is in the file.
Over-granting tools. The first version of several agents had Write access because it seemed like a superset that simplified setup. Granting write to an agent that only needs to read creates blast radius the day something goes wrong. A narrow tool list is also an audit trail, it tells you where the failure could not have happened.
No companion memory file. I noticed this early running the content agent without one. The same voice patterns kept needing correction across sessions because nothing was landing across runs. Create the file from day one, even if it starts empty.
Brief ambiguity as a proxy for agent ambiguity. The agents that needed the most mid-session corrections were the ones where I had not written a clear scope statement. Writing the file is clarifying my own thinking about the role. If the file is hard to write, the role is not yet clear.
The next agent you write is the next hire. The file is the role description and the performance agreement in one.
Read the full agent file
This article provides an overview. If you want to learn more, I've open-sourced the file on GitHub. If you want to fork the file, take this one as a starting point and bend it to whatever discipline you are codifying. The shape comes from the work, not from a template. Open the full accessibility.md file in a new tab and read it alongside the breakdown above.
Frequently Asked Questions
What does an agent.md file contain?
Two key blocks, but can be more. The frontmatter carries name, description, model, and tools. The prompt body carries the role statement, scope, behaviour rules, memory pointers, output format, and a usage-tracking line the org reads. Optional fields cover invocation hints and explicit memory paths. Each field is a design decision, not a configuration setting.
How is an agent file different from a system prompt?
A system prompt is the instruction set for one model in one app. Agent files are source-controlled artefacts you version, iterate, and route work to by name. Other agents read the file and decide whether to hand off. Where a system prompt instructs one model in one context, an agent file is a named teammate that the rest of the team can route to.
What model should I use for my agents?
The task decides, not the recommendation. On the Anthropic side, Sonnet handles repeatable, bounded work where cost matters and fast turnaround is part of the value. Opus handles judgement-intensive, long-context, orchestration-heavy work where the cost of a wrong answer is high. Leaving the field unset runs every agent on the default, which is rarely the right choice for the scope.
How do I scope the tool list for a new agent?
Minimum viable access. Give the agent the tools it needs and nothing more. Over-granting creates blast radius. Under-granting creates capability failures the agent cannot recover from. A read-only agent with Read and Grep has a different failure surface from one with Write and Bash.
When should an agent have a companion memory file?
My recommendation is always, even if it starts empty. The memory file holds lived behaviour rules, corrections, and patterns that accumulate through real use. Without it, every session restarts from the prompt baseline and the agent learns nothing across runs. The memory file is where the agent becomes more useful over time. Whether the agent actually learns from that memory is a separate question.
Created with Midjourney