特工
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Docker
- 运行环境要求
- Python · Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
在编写任何内容之前,请先了解代码库。使用有针对性的调查——不要猜测。强制检查:语言和框架 - `ls`根,阅读`package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod`、`Gemfile`、`build.gradle`、`pom.xml`或等效的构建和开发命令 - 查找`Makefile`、`justfile`、`Taskfile`、CI 配置(`.github/workflows/`、`.gitlab-ci.yml`)、`scripts/` 目录
用命令性的、代理人主导的散文来写作。每条指令都应该是可操作的。有关 Rust、Python、TypeScript、Go 和 Java 项目的完整示例,请参阅`references/examples.md`。核心原则:具体、可操作。不要说“运行测试”——说`pnpm test --filter <package>`。不要说“遵循风格指南”,而要说“使用单引号,无分号,2 个空格缩进”。要包含的部分
在提交草稿之前,请验证命令是否确实有效。这可以捕获过时的指令、错误的标志和丢失的设置步骤。对于 AGENTS.md 中的每个命令:尝试在项目目录中运行它(或空运行等效命令)如果失败,请调查原因 - 工具版本错误?缺少依赖?工作目录错误?修复命令或添加先决条件注释
验证后,根据以下条件检查文件: 每个命令都是可复制粘贴的。除非明确标记(如`<package-name>`),否则没有占位符。无明显间隙。如果项目有测试,就会有一个测试部分。如果它有 linter,就会有 lint 命令。没有绒毛。删除代理已经知道的任何内容(TypeScript 是什么,`npm install` 如何工作)。仅特定于项目的上下文。架构边界是明确的。如果模块有导入限制,请说明。
当改进而不是从头开始创建时:首先读取现有文件。在更改任何内容之前先了解已有的内容。无论如何都要进行调查阶段。现有的 AGENTS.md 可能已经过时 - 将其内容与实际配置文件、CI 配置和项目结构进行比较。检查是否陈旧。查找:引用不再存在的工具或脚本的命令
嵌套文件对于上下文效率很重要 - 代理将最近的 AGENTS.md 加载到正在编辑的文件中。在包含 10 个包的 monorepo 中,单个根文件强制每个代理交互加载所有 10 个包的指令。嵌套文件将上下文范围限定为相关内容。根 — 工作区级命令、共享代码风格、跨包规则。保持它适用于任何地方。 Package——特定于包的构建/测试/lint,该包特有的约定。代理编辑`packages/web/`获取root + web,而不是api或共享的指令。
# AGENTS.md Generator
AGENTS.md is a standard Markdown file that gives AI coding agents project-specific context: exact commands, enforced conventions, architecture constraints. Agents from most major tools (Codex, Copilot, Cursor, Jules, Devin, opencode, etc.) read it automatically.
## The Cost Model — Why Every Line Matters
**AGENTS.md is auto-injected into the agent's context window on every interaction.** Unlike docs or skills that load on demand, AGENTS.md permanently occupies context for every task the agent works on in that repo. A bloated AGENTS.md directly degrades agent performance on everything — less room for code, conversation, and reasoning.
This means:
**Prioritize by frequency × impact.** Every line must earn its permanent context cost.
| Priority | Content type | Why it earns its tokens |
|---|---|---|
| **Critical** | Test commands (run-all, run-single) | Used on nearly every task |
| **Critical** | Lint/format commands | Run after every edit |
| **Critical** | Architecture boundaries | Prevents expensive mistakes on every change |
| **High** | Code style rules (only enforced, non-obvious ones) | Prevents failed CI on every PR |
| **High** | Build commands | Used frequently |
| **Medium** | Commit/PR conventions | Used at end of each task |
| **Medium** | Setup instructions | Used once per session |
| **Low** | Deployment steps, migration workflows, API docs | Used rarely — consider putting in docs/ or a separate skill instead |
**What does NOT belong in AGENTS.md:**
- Detailed API reference docs → put in `docs/api.md`, the agent reads them when needed
- Extensive style guides → link to the config file (`see .eslintrc.json`), state only the non-obvious rules
- Complex deployment runbooks → put in `docs/deploy.md` or a deployment skill
- One-time setup instructions that are already in README → don't duplicate
- Anything the agent already knows (language defaults, how common tools work)
**Target:** Most single-package projects should produce an AGENTS.md under 150 lines. Monorepo roots can be longer (up to ~250), but nested per-package files should be tight (50-100 lines each). If you're over these targets, you're probably including content that should live elsewhere.
## Workflow
### Phase 1: Investigate the Project
Before writing anything, understand the codebase. Use focused investigation — don't guess.
**Mandatory checks:**
1. **Language & framework** — `ls` the root, read `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `build.gradle`, `pom.xml`, or equivalent
2. **Build & dev commands** — Look for `Makefile`, `justfile`, `Taskfile`, CI configs (`.github/workflows/`, `.gitlab-ci.yml`), `scripts/` directory
3. **Test setup** — Find test runner config, test directories, example test commands
4. **Linting & formatting** — Check for `.eslintrc`, `ruff.toml`, `rustfmt.toml`, `.prettierrc`, `.editorconfig`, clippy config, etc.
5. **Project structure** — Identify key directories, monorepo layout if applicable
6. **Existing docs** — Read `README.md`, `CONTRIBUTING.md`, existing `AGENTS.md` if present
7. **Git conventions** — Check recent commit messages for patterns, look for commit hooks or conventional commits config
**Use `references/detection-patterns.md`** to map config files to exact tool invocations. Don't guess commands — the detection patterns file maps every common signal (lockfiles, config files, CI steps) to the precise commands.
**Extract commands from CI configs.** CI workflows (`.github/workflows/*.yml`, `.gitlab-ci.yml`) contain the exact commands the project uses. Read them and convert `--check` mode to `--fix` mode for the AGENTS.md (e.g., CI's `prettier --check .` becomes `prettier --write .`).
**For monorepos**, additionally:
- Identify package manager workspace config (`pnpm-workspace.yaml`, `Cargo.toml` workspace members, etc.)
- Note which packages have their own test/build commands
- Plan nested AGENTS.md files for subprojects
### Phase 2: Draft the AGENTS.md
Write in imperative, agent-directed prose. Every instruction should be actionable. See `references/examples.md` for full examples across Rust, Python, TypeScript, Go, and Java projects.
**Core principle: Be specific and actionable.** Don't say "run tests" — say `pnpm test --filter <package>`. Don't say "follow the style guide" — say "use single quotes, no semicolons, 2-space indent."
#### Sections to Include
Include all that apply. Skip what doesn't — a short, accurate file beats a long, padded one.
| Section | When to include | What makes it good |
|---|---|---|
| **Setup / Environment** | Always | Exact install commands, required tools with versions, minimum viable path |
| **Commands** | Always | Flat list: build, dev, lint, format, typecheck. Specify working directory if ambiguous |
| **Testing** | Always (if tests exist) | Most important section. Include: run-all, run-single-file, run-single-test, package-scoped (monorepo). Agents run these commands directly |
| **Code style** | When the project has enforced conventions | Name the linter/formatter, state specific rules agents get wrong (quote style, semicolons, import ordering). Don't restate language defaults |
| **Architecture** | Non-trivial projects | Directory map + **boundary constraints**. Not just "what lives where" but "what must not import what" |
| **Commits & PRs** | When project has conventions | Message format, PR title format, pre-commit checks. Include good/bad examples |
| **Boundaries** | When safety matters | What to never do, what to ask about first |
**Optional:** Database conventions, API patterns, deployment steps, security rules, debugging tips — include when the project has specific patterns an agent would otherwise get wrong.
#### How to Write Each Section Well
**Testing** — the section agents rely on most. Always include three levels: run everything, run one file, run one test. If the project uses a wrapper tool (`breeze`, `docker compose`, `tox`), say so — agents will try to call the runner directly otherwise.
**Code style** — only state what's project-specific or counter-intuitive. Don't explain that Python uses 4-space indent (it's the default). Do explain that this project uses `ruff` not `black`, or that `assert` is banned in production code.
**Architecture** — the hardest section to write well. Boundaries matter more than descriptions. To discover undocumented boundaries:
- Check import patterns: `grep -r "from src.api import" src/core/` — if zero results, that's a boundary
- Check CI for architecture tests (e.g., `dependency-cruiser`, `cargo deny`, import linting rules)
- Look at module-level `__init__.py` or `mod.rs` for public API surface
- Ask: "if an agent added an import from module X to module Y, would that break the design?"
**Conventions** — distinguish enforced vs. aspirational. If CI runs `ruff check` on every PR, that convention is enforced — state it confidently. If CONTRIBUTING.md says "prefer functional style" but nothing checks it, state it as a preference, not a rule.
### Phase 3: Validate Commands
Before presenting the draft, verify that the commands actually work. This catches stale instructions, wrong flags, and missing setup steps.
**For each command in the AGENTS.md:**
1. Try running it (or a dry-run equivalent) in the project directory
2. If it fails, investigate why — wrong tool version? Missing dependency? Wrong working directory?
3. Fix the command or add a prerequisite note
**Validation priority** (do the most important first):
- Test commands (agents run these most often)
- Lint/format commands
- Build commands
- Setup commands (these often just work)
If you can't run a command (e.g., requires a database or Docker), note it with a comment explaining the dependency: `# Requires PostgreSQL running on localhost:5432`.
Skip validation for commands that are clearly correct from the config (e.g., the test script is literally `"test": "vitest run"` in package.json).
### Phase 4: Review & Refine
After validating, check the file against these criteria:
1. **Every command is copy-pasteable.** No placeholders unless explicitly labeled (like `<package-name>`).
2. **No obvious gaps.** If the project has tests, there's a testing section. If it has a linter, there's a lint command.
3. **No fluff.** Remove anything an agent already knows (what TypeScript is, how `npm install` works). Only project-specific context.
4. **Architecture boundaries are explicit.** If modules have import restrictions, say so.
5. **For monorepos: consider nested files.** If subprojects have their own build/test/lint commands, generate per-package AGENTS.md files. The closest AGENTS.md to the edited file takes precedence.
### Phase 5: Improving an Existing AGENTS.md
When improving rather than creating from scratch:
1. **Read the existing file first.** Understand what's already there before changing anything.
2. **Run the investigation phase anyway.** The existing AGENTS.md may be stale — compare what it says against actual config files, CI configs, and project structure.
3. **Check for staleness.** Look for:
- Commands that reference tools or scripts that no longer exist
- Outdated version numbers or deprecated flags
- Missing sections for tools the project has adopted since the file was written
- Architecture descriptions that don't match current directory structure
4. **Preserve what works.** Don't rewrite sections that are already good. Focus on gaps and inaccuracies.
5. **Validate changed commands.** Run any command you modify or add to confirm it works.
6. **Diff-friendly edits.** Make targeted changes rather than rewriting the whole file. The user can review a focused diff much faster.
### Phase 6: Nested AGENTS.md for Monorepos
Nested files matter for context efficiency — agents load the nearest AGENTS.md to the file being edited. In a monorepo with 10 packages, a single root file forces every agent interaction to load instructions for all 10 packages. Nested files scope the context to what's relevant.
```
monorepo/
├── AGENTS.md # Root: workspace-level commands, shared conventions (~100 lines)
├── packages/
│ ├── api/
│ │ └── AGENTS.md # API-specific: test commands, API conventions (~60 lines)
│ ├── web/
│ │ └── AGENTS.md # Frontend-specific: dev server, component patterns (~60 lines)
│ └── shared/
│ └── AGENTS.md # Shared library: build, usage from other packages (~40 lines)
```
**Root** — workspace-level commands, shared code style, cross-package rules. Keep it to what applies everywhere.
**Package** — package-specific build/test/lint, conventions unique to this package. Agent editing `packages/web/` gets root + web, not instructions for api or shared.
## Writing Quality Checklist
- [ ] Commands are exact, not vague ("run tests" → `pytest tests/ -xvs`)
- [ ] Commands were validated (or clearly correct from config)
- [ ] Working directories specified where ambiguous
- [ ] Linter and formatter named with their config
- [ ] Test runner named with example single-test invocation
- [ ] Architecture boundaries stated as constraints, not just descriptions
- [ ] No explanations of general programming concepts
- [ ] No time-sensitive information (use "current method" / "legacy" sections)
- [ ] Consistent terminology throughout
- [ ] Under 150 lines for single-package projects, ~250 max for monorepo roots, 50-100 for nested files
- [ ] Nested files for monorepo subprojects when applicable
- [ ] Commands extracted from CI configs where available (converted from --check to --fix mode)
## Reference Files
- `references/detection-patterns.md` — Maps config files and project signals to exact tool invocations. Read during Phase 1 investigation.
- `references/examples.md` — Real-world AGENTS.md examples and patterns from notable open-source projects
---
> Source: [AidenGeunGeun/OpencodeOrchestra](https://github.com/AidenGeunGeun/OpencodeOrchestra) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
按说明文件中的顺序排列。
成本模型——为什么每条生产线都很重要
第一阶段:调查项目
第 2 阶段:起草 AGENTS.md
第 3 阶段:验证命令
第四阶段:审查和完善
文件/命令 -> docs/api.md · see .eslintrc.json · docs/deploy.md · package.json · pyproject.toml · Cargo.toml · go.mod · Gemfile
内容校验值 -> ac85efb366d1
当前原文的自动摘译,尚未人工审校。
成本模型——为什么每条生产线都很重要
AGENTS.md 在每次交互时都会自动注入到代理的上下文窗口中。与按需加载的文档或技能不同,AGENTS.md 永久占用代理在该存储库中处理的每个任务的上下文。臃肿的 AGENTS.md 会直接降低代理在所有方面的性能——减少代码、对话和推理的空间。这意味着:按频率 × 影响确定优先级。每行都必须获得其永久上下文成本。
第一阶段:调查项目
在编写任何内容之前,请先了解代码库。使用有针对性的调查——不要猜测。强制检查: 语言和框架 —
ls根,读取package.json、pyproject.toml、Cargo.toml、go.mod、Gemfile、build.gradle、pom.xml或等效的构建和开发命令 — 查找Makefile、justfile、Taskfile、CI 配置(.github/workflows/、.gitlab-ci.yml)、scripts/目录