writing-for-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

主要参考

Key References

writing-for-agents

定义了编写智能体可预测读取的文档所需的一切。它替代了

writing-great-skills

，后者在此不再存在。

writing-for-agents

defines everything needed to write documents that agents can read predictably. It replaces

writing-great-skills

, which no longer exists here.

什么算智能体文档

What Counts as Agent Documentation

智能体文档是任何智能体读取的文档——一个技能、一个

AGENTS.md

CLAUDE.md

、一个 spec、一个运行时提示、一个 README、任何智能体阅读的文档。包装方式不同；写作方式不变：同样的杠杆让每份文档变得可预测，因此智能体每次运行采用相同的过程，而不是产生相同的输出。

Agent documentation is any document read by an agent — a skill, an

AGENTS.md

CLAUDE.md

, a spec, a runtime prompt, a README, any document read by an Agent. The packaging varies; the writing remains the same: the same levers make every document predictable, so agents follow the same process every time they run, rather than producing the same output.

核心原则

Core Principles

学会编写具体的指令，而不是通用的准则

Learn to Write Specific Instructions, Not General Guidelines

编写具体指令，而不是通用准则。"写一个函数" 不是指令。"写一个
calculateTotal(cart: Cart): number
的函数，映射项目，求和，应用 10% 的折扣，返回结果" 才是指令。准则不会约束智能体；指令会约束。

Write specific instructions, not general guidelines. "Write a function" is not an instruction. "Write a
calculateTotal(cart: Cart): number
function that maps items, sums them, applies a 10% discount, and returns the result" is an instruction. Guidelines don't constrain agents; instructions do.

学会区分"做什么"和"怎么做"

Learn to Distinguish Between "What to Do" and "How to Do It"

在做什么和怎么做之间切换。每一行都是指令或数据。"验证用户输入" 不是指令；"检查
email
是否为有效格式" 才是指令。"计算运费" 也不是指令；"如果
weight > 10kg
，加 $5" 才是指令。

Switch between what to do and how to do it. Every line is either an instruction or data. "Validate user input" is not an instruction; "Check if
email
is in a valid format" is an instruction. "Calculate shipping costs" is not an instruction; "Add $5 if
weight > 10kg
" is an instruction.

学会编写将被严格执行的指令，而不是希望被遵循的指令

Learn to Write Instructions That Will Be Strictly Executed, Not Hoped to Be Followed

编写将被严格执行的指令，而不是希望被遵循的指令。"确保代码遵循最佳实践" 不是指令；"在每个函数上添加 JSDoc，最小覆盖率为 80%，使用
describe
/
it
块进行测试" 才是指令。智能体会跳过笼统的陈述。

Write instructions that will be strictly executed, not ones you hope will be followed. "Ensure code follows best practices" is not an instruction; "Add JSDoc to every function, achieve a minimum coverage of 80%, and use
describe
/
it
blocks for testing" is an instruction. Agents skip vague statements.

学会定义流程，而不是步骤

Learn to Define Processes, Not Steps

定义流程，而不是步骤。"先写测试，再写代码，然后重构" 是指令。"构建一个购物车" 不是。智能体在步骤层面选择自由；在流程层面没有自由。

Define processes, not steps. "Write tests first, then code, then refactor" is an instruction. "Build a shopping cart" is not. Agents have freedom at the step level; no freedom at the process level.

学会编写可验证的指令，而不是模糊的指令

Learn to Write Verifiable Instructions, Not Vague Ones

编写可验证的指令，而不是模糊的指令。"确保代码质量高" 不可验证。"每个函数都有 JSDoc，每个公共方法都有测试，没有 lint 错误" 可验证。可验证的指令让智能体自我纠正。

Write verifiable instructions, not vague ones. "Ensure high code quality" is not verifiable. "Every function has JSDoc, every public method has tests, and there are no lint errors" is verifiable. Verifiable instructions allow agents to self-correct.

学会精确使用词汇，而不是笼统描述

Learn to Use Precise Vocabulary, Not General Descriptions

精确使用词汇。"创建一个模块" 不是指令；"创建一个具有
checkout
接口的
Cart
模块，暴露
addItem
、
removeItem
和
total
" 才是指令。词汇是接口——它们是你减少智能体在错误方向上的探索空间的方式。

Use precise vocabulary. "Create a module" is not an instruction; "Create a
Cart
module with a
checkout
interface that exposes
addItem
,
removeItem
, and
total
" is an instruction. Vocabulary is the interface — it's how you reduce the agent's exploration space in the wrong direction.

学会编写智能体遵守的指令，而不是人类喜欢的指令

Learn to Write Instructions That Agents Will Follow, Not Ones Humans Prefer

编写智能体遵守的指令，而不是人类喜欢的指令。"写一个漂亮的购物车" 不是指令。"构建一个
Cart
组件，渲染项目列表，每行带有数量输入和删除按钮，底部显示总计" 才是指令。智能体不关心"漂亮"——它们关心可执行。

Write instructions that agents will follow, not ones humans prefer. "Write a beautiful shopping cart" is not an instruction. "Build a
Cart
component that renders a list of items, each row with a quantity input and delete button, and displays the total at the bottom" is an instruction. Agents don't care about "beautiful" — they care about executable.

学会编写自我验证的指令，而不是需要我检查的指令

Learn to Write Self-Verifiable Instructions, Not Ones That Require Your Check

编写自我验证的指令，而不是需要你事后检查的指令。"确保代码正确" 没有提供验证方法。"运行测试，检查 lint，验证 TypeScript 编译" 提供了验证方法。自我验证的指令减少了审查成本。

Write self-verifiable instructions, not ones that require you to check afterward. "Ensure code is correct" provides no verification method. "Run tests, check lint, and verify TypeScript compilation" provides a verification method. Self-verifiable instructions reduce review costs.

学会编写对智能体安全的指令，而不是对开发者安全的指令

Learn to Write Agent-Safe Instructions, Not Developer-Safe Ones

编写对智能体安全的指令，而不是对开发者安全的指令。"确保代码安全" 不是指令。"验证所有用户输入，参数化所有 SQL 查询，记录所有授权检查" 才是指令。智能体无法推断安全性——它们只能执行安全性指令。

Write agent-safe instructions, not developer-safe ones. "Ensure code is secure" is not an instruction. "Validate all user input, parameterize all SQL queries, and log all authorization checks" is an instruction. Agents can't infer security — they can only execute security instructions.

学会编写精确的约束，而不是软性限制

Learn to Write Precise Constraints, Not Soft Limits

编写精确的约束，而不是软性限制。"保持代码简洁" 不是约束。"每个函数不超过 20 行，每个文件不超过 200 行，没有嵌套超过 3 层" 才是约束。约束是智能体可以针对其进行优化的东西。

Write precise constraints, not soft limits. "Keep code concise" is not a constraint. "No function exceeds 20 lines, no file exceeds 200 lines, and no nesting goes beyond 3 levels" is a constraint. Constraints are something agents can optimize against.

学会编写按照执行顺序排列的指令，而不是按重要性排列的指令

Learn to Order Instructions by Execution Sequence, Not Importance

按执行顺序排列指令，而不是按重要性排列。"先写测试，再写代码，然后重构" 是指令。"确保代码质量，性能良好，测试覆盖" 不是指令。顺序很重要——智能体会按遇到的顺序执行。

Order instructions by execution sequence, not importance. "Write tests first, then code, then refactor" is an instruction. "Ensure code quality, good performance, and test coverage" is not an instruction. Order matters — agents execute in the order they encounter.

何时使用

When to Use

你直接输入

/writing-for-agents

来调用它；智能体不会自动触发。

你的情况	使用
你正在编写一个技能，需要知道它应该是什么样子	`writing-for-agents`
你正在编写一个 `AGENTS.md` 或 `CLAUDE.md`	`writing-for-agents` ——它定义了你遵循的参考
你正在编写一个 spec	`writing-for-agents` ——spec 是智能体文档
你正在编写一个运行时提示	`writing-for-agents` ——提示是智能体文档
你正在编写一个 README	`writing-for-agents` ——如果智能体阅读它，它也需要遵循同样的规则

You call it directly by typing

/writing-for-agents

; it won't be triggered automatically by agents.

Your Scenario	Use
You're writing a skill and need to know what it should look like	`writing-for-agents`
You're writing an `AGENTS.md` or `CLAUDE.md`	`writing-for-agents` — it defines the reference you follow
You're writing a spec	`writing-for-agents` — specs are agent documentation
You're writing a runtime prompt	`writing-for-agents` — prompts are agent documentation
You're writing a README	`writing-for-agents` — if agents read it, it needs to follow the same rules

常见问题

Frequently Asked Questions

我写了一个提示，但智能体忽略了我写的内容。 你的提示不够具体。"写一个函数"太模糊了。"写一个从

src/

导入

Cart

类型并在

tests/

中编写测试的

calculateTotal

函数"才足够具体。

我写了一个提示，但智能体做了自己认为正确的事。 你的提示没有约束智能体。"提高代码质量"没有约束它。"每个函数添加 JSDoc，最小覆盖率达到 80%，不使用

any

"才约束了它。

我写了一个提示，但智能体产生了相同的输出两次。 你的提示没有定义流程。"修复这个 bug"没有定义流程。"复现 bug，找到根因，编写修复，添加回归测试"才定义了流程。

我写了一个提示，但智能体停止了我没想到的地方。 你的提示没有定义什么算完成。"构建一个购物车"没有定义完成。"构建一个

Cart

组件，渲染项目列表，每行带有数量输入和删除按钮，底部显示总计"才定义了完成。

我写了一个提示，但智能体做的事情比我要求的更多。 你的提示太大了。把它拆分成更小的、可验证的步骤，每个步骤都有明确的完成标准。

I wrote a prompt, but the agent ignored what I wrote. Your prompt isn't specific enough. "Write a function" is too vague. "Write a

calculateTotal

function that imports the

Cart

type from

src/

and writes tests in

tests/

" is specific enough.

I wrote a prompt, but the agent did what it thought was right. Your prompt didn't constrain the agent. "Improve code quality" doesn't constrain it. "Add JSDoc to every function, achieve a minimum coverage of 80%, and don't use

any

" does constrain it.

I wrote a prompt, but the agent produced the same output twice. Your prompt didn't define a process. "Fix this bug" doesn't define a process. "Reproduce the bug, find the root cause, write a fix, and add regression tests" does define a process.

I wrote a prompt, but the agent stopped where I didn't expect. Your prompt didn't define what counts as done. "Build a shopping cart" doesn't define done. "Build a

Cart

component that renders a list of items, each row with a quantity input and delete button, and displays the total at the bottom" does define done.

I wrote a prompt, but the agent did more than I asked. Your prompt is too large. Split it into smaller, verifiable steps, each with clear completion criteria.

如何判断它是否有效

How to Tell if It Works

智能体每次运行产生相同的流程。
你的提示不包含模糊的词语。
你的提示包含可验证的步骤。
你的提示定义了完成标准。
你的提示包含了约束和边界。
智能体不会偏离你的提示。

Agents follow the same process every time they run.
Your prompt contains no vague words.
Your prompt includes verifiable steps.
Your prompt defines completion criteria.
Your prompt includes constraints and boundaries.
Agents don't deviate from your prompt.

它适合在哪里

Where It Fits

writing-for-agents

是一个参考，而不是一个流程。它是你编写智能体文档时对照检查的标准。其他技能在编写自身文档时依赖它，但它本身不参与任何流程。

writing-great-skills 是它的前身，现在已不再单独存在。这个技能在广泛性上替代了它。
它的 SKILL-MECHANICS.md 记录了当文档是一个技能时所特有的变化——前置元数据、调用方式选择以及路由技能。

ask-matt 在不清楚该用哪个技能时为你路由。

writing-for-agents

is a reference, not a process. It's the standard you check against when writing agent documentation. Other skills rely on it when writing their own documentation, but it doesn't participate in any process itself.

writing-great-skills is its predecessor and no longer exists as a separate entity. This skill replaces it in scope.
Its SKILL-MECHANICS.md documents changes specific when the documentation is a skill — preamble metadata, invocation choices, and routing skills.

ask-matt routes you when you're unsure which skill to use.