AGENTS.md, SKILL.md, DESIGN.md: How AI Instructions Split into Three Layers
AGENTS.md, SKILL.md, DESIGN.md: How AI Instructions Split into Three Layers
AGENTS.md, SKILL.md, DESIGN.md：AI 指令如何分化为三个层级
In April 2026, Google Labs released a spec called DESIGN.md. It’s a design system specification readable by AI agents, packaged with a CLI validator: npx @google/design.md lint.
2026 年 4 月，Google Labs 发布了一项名为 DESIGN.md 的规范。这是一种可供 AI Agent 读取的设计系统规范，并附带了一个 CLI 验证工具：npx @google/design.md lint。
With DESIGN.md in the picture, we now have three different file types for instructing AI agents. AGENTS.md has been spreading as an industry standard since 2025 (jointly developed by OpenAI, Google, Sourcegraph, Cursor, and Factory; donated to the Linux Foundation in December 2025). SKILL.md sits at the core of Anthropic’s Claude Skills. And now DESIGN.md. The three handle different concerns and don’t overlap. 随着 DESIGN.md 的出现，我们现在有了三种用于指导 AI Agent 的不同文件类型。AGENTS.md 自 2025 年起已作为行业标准普及（由 OpenAI、Google、Sourcegraph、Cursor 和 Factory 联合开发，并于 2025 年 12 月捐赠给 Linux 基金会）。SKILL.md 则是 Anthropic Claude Skills 的核心。现在又有了 DESIGN.md。这三者处理不同的关注点，互不重叠。
This article is for developers using coding agents like Claude Code, Cursor, or Codex in their work, and for tech leads operating natural-language instruction files like CLAUDE.md and style guides. If your team is doing Spec-Driven Development (SDD), this should also reach you. What I want to lay out is two things: how AI instructions are starting to split across three layers — behavior, individual tasks, and visual appearance — and how that connects with SDD as a parallel movement. 本文面向在工作中通过 Claude Code、Cursor 或 Codex 等编码 Agent 进行开发的工程师，以及维护 CLAUDE.md 和风格指南等自然语言指令文件的技术负责人。如果你的团队正在实践规范驱动开发（Spec-Driven Development, SDD），那么这篇文章也与你息息相关。我想阐述两点：AI 指令是如何开始分化为行为、具体任务和视觉外观这三个层级的，以及这如何与 SDD 这一并行趋势相联系。
The Old Pattern: Natural-Language Documents
旧模式：自然语言文档
A few years into the ChatGPT era, most engineers have written some form of “rules I want the AI to follow” in a Markdown file. CLAUDE.md, styleguide.md, CONTRIBUTING.md, internal coding conventions. The locations vary, but the format is roughly the same: unstructured natural language. 进入 ChatGPT 时代几年后，大多数工程师都在 Markdown 文件中编写过某种形式的“我希望 AI 遵循的规则”。无论是 CLAUDE.md、styleguide.md、CONTRIBUTING.md 还是内部编码规范，位置虽各不相同，但格式大致相同：非结构化的自然语言。
A writing-style-guide.md file I’ve been building over the past few months is a typical example. It’s a style guide I use when writing technical articles with Claude — a list of patterns common in AI-generated text, written down as forbidden phrases. By making Claude Desktop read it every session, the tone of my output stays consistent. It’s part of a personal repository (ikenyal-ai-agents) I use as the harness for my business automation agents — the one I covered in my previous post. 我过去几个月一直在构建的 writing-style-guide.md 文件就是一个典型例子。这是我在用 Claude 撰写技术文章时使用的风格指南——一份记录了 AI 生成文本中常见模式的列表，并将其列为禁止短语。通过让 Claude Desktop 在每次会话中读取它，我输出内容的语调保持了一致。它是我个人仓库（ikenyal-ai-agents）的一部分，我用它作为业务自动化 Agent 的框架——这正是我上一篇文章中提到的内容。
The file contains roughly 150 lines: rules like “don’t use em dashes,” “avoid invitations like ‘let’s try…!’,” “drop AI-style preambles like ‘what’s interesting is…’.” The same repository has 15 instruction files under agents/, organized by team and role: executive-assistant.md, sre-support.md, qa-support.md, accounting.md. Each describes “the assumptions to operate under as this role” in plain natural language. 该文件包含约 150 行内容：例如“不要使用破折号”、“避免使用‘让我们试试……！’之类的邀请语”、“删掉‘有趣的是……’之类的 AI 式开场白”。同一个仓库在 agents/ 目录下还有 15 个指令文件，按团队和角色组织：executive-assistant.md、sre-support.md、qa-support.md、accounting.md。每个文件都用纯自然语言描述了“作为该角色应遵循的操作假设”。
This approach has clear benefits. You can articulate tone, stance, and implicit rules. New team members can read the files and pick up the expectations. With CLAUDE.md, Claude Code reads it every session, so persona-level instructions land consistently. 这种方法有明显的优势。你可以清晰地表达语调、立场和隐性规则。新团队成员可以阅读这些文件并掌握预期。通过 CLAUDE.md，Claude Code 会在每次会话中读取它，因此角色层面的指令能够得到一致的执行。
There are limits, too. First, validation falls on humans. Whether a rule was followed or not gets decided by a human reading the output. Second, individual judgment leaks in. “Write politely” means different things to different reviewers. The third limit is the actual subject of this article. Rules that are formally verifiable (forbidden phrases, em-dash usage, specific pattern matches) and rules that require judgment (tone, structural choices, how to open with empathy) sit in the same file. So even the verifiable parts end up depending on human review. That’s the problem the three new file types are addressing. 但它也有局限性。首先，验证工作依赖于人类。规则是否被遵循，需要人类阅读输出结果来判断。其次，个人主观判断会介入。“写得礼貌点”对不同的审核者来说意味着不同的含义。第三个局限性正是本文的主题：可形式化验证的规则（禁止短语、破折号用法、特定模式匹配）与需要主观判断的规则（语调、结构选择、如何以共情方式开场）混杂在同一个文件中。因此，即使是可验证的部分，最终也依赖于人工审核。这正是这三种新文件类型试图解决的问题。
New Type 1: How DESIGN.md (Google Labs) Specifies Visual Appearance
新类型 1：DESIGN.md (Google Labs) 如何规范视觉外观
On April 10, 2026, Google Labs published the DESIGN.md specification at google-labs-code/design.md. As of early May, the repo has over 11,000 stars. It’s the reference implementation for Google Stitch (stitch.withgoogle.com), an AI-driven UI generation product. 2026 年 4 月 10 日，Google Labs 在 google-labs-code/design.md 发布了 DESIGN.md 规范。截至 5 月初，该仓库已获得超过 11,000 颗星。它是 Google Stitch (stitch.withgoogle.com) 的参考实现，这是一个 AI 驱动的 UI 生成产品。
What DESIGN.md covers is the design system specification. You write machine-readable design tokens in YAML at the top of the file (colors, typography, spacing, components), and human-readable design intent in the Markdown body underneath. Both live in the same file. DESIGN.md 涵盖的是设计系统规范。你在文件顶部用 YAML 编写机器可读的设计令牌（颜色、排版、间距、组件），并在下方的 Markdown 正文中编写人类可读的设计意图。两者共存于同一个文件中。
The headline feature of this format is the CLI validator that ships with it. npx @google/design.md lint DESIGN.md. This checks token reference integrity, WCAG contrast ratios, and structural rule compliance, returning the result as JSON. Wire it into CI and you can verify design system consistency on every pull request. There’s also a diff command that compares two DESIGN.md files and returns token-level changes in a structured form. Design system version control — historically a manual process — gains a verifiable layer.
这种格式的重头戏是随附的 CLI 验证工具：npx @google/design.md lint DESIGN.md。它会检查令牌引用的完整性、WCAG 对比度以及结构规则的合规性，并以 JSON 格式返回结果。将其接入 CI，你就可以在每次 Pull Request 时验证设计系统的一致性。此外还有一个 diff 命令，可以比较两个 DESIGN.md 文件并以结构化形式返回令牌层级的变更。设计系统版本控制——历史上一直是一个手动过程——从此获得了一个可验证的层级。
For Japanese UIs, the Google Labs spec alone falls short. It doesn’t define the typography requirements specific to Japanese (CJK font fallback chains, line height, letter-spacing, kinsoku shori, mixed typesetting). The gap is filled by kzhrknt/awesome-design-md-jp, which publishes Japan-localized DESIGN.md files for over 10 services including Apple Japan, SmartHR, freee, note, MUJI, Mercari, LINE, and Toyota. For Japanese products, using both the Google Labs spec and the Japan edition together is the practical approach. 对于日语 UI 而言，仅靠 Google Labs 的规范是不够的。它没有定义日语特有的排版要求（中日韩字体回退链、行高、字间距、禁则处理、混合排版）。这一空白由 kzhrknt/awesome-design-md-jp 填补，该项目为包括 Apple Japan、SmartHR、freee、note、MUJI、Mercari、LINE 和 Toyota 在内的 10 多项服务发布了日语本地化的 DESIGN.md 文件。对于日本产品，同时使用 Google Labs 规范和日本版规范是务实的方法。
What DESIGN.md carries is the design system that used to be scattered across Figma files and style guide PDFs, now consolidated into a single file with both machine-readable and human-readable parts. Think of it as the spec foundation that lets AI agents generate UIs with a consistent look every time. DESIGN.md 承载的是过去散落在 Figma 文件和风格指南 PDF 中的设计系统，现在将其整合到一个既包含机器可读部分又包含人类可读部分的单一文件中。可以将其视为一种规范基础，让 AI Agent 每次都能生成外观一致的 UI。
New Type 2: How SKILL.md (Anthropic) and AGENTS.md Specify Behavior
新类型 2：SKILL.md (Anthropic) 和 AGENTS.md 如何规范行为
While DESIGN.md covers “appearance,” SKILL.md and AGENTS.md cover “behavior” — defining what the agent is trying to do, how it should proceed, and what it must not do. 如果说 DESIGN.md 涵盖的是“外观”，那么 SKILL.md 和 AGENTS.md 涵盖的就是“行为”——定义 Agent 试图做什么、应该如何进行，以及绝对不能做什么。