代理
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 安全
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# agents-md-lint
Audit AI agent instruction files by spawning a blind sub-agent that tries to rediscover each documented fact from code search alone. Facts it finds easily → remove. Facts it can't → keep.
This works on any file whose purpose is to give an AI agent context about a codebase: AGENTS.md, CLAUDE.md, CONVENTIONS.md, .cursorrules, or similar. The workflow refers to these collectively as "instruction files."
## Modes
**Default (rewrite):** Produces a report and rewrites the instruction files with only the surviving facts.
**Dry-run:** Produces the report but does not modify any files. Use this when the user wants to see what would change before committing, or says things like "just show me," "report only," or "what's redundant." Ask which mode the user wants if it's ambiguous.
## Workflow
### 1. Discover and normalize instruction files
Scan the repo for instruction files. Common names: `AGENTS.md`, `CLAUDE.md`, `CONVENTIONS.md`, `.cursorrules`, `.github/copilot-instructions.md`. Ask the user if there are others, or if any should be excluded.
**CLAUDE.md → AGENTS.md normalization:** If a `CLAUDE.md` exists but no `AGENTS.md`, rename `CLAUDE.md` to `AGENTS.md` and create a symlink `CLAUDE.md → AGENTS.md`. This keeps `AGENTS.md` as the canonical name while preserving compatibility with tools that look for `CLAUDE.md`. If both files already exist as separate files, leave them as-is and audit each independently. Skip this normalization in dry-run mode.
### 2. Extract facts
Read each instruction file. List every distinct fact as a numbered item, grouped by file. A "fact" is any single claim, convention, instruction, or piece of context — e.g., "tests use vitest," "branch names follow feature/JIRA-123 format," "never mock the database in integration tests."
### 3. Chunk facts for testing
Sub-agents get unreliable when asked too many questions at once. If a file contains more than 25 facts, split them into batches of 20–25 and spawn a separate sub-agent for each batch. Each batch should be self-contained — include enough context in the prompt so the sub-agent understands the domain without needing to see the other batches.
### 4. Spawn blind reviewer(s)
For each batch of facts, spawn a sub-agent with this task template. The key insight here is that the sub-agent must not have access to the instruction files — it should rely only on what it can find by searching the code. Rather than renaming or moving files (which risks data loss if something goes wrong), tell the sub-agent explicitly which files to ignore:
```
You are reviewing the codebase at <REPO_PATH> to test what facts are easily
discoverable from code alone — without any documentation.
IMPORTANT: Do NOT read or search inside these files, as they are the
documentation being audited:
<list of instruction file paths to exclude>
For EACH question below, try to answer using code searches (grep, glob,
reading config/source files). Use up to 3-4 searches per question — check
multiple locations if the first search doesn't find it (e.g., config files,
source code, test files, CI configs). Answer briefly and rate your confidence:
- HIGH: Found clear, unambiguous evidence
- MEDIUM: Found partial or indirect evidence (e.g., an example exists but
the convention isn't stated, or the fact is buried in a non-obvious place)
- LOW: Could not find evidence, or only found it after extensive digging
For MEDIUM answers, note WHERE you found the evidence and how many searches
it took. This helps distinguish "technically findable but practically buried"
from "right there in the config."
QUESTIONS:
<numbered list of questions, one per extracted fact>
```
Use a capable model (opus or equivalent) for reliable results.
### 5. Score results
Compare each sub-agent's answers against the original facts. The scoring accounts for both correctness and practical discoverability — a fact that's technically in the code but requires insider knowledge to find is still worth documenting.
| Agent confidence | Agent correct? | Verdict |
|-----------------|----------------|---------|
| HIGH | Yes | **Remove** — easily discoverable |
| HIGH | Partially | **Keep** the missing detail only |
| MEDIUM | Yes | **Keep** — findable but buried; an agent without docs would likely miss it or waste time searching |
| MEDIUM | Partially | **Keep** — not reliably found |
| LOW | — | **Keep** — not discoverable |
### 6. Present results
Show a summary table:
```
| # | Fact | Confidence | Correct? | Verdict |
|---|------|-----------|----------|---------|
| 1 | Uses vitest for testing | HIGH | Yes | Remove |
| 2 | Branch naming: feature/JIRA-### | LOW | No | Keep |
| 3 | Auth middleware in src/middleware/auth.ts | MEDIUM | Yes | Keep (buried) |
```
Report: total facts, removed count, kept count, line reduction percentage.
**If dry-run mode:** Stop here. Do not modify any files.
### 7. Rewrite the files (default mode only)
Rewrite each instruction file with only the surviving facts. Principles:
- Every line must earn its tokens
- No headers or sections with a single bullet (inline it)
- Don't repeat what's in CONTRIBUTING.md, README.md, or config files
- Group related facts naturally
- Preserve the original file's voice and structure where possible — this is a trim, not a rewrite from scratch
## Tips
- For monorepos with multiple instruction files, test each file separately — a fact might be discoverable in one subproject's context but not another's
- Facts about *conventions* (naming rules, branch patterns) are usually NOT discoverable even if examples exist in git history — keep them
- Facts about *auth mechanisms* are often buried in middleware — usually worth keeping
- Facts about *known gotchas* (e.g., "use --forceExit," "don't mock the DB") are almost never discoverable — keep them
- Facts about *file locations* ("tests live in __tests__/") are often easily discoverable from directory structure — good candidates for removal
- When in doubt, keep the fact. The cost of a missing instruction (agent does the wrong thing) is higher than the cost of a few extra context tokens
---
> Source: [borkweb/skills](https://github.com/borkweb/skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
模式
1. 发现并规范指令文件
2. 提取事实
3. 用于测试的块事实
4. 产生盲审者
文件/命令 -> AGENTS.md · CLAUDE.md · CONVENTIONS.md · .cursorrules · .github/copilot-instructions.md · CLAUDE.md → AGENTS.md
内容校验值 -> ee55f87ff152
当前原文的自动摘译,尚未人工审校。
模式
默认(重写):生成报告并仅使用幸存的事实重写说明文件。试运行:生成报告但不修改任何文件。当用户想要在提交之前查看会发生什么变化,或者说“只告诉我”、“仅报告”或“什么是多余的”之类的内容时,请使用此选项。如果不明确,询问用户想要哪种模式。
1. 发现并规范指令文件
扫描存储库以获取说明文件。常用名称:
AGENTS.md、CLAUDE.md、CONVENTIONS.md、.cursorrules、.github/copilot-instructions.md。询问用户是否还有其他,或者是否应该排除任何其他。 CLAUDE.md → AGENTS.md 规范化:如果存在CLAUDE.md但不存在AGENTS.md,则将CLAUDE.md重命名为AGENTS.md并创建符号链接CLAUDE.md → AGENTS.md。这使AGENTS.md保持为规范名称,同时保留与查找CLAUDE.md的工具的兼容性。如果这两个文件已作为单独的文件存在,请将它们保留原样并独立审核每个文件。在试运行模式下跳过此标准化。2. 提取事实
阅读每个指令文件。将每个不同的事实列出为编号项目,并按文件分组。 “事实”是任何单个声明、约定、指令或上下文 - 例如,“测试使用 vitest”、“分支名称遵循功能/JIRA-123 格式”、“切勿在集成测试中模拟数据库”。
3. 用于测试的块事实
当同时问太多问题时,分代理会变得不可靠。如果文件包含超过 25 个事实,请将它们分成 20-25 个批次,并为每个批次生成一个单独的子代理。每个批次都应该是独立的 - 在提示中包含足够的上下文,以便子代理了解域而无需查看其他批次。
4. 产生盲审者
对于每批事实,使用此任务模板生成一个子代理。这里的关键见解是子代理不得访问指令文件 - 它应该仅依赖于通过搜索代码找到的内容。不要重命名或移动文件(如果出现问题,可能会导致数据丢失),而是明确告诉子代理要忽略哪些文件:使用有能力的模型(opus 或等效模型)来获得可靠的结果。