AGENTS.md, SKILL.md, DESIGN.md: AI Instructions Now Have Three Layers

The Age of Structured AI Instructions Is Here

When developers first started working with AI coding agents, instructions were messy. Prompts lived in chat windows, scattered READMEs, or ad-hoc system messages. That era is ending fast. In April 2026, Google Labs released DESIGN.md — a machine-readable design system specification for AI agents — and with it, a surprisingly clean three-layer architecture for AI instruction has emerged.

We now have AGENTS.md for workflow and behavioral rules, SKILL.md for capability definitions, and DESIGN.md for visual and design constraints. Together, they represent the first real attempt at a standardized 'operating system' for how humans communicate intent to autonomous AI agents.

What Each Layer Does

AGENTS.md — The Behavioral Contract

AGENTS.md has been the fastest-adopted of the three specs. Jointly developed by OpenAI, Google, Sourcegraph, Cursor, and Factory, it was donated to the Linux Foundation in December 2025 and has since become something close to an industry standard.

At its core, AGENTS.md defines how an AI agent should behave within a given repository or project. Think of it as a behavioral contract: it specifies coding conventions, testing requirements, commit message formats, review protocols, and guardrails. If a team wants every AI-generated pull request to include unit tests and follow a specific branching strategy, AGENTS.md is where that gets encoded.

The file sits at the root of a repository and is designed to be both human-readable and machine-parseable. Its adoption has been rapid precisely because it solves an immediate pain point — without it, every AI agent interaction starts from zero context.

SKILL.md — The Capability Map

SKILL.md sits at the core of Anthropic's agent architecture and takes a fundamentally different approach. Rather than telling an agent how to behave, SKILL.md tells it what it can do.

A SKILL.md file defines discrete capabilities — parsing a CSV, calling a specific API, running a database migration — along with prerequisites, input/output schemas, and confidence levels. It is, in essence, a self-declaration of competence. When an orchestrating agent needs to delegate a subtask, it can scan available SKILL.md files to find the right sub-agent or tool for the job.

This matters enormously for multi-agent systems. As AI workflows grow more complex, with agents handing off tasks to other agents, having a standardized way to advertise and discover capabilities becomes critical infrastructure. Anthropic has positioned SKILL.md as that discovery layer.

DESIGN.md — The Visual Specification

Google Labs' DESIGN.md is the newest addition, and it fills a gap neither of the other two specs addresses: visual and design system constraints.

DESIGN.md allows teams to encode their design systems — color palettes, typography scales, spacing rules, component hierarchies, accessibility requirements — in a format AI agents can parse and enforce. It ships with a CLI validator (npx @google/design.md lint) that checks whether generated UI code complies with the declared design spec.

For front-end development workflows, this is a significant step forward. AI coding agents have historically struggled with design consistency. They can generate functional React components or HTML layouts, but matching a specific design system's spacing rhythm or color token usage has required extensive prompt engineering. DESIGN.md aims to make that automatic.

Why Three Layers, Not One?

The natural question is: why not put all of this in a single file? The answer comes down to separation of concerns — the same principle that drives good software architecture.

Each spec addresses a different audience and changes at a different cadence. AGENTS.md is primarily about team process and engineering culture. It changes when a team updates its workflow — say, switching from trunk-based development to feature branches. SKILL.md is about technical capability and changes when new tools or APIs become available. DESIGN.md is about visual identity and changes when a brand updates its design system.

Combining these into one monolithic file would create a maintenance nightmare. More importantly, the three-layer split enables composability. A single AI agent can read all three files simultaneously, but different agents can also specialize. A code-generation agent might primarily consume AGENTS.md and SKILL.md, while a UI-generation agent leans heavily on DESIGN.md.

The Emerging Stack in Practice

In practice, teams adopting all three specs are reporting meaningful improvements in AI agent output quality. The pattern typically looks like this:

1. AGENTS.md at the repo root defines global behavioral rules — linting standards, test coverage thresholds, documentation requirements.
2. SKILL.md files distributed across the project declare what each module or service can do, enabling intelligent task routing in multi-agent setups.
3. DESIGN.md lives alongside front-end code and ensures generated UI components match the project's visual language.

The result is a layered context system that gives AI agents far richer understanding of a project than any single prompt or README could provide.

Industry Alignment — and Tensions

The fact that these three specs come from three different organizations — the Linux Foundation (originally OpenAI and allies), Anthropic, and Google — raises both opportunities and concerns.

On the positive side, the specs are complementary rather than competing. They occupy distinct niches and can coexist without conflict. Early integrations in tools like Cursor, Windsurf, and VS Code's Copilot extensions already support reading multiple spec files from a project.

On the other hand, there is no unified governance body overseeing all three. AGENTS.md benefits from Linux Foundation stewardship, lending it institutional credibility and a clear contribution process. SKILL.md remains closely tied to Anthropic's ecosystem, and DESIGN.md is currently a Google Labs project with no announced plans for independent governance.

This fragmentation could become problematic if the specs begin to overlap or if vendors start extending them in incompatible ways. The developer tooling community has already begun calling for a unified 'AI Context Specification' umbrella — though no formal effort has materialized yet.

What This Means for Developers

For individual developers and engineering teams, the practical takeaway is straightforward: start adopting these specs now, even if incrementally.

AGENTS.md is the most mature and broadly supported — adding one to your repository today will immediately improve AI agent interactions across most major tools. SKILL.md is most valuable if you are building or orchestrating multi-agent workflows, particularly within Anthropic's Claude ecosystem. DESIGN.md is worth adopting if your team does significant front-end work and struggles with AI-generated UI consistency.

The learning curve is minimal. All three specs use Markdown-based formats designed for human readability. The investment is primarily in thinking clearly about your project's rules, capabilities, and design constraints — which is valuable engineering work regardless of AI.

Looking Ahead

The emergence of three distinct instruction layers for AI agents signals a broader maturation of the AI-assisted development ecosystem. We are moving past the era of 'just prompt it and hope' into one where AI agents operate within well-defined, machine-readable frameworks.

The next frontier is likely dynamic spec generation — AI agents that can write and update their own AGENTS.md, SKILL.md, and DESIGN.md files based on observed project patterns. Several startups are already exploring this space.

There is also the question of whether this three-layer pattern extends beyond software development. Could similar spec files govern AI agents in legal document review, financial analysis, or creative production? The underlying principle — separating behavioral rules, capability declarations, and output constraints — is domain-agnostic.

For now, the developer community has a clear and practical framework for communicating with AI agents. AGENTS.md, SKILL.md, and DESIGN.md may not be the final answer, but they represent the most coherent instruction architecture we have seen yet. And in a world where AI agents are writing an increasing share of production code, that coherence matters enormously.