DEV Community: Felipe Arriaga Carriço

Not every skill is a capability

Felipe Arriaga Carriço — Fri, 07 Aug 2026 17:26:04 +0000

Nobody installs the speed limit.

You can add a GPS to your car, parking sensors, a backup camera, that thing that beeps when someone's in your blind spot. Those are capabilities: the car does something it couldn't do before, and each one matters exactly when you need it. Nobody turns on the backup camera to drive down a highway.

Seatbelts and speed limits don't work that way. They aren't capabilities, they're constraints — they don't give you power, they take away options. And the difference becomes obvious the moment you imagine the alternative:

A seatbelt that fastens when you ask for safety isn't a seatbelt. It's a well-meaning ornament.

I kept that distinction because it explains a discomfort I couldn't name.

Skills, and the verb holding them up

There's an open format called Agent Skills, created by Anthropic and adopted by around forty AI coding tools. The idea is good and I'm a fan: a skill is a folder with an instructions file, plus optional references and scripts. The agent reads only the name and description of each skill at startup, and loads the full contents when the task matches that description.

It's well-designed context economy — an agent can have a hundred specialities on hand without carrying a hundred manuals at all times.

Notice the verb holding the mechanism up: matches.

That works perfectly for capabilities. "How to generate a PDF", "how to write an integration test", "how to format a deck". These answer how do I do X, and they only need to exist while someone is doing X.

The second kind of knowledge

But there's a second kind of knowledge we've been packaging in the same format without noticing it's a different animal. The question it answers isn't how do I do X. It's what may I never do, whatever X turns out to be.

Accessibility is like that. So is security. So is data protection. They aren't abilities the agent reaches for when the subject comes up; they're conditions that hold before the subject exists.

And the problem with treating them as capabilities is arithmetic, not philosophical: if the rule only loads when someone asks for accessibility, it arrives after the interface is built.

Accessibility that has to be asked for is already late. That's the same old audit, now with a markdown file in the middle.

This isn't a comfortable desk hypothesis. The WebAIM Million analyses a million home pages every year, and in 2026 it recorded the first regression in six years: 95.9% with detectable WCAG failures, at the exact moment AI agents began writing much of the world's interface code.

The models learned from the web that exists, and the web that exists is inaccessible. Their statistical default isn't neutral; it has a direction, and the direction is downhill. Against a slope like that, arriving at the right moment isn't an implementation detail. It's the whole thing.

The convergence, and the one place it breaks

I've spent the last few months building an open-source project called A11Y.md that does exactly that: a context file that injects accessibility rules into the agent before the first line of code.

fecarrico / A11Y.md

A context system for building accessible software by default — for developers and AI, with enforceable rules aligned to WCAG.

🇧🇷 Read in Portuguese: ./README.pt-BR.md

Project A11Y.md

The Persistent Context System for Accessibility

A11Y.md is not a guideline. It is an accessibility validation protocol and a persistent context architecture for developing accessible software with AI. It is designed to integrate with AI agent systems (Cursor, Claude, Copilot) to ensure certifiable compliance from genesis.

We treat .gitignore, eslint, and CLAUDE.md as canonical truths in our repositories. But why isn't accessibility canonical? A11Y.md translates accessibility rules into a portable governance layer: a platform-agnostic normative core (POUR, compliance profiles, severity, governance) with mature web references and a native translation layer (iOS, Android, React Native, Flutter). Instead of generic coding advice, it forces any coding agent to strictly adhere to WCAG 2.2 AA and ADA standards from the very first line of generated UI code.

⚡ Core

…

View on GitHub

When I finally sat down with the Agent Skills specification, I got a slightly funny shock — the architecture I'd designed was the same one, down to the folder names. References loaded on demand, instructions at the root, scripts alongside. Independent convergence, which is usually the best news a project can get: it means the design wasn't stubbornness, it was the answer the problem was asking for.

And that's when the discomfort came into focus. My project fits the format entirely, except on one point: it can't wait for the task to match. It has to be there while the agent still doesn't know what it's about to build, because that's precisely where the wrong decision gets made — the div that became a button, the input with no label, the modal that traps the keyboard.

None of those come from a task called "accessibility". They all come from a task called "build a signup form".

The ecosystem already knows. It just hasn't named it.

Here's the part I didn't expect to find when I read the specs closely. Every extension the clients have added moves activation in the restrictive direction — never the permanent one:

Client	Field they added	What it does
Cursor	`disable-model-invocation`	runs only when you type its name
Claude Code	`disable-model-invocation`	same
Claude Code	`paths`	narrows activation to matching files
The spec itself	six fields, none of them	keeps a skill loaded

Nobody added the reverse, because the reverse isn't a skill.

The prettiest proof is Cursor's migration tool, which converts old rules into the new format. It converts the dynamic ones — the rules that apply in certain situations. And it refuses to convert the ones marked always-apply, because those, in its own documentation's words:

retain explicit triggering conditions that differ from skill behavior

So always-on context does exist. It just lives outside the portable format, in each tool's proprietary layer — the rule files you have to rewrite for every client you support. Which means today's authors choose between:

Portability — one skill, forty tools, one install.
Guaranteed presence — one rule file per client, N times over.

Constraints are precisely the case where that trade-off hurts most.

Two words where we have one

	Capability skills	Constraint skills
Answer	how do I do X	what may I never do
Activate	by subject	across a whole domain
How many	many, the more the better	few, or they stop being constraints
Failure mode	loads when it isn't needed	doesn't load when it is

A capability that stays quiet when nobody calls it is working correctly. A constraint that stays quiet is broken — and looks identical from the outside.

What you can do today

The good news is the format handles both. What doesn't handle both is the mental model of activation. And there's a practical workaround that fits in one line: write your constraint skill's description by domain, never by desire.

# By desire — guarantees absence at the moment that matters
description: Use when the user asks about accessibility.

# By domain — the rule exists before anyone thinks to ask
description: Use whenever creating or modifying any UI, component,
  or front-end code.

Change one sentence, change when the rule exists. It's a patch, and a good one — but still a patch on a model that assumes everything we package is an ability.

Where this goes

I'm not proposing a new standard, and I'm not complaining about the one we have. I adopted the format, it's good, and the industry just converged around it — Vercel, Amazon, Microsoft, OpenAI, Cursor and Google closed a packaging layer on top of it days ago.

When a space consolidates like that, arguing about vocabulary stops being pedantry and becomes infrastructure: the difference between "install the seatbelt when you want safety" and "the seatbelt comes fastened" is a design decision someone makes once and everyone inherits.

I took the question to the spec repository, where it belongs — discussion #484, if you'd like to argue with me there.

So, for the people building agents and the people writing specs: when the thing being packaged is a prohibition rather than an ability, is loading it on demand still the right call — or are we applying context economy exactly where it costs the most?

In the meantime, go check your skills' descriptions. That one line nobody reads is what decides whether the rule shows up before or after the damage.

A11Y.md: Accessibility before any prompt

Felipe Arriaga Carriço — Mon, 06 Jul 2026 20:49:01 +0000

And if accessibility wasn't something you simply validate, but something the system already knows?

If context defines AI behavior, then accessibility needs to be part of that DNA from the very first prompt.

This is the simple — and necessary — premise behind A11Y.md: a configuration file that acts as the accessibility “conscience” of your project, guiding code agents to follow inclusive standards automatically and organically.

Project A11Y.md

A context system for building accessible software by default — for developers and AI, with enforceable rules aligned to WCAG.

Inspired by the CLAUDE.md file model, it is not meant to be just another best practices guide or an infinite checklist, but rather a validation protocol and a persistent context architecture for AI agents that generate code.

A11Y.md is a common abbreviation for accessibility: between the “A” and the “Y”, there are 11 letters (ccessibilit). But there’s an interesting detail: it can also be read as “ally“. An ally. And that is exactly what this project sets out to be.

The discomfort: two parallel worlds

During a conversation about accessibility in the Community Lounge at the TDC Summit AI São Paulo 2026, where I am a coordinator, I perceived a chasm.

On one side, certification and legal compliance — necessary, but slow. On the other, vibe coding and AI generating interfaces at an absurd speed. The result?

We are scaling digital exclusion faster than ever.

The question has changed: Who is left out when the AI works, but isn’t accessible?

Reactive accessibility starts too late

Today, accessibility is treated as the final stage of the pipeline:

You design,
You develop (or the AI develops),
Then, you validate.

At this pace of agents and copilots, the error has already scaled before we even open the validator. If accessibility only enters at the end, it will never reach the speed of innovation.

From checklist to a context ally

We treat accessibility as a to-do list: Is there contrast? Is there a label? But anyone working with LLMs already understands the game: the model doesn't follow rules, it follows context. Without context, the AI improvises. And improvisation in accessibility is the recipe for exclusion.

If we don’t provide the base context, the AI will prefer the visually “beautiful” path over the functionally “inclusive” one.

What the audit reveals (real examples)

To understand the impact of missing context, see what happens in interfaces that “look” correct but are unoperable.

The following examples were generated from a recent project I worked on using Figma Make and Antigravity (Gemini 3 Flash).

The code blocks with errors were already present in the project, and the improvement suggestions were generated by using A11Y.md as a reviewer:

1. The fake button

It is common to see AI generating clickable elements using div. Visually it works, but in practice, you have created an element invisible to keyboard and screen readers.

The common error (works… for mouse users)

<div onClick={() => navigate('/components')}>
  Explore Components
</div>

The problem

This element:

Does not receive keyboard focus,
Does not respond to Enter or Space,
Is not announced as interactive by screen readers.

In other words: it is not a button; it only looks like one.

The contextualized correction

<button onClick={() => navigate('/components')}>
  Explore Components
</button>

Why this is better:

Native focus,
Automatic keyboard support,
Semantic recognition by assistive technologies.

You didn’t add accessibility. You just stopped breaking the browser’s default behavior.

2. Typography is not aesthetics, it’s access

“Minimalism” often demands an invisible price: legibility. Fonts that are too small may look elegant, until you try to read them in:

A low-light environment,
A phone in the sun,
Or with any level of low vision.

The error

<p className="text-[10px]">
  Important information, but unreadable.
</p>

The problem

Below 12px, you begin to significantly compromise readability. It's not a preference; it's a physiological limitation.

The correction:

<p className="text-xs">
  Legibility is not a detail, it's a condition of use.
</p>

Why this is better:

Maintains a functional minimum for reading,
Reduces cognitive effort,
Avoids relying exclusively on zoom or user adjustments.

If the layout needs to be dense, the solution is to improve hierarchy and contrast.

3. Silent forms

The error

<label>Email</label>
<input type="email" />

The problem

Screen readers allow direct navigation between form fields, ignoring surrounding content. When the input is not associated with the label, it loses its accessible name.

The user arrives at the field, but doesn’t know what it represents. Because for assistive technologies, visual proximity means nothing; only explicit relationships in the code matter.

The correction

<label htmlFor="email">Email</label>
<input id="email" type="email" />

Why this is better:

Creates an explicit semantic link,
Allows the field to be announced correctly,
Improves form navigation.

Here, it’s not a matter of “good practice,” but about interface comprehension.

4. Feedback no one hears

Modern interfaces are full of dynamic states: errors, successes, alerts. But there is one detail: not every visual change is perceived by assistive technologies.

The error

{error && (
  <div className="p-3 bg-red-100 text-red-700">
    {error}
  </div>
)}

The problem

The message appears on screen, but is not announced. For a screen reader, nothing happened.

The correction

{error && (
  <div role="alert" aria-live="assertive">
    {error}
  </div>
)}

Why this is better:

Immediately informs state changes,
Ensures errors are not overlooked,
Maintains consistency between what is seen and what is perceived.

The A11Y.md Paradigm

The point is not the isolated examples, but that they continue to happen because they depend on human memory in accelerated environments. A11Y.md proposes three pillars:

Human-Centric: Focus on the user’s real autonomy.
AI-Ready: Guidelines written to guide code agents.
Certifiable: Rules mapped directly to the WCAG 2.2 standard.

If the code agent (or your editor in Vibe Coding mode) already “reads” in the project context that it is forbidden to use div as a button or generate text below 12px, the error ceases to be an option.

AI won’t solve (alone) accessibility

Let’s be realistic: AI won’t “solve” accessibility. Accessibility is experience. It’s the look of someone who perceives colors, the touch of someone who navigates without a mouse, the listening of someone who depends on voice.

The human remains indispensable. A11Y.md does not replace us; it guarantees that the basics are not neglected so we can focus on what really matters: the exceptional human experience.

To use A11Y.md is simple:

Download the rules from the official Github repository: Copy the content from the /docs/pt-BR folder (or the English version as a good practice) to the root of your project repository.
Inject into the prompt: If you use Cursor, GitHub Copilot, Claude, or Antigravity, add to your global rules file (.cursorrules, GEMINI.md, or any other context system): “When developing interfaces, strictly follow the development rules defined in the A11Y.md file.”
Call it directly: You can also call A11Y.md at any time directly in your agent: “Analyze the project (which can be existing code or a Figma screen using MCP) using A11Y.md.”

By doing this, your development environment will know — from the beginning — that accessibility is a basic requirement in code generation.

An invitation to Open Source

A11Y.md is not just a file; it's a starting point. It can become an IDE plugin, a CI/CD pipeline, or a specialized agent. The project is open source (MIT license) because accessibility does not ask for permission; it asks for collaboration.

Accessibility cannot be a seal at the end of the process. It needs to be the restriction at the beginning.

Maybe the next step in accessibility is, finally, to become practical and accessible for those building the future, whether human or not.

References and inspirations

Using CLAUDE.md files: Customizing Claude Code for your codebase — Claude
ACCESSIBILITY.md— mneves75
a11y.md — RedwoodGraphQL
Antigravity Rules: Guide with AGENTS.md & Examples— Antigravity Codes
Original articule in Portuguese - Felipe A. Carriço