name: agents-md
description: This skill should be used when the user asks to “create AGENTS.md”, “update AGENTS.md”, “maintain agent docs”, “set up CLAUDE.md”, or needs to keep agent instructions concise. Enforces research-backed best practices for minimal, high-signal agent documentation.
risk: critical
source: community
维护 AGENTS.md
AGENTS.md 是面向代理的权威文档。保持简洁——代理足够能干，不需要手把手的指导。目标是少于 60 行；绝不超过 100 行。随着文档长度增加，执行指令的质量会下降。
何时使用
- 用户请求创建、更新或审计
AGENTS.md或CLAUDE.md。 - 该项目需要从实际工具链和仓库布局中提炼出的简明、高信号的代理指令。
- 现有的代理文档太长、重复，或者偏离了实际项目的规范。
文件设置
- 在项目根目录创建
AGENTS.md - 创建符号链接：
ln -s AGENTS.md CLAUDE.md
写作前
分析项目以了解哪些内容属于该文件：
- 包管理器— 检查锁文件（
pnpm-lock.yaml、yarn.lock、package-lock.json、uv.lock、poetry.lock） - Linter/格式化程序配置— 查找
.eslintrc、biome.json、ruff.toml、.prettierrc等。（不要在 AGENTS.md 中重复这些内容） - CI/构建命令— 检查
Makefile、package.json脚本以及 CI 配置中的标准命令 - Monorepo 指示器— 检查
pnpm-workspace.yaml、nx.json、Cargo workspace 或子目录中的package.json文件 - 现有的约定— 检查现有的 CONTRIBUTING.md、docs/ 或 README 模板
写作规则
- 标题 项目符号— 无段落
- 代码块— 用于命令和模板
- 仅作参考，不要嵌入— 指向现有文档：“有关设置，请参阅
CONTRIBUTING.md” 或 “遵循src/api/routes/中的模式” - 无废话— 无介绍、结论或客套话
- 信任能力— 省略明显的上下文
- 优先使用文件范围的命令— 每个文件的测试/代码检查/类型检查命令优于全项目构建
- 不要重复使用代码检查工具— 代码风格存在于代码检查工具配置中，而不是 AGENTS.md
必填部分
软件包管理器
仅使用哪个工具和快捷键：
## Package Manager Use **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test`文件范围命令
逐文件命令比完整项目构建更快、更便宜。可用时请始终包括：
## File-Scoped Commands | Task | Command | |------|---------| | Typecheck | `pnpm tsc --noEmit path/to/file.ts` | | Lint | `pnpm eslint path/to/file.ts` | | Test | `pnpm jest path/to/file.test.ts` |提交归属
始终包含此部分。代理应使用他们自己的身份：
## Commit Attribution AI commits MUST include:联合作者： （代理模型的名称和署名栏）
Example: `Co-Authored-By: Claude Sonnet 4 <noreply@example.com>`关键惯例
项目特定模式，代理必须遵循。保持简短。
可选部分
仅在真正需要时添加：
- API 路由模式（显示模板，不解释）
- 命令行界面命令（表格格式）
- 文件命名规范
- 项目结构提示（指向关键文件，标记需避免的遗留代码）
- 单一代码库覆盖（子目录
AGENTS.md文件覆盖根目录）
反模式
省略这些：
- “欢迎来到……” 或 “本文件说明……”
- “你应该……”或“记得……”
- Lint器/格式化器规则已在配置文件中（
.eslintrc、biome.json、ruff.toml） - 列出已安装的技能或插件（代理会自动发现这些）
- 当存在文件范围的替代项时，完整的全项目构建命令
- 明显的指示（“运行测试”，“编写干净的代码”）
- 解释原因（只说是什么）
- 长篇散文段落
示例结构
# Agent Instructions ## Package Manager Use **pnpm**: `pnpm install`, `pnpm dev` ## Commit Attribution AI commits MUST include:联合作者： （代理模型的名称和署名）
## File-Scoped Commands | Task | Command | |------|---------| | Typecheck | `pnpm tsc --noEmit path/to/file.ts` | | Lint | `pnpm eslint path/to/file.ts` | | Test | `pnpm jest path/to/file.test.ts` | ## API Routes [Template code block] ## CLI | Command | Description | |---------|-------------| | `pnpm cli sync` | Sync data |限制
- 仅当任务明确符合上述描述的范围时，才使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少所需的输入、权限、安全界限或成功标准，请停下来并要求澄清。
