Add Markdown Accessibility Assistant agent

[v-rperez030]

Adds a new agent that helps improve the accessibility of existing markdown files based on GitHub's 5 tips for making your GitHub profile page accessible.

The agent focuses on five key areas:

• Making links descriptive
• Adding meaningful alt text to images
• Using proper heading hierarchy
• Writing in plain language
• Structuring lists properly and using emoji thoughtfully

It integrates markdownlint for structural validation and flags alt text/plain language changes for human review before applying them.

Changes:

• agents/markdown-accessibility-assistant.agent.md — new agent definition
• docs/README.agents.md — auto-generated update via npm run build

[Copilot]

Pull request overview

Adds a new custom agent to the repository’s agents/ catalog to help users improve the accessibility of existing Markdown documents, aligned to GitHub’s “5 tips for making your GitHub profile page accessible”.

Changes:

• Added a new agent definition: Markdown Accessibility Assistant
• Updated the auto-generated agents index to include the new agent

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
agents/markdown-accessibility-assistant.agent.md	New agent definition with workflow guidance and markdownlint integration for accessibility-focused Markdown improvements.
docs/README.agents.md	Auto-generated index update to list the new agent and its install links.

[aaronpowell]

Given that #797 also exists, and is functionally the same, is there value in having a custom agent?

It may actually be better to convert it all to a skill (the instructions file as well) so that it can be invoked with a slash command or the agent can discover and use it as required.

[v-rperez030]

Hi @aaronpowell,

Thank you so much for looking into this.

#797 is an instructions file that works in the background when an agent needs to create new Markdown content, as well as during code reviews on GitHub.com. It has already proven to be helpful in my work.

I initially thought of creating a skill, but in all the documentation I reviewed, I could not confirm whether skills participate in code reviews on GitHub.com. If the code review agent can use skills, that would definitely be a reason to turn it into a skill, because it could also be invoked to review a specific file.

If we turn #768 into a skill, we would lose the turn-by-turn conversation with a persistent identity, as well as the teaching aspect I had in mind for it.

Right now, #797 works in the background to guide agents when generating new Markdown content and during code reviews. #768, on the other hand, can do more in-depth reviews of specific files and answer questions about Markdown accessibility. Another difference is that the agent in #768 uses a linter and a more detailed workflow for more thorough reviews.

I see them as playing different roles, but I also understand there is significant overlap between the two. If you believe a skill combining the two would accomplish the same goals, I am happy to make the change.

[aaronpowell]

I initially thought of creating a skill, but in all the documentation I reviewed, I could not confirm whether skills participate in code reviews on GitHub.com. If the code review agent can use skills, that would definitely be a reason to turn it into a skill, because it could also be invoked to review a specific file.

That's a really good point in where an instructions file is going to provide value over the top of a skill, but let me follow up with the Copilot Code Review team to see if maybe it's not a missing bit of docs.

The reason why I ask the question in general is that I'm wanting to reduce the number of overlapping items we have in this repo as it can cause confusion as to when you should use A over B.

You mention that the turn-by-turn conversation with an agent was part of what led you to create it as an agent in the first place, but I challenge you on whether that wouldn't be available still if it was a skill? I feel like you would actually see it leveraged more as a skill since the agent could choose to use the skill during its run rather than having to have you initially started the conversation from a custom agent. I'm thinking of the workflow of where you've done a refactor of part of an application and now you need to update the relevant docs, and you enter the prompt "now update the docs/feature.md based off the work". A skill can be picked up in that and applied, whereas if it's a custom agent you have to have opted into it prior to sending that prompt, and if it's in an existing conversation, it can be easy to forget that you need to switch agents.