Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (84 loc) · 6.22 KB

CONTRIBUTING.md

File metadata and controls

129 lines (84 loc) · 6.22 KB

Contributing to Accessibility Agents

Thank you for considering a contribution. This is a community-driven project, and every improvement to these agents helps developers ship more inclusive software for blind and low vision users - and everyone else who depends on accessible design.

A sincere thanks goes out to Taylor Arndt and Jeff Bishop for leading the charge in building this project. Now we want more contributors to help us make more magic. Whether you are a developer, accessibility specialist, screen reader user, or someone who just cares about inclusive software - your contributions are welcome here.

Ways to Contribute

Report agent gaps

The most valuable contributions are agent gap reports - cases where an agent missed something, gave wrong advice, or suggested unnecessary ARIA. These reports directly improve agent instructions. Use the Agent Gap issue template.

Improve agent instructions

Each agent is a Markdown file with a system prompt. If you know a pattern an agent should catch, or a rule it enforces incorrectly, open a PR with the fix. Agent files live in:

  • .claude/agents/ - Claude Code agents
  • .github/agents/ - GitHub Copilot agents

When updating an agent, update both the Claude Code and Copilot versions to keep them in sync.

Add framework-specific patterns

The agents are framework-agnostic by default. If you work with React, Vue, Svelte, Angular, or another framework and know accessibility pitfalls specific to it, those patterns are welcome additions to the relevant agent instructions.

Fix installer or update scripts

The install, update, and uninstall scripts support macOS and Windows. Bug fixes and improvements are welcome, especially for edge cases on systems we have not tested.

Improve documentation

Clearer docs, better examples, typo fixes - all welcome.

How to Submit a PR

  1. Fork the repo
  2. Create a branch from main (git checkout -b my-fix)
  3. Make your changes
  4. Test on your system (run the installer, verify agents load)
  5. Open a PR with a clear description of what changed and why

Windows: Enable Symlinks

This repo uses symlinks inside claude-code-plugin/ to avoid duplicating docs and templates. Git on Windows defaults to core.symlinks=false, which converts symlinks to text stub files. To get real symlinks:

  1. Enable Developer Mode in Windows Settings (Settings > System > For developers).

  2. Clone with symlinks enabled:

    git clone -c core.symlinks=true https://github.com/Community-Access/accessibility-agents.git

    Or set it globally: git config --global core.symlinks true

Testing Requirements

⚠️ CRITICAL: Always test contributions with the latest versions of all relevant tools. Agent behavior depends on current platform APIs, model capabilities, and bug fixes.

Before submitting a PR, verify you are using:

  • VS Code: Latest stable release
  • GitHub Copilot Extensions: Latest versions (both Copilot and Copilot Chat)
  • Claude Code CLI: Latest version (claude code update)
  • Claude Desktop: Latest version (auto-updates enabled)
  • Gemini CLI: Latest version
  • Codex CLI: Latest version
  • Node.js: v18.0.0 or higher (for CLI tools like axe-core, pa11y)

Version checks before testing:

code --version          # VS Code
claude code --version   # Claude Code CLI
node --version         # Node.js
npm list -g --depth=0  # Global npm packages

Why this matters:

  • Platform API changes affect agent tool use and capabilities
  • New VS Code/Copilot features (browser tools, screenshot analysis) directly impact agent effectiveness
  • Model updates change response quality and context handling
  • Bug fixes in platform tooling resolve edge cases

If you encounter unexpected behavior, update all tools first. Include your tool versions in PR descriptions when reporting issues.

Source Verification Checklist

When your PR updates platform behavior, settings, release notes, or integration guidance, include source verification so docs remain current and authoritative.

Before submitting, confirm:

  • You linked at least one official source for each platform-specific claim.
  • Settings keys are validated against current vendor docs.
  • Release-specific statements include the release notes link.
  • New prompts/agents/skills counts match repository inventory.
  • If guidance changed due to a platform update, note what changed in the PR description.

Preferred primary sources:

  • VS Code updates: https://code.visualstudio.com/updates
  • VS Code Copilot customization: https://code.visualstudio.com/docs/copilot/customization
  • GitHub Copilot docs: https://docs.github.com/copilot
  • W3C WCAG 2.2: https://www.w3.org/TR/WCAG22/

Suggested PR note template:

Source verification:
- Claim: <what changed>
 Source: <official URL>
 Verified on: <YYYY-MM-DD>

Guidelines

  • Keep agent instructions focused. Each agent owns one domain. Do not add ARIA rules to the contrast agent or focus management to the forms agent.
  • Match the existing style. Read the agent you are modifying before making changes. Follow the same structure and tone.
  • Update both platforms. If you change a Claude Code agent, update the matching Copilot agent too (and vice versa).
  • Test your changes. Install the agents and verify they work. If you changed an agent, try invoking it with a prompt that exercises the change.
  • One concern per PR. A PR that fixes one agent gap is easier to review than one that changes five agents and the installer.

Code of Conduct

This project follows a Code of Conduct. By participating, you agree to uphold it. Be kind, be respectful, and remember that accessibility is about including everyone.

Questions?

Open a discussion or file an issue. No question is too basic. We especially welcome questions and feedback from blind and low vision users, screen reader users, and others with direct experience of accessibility barriers - your perspective makes these agents more effective for the people who need them most.