跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
部署与云服务

agents-md

Use when a repo needs agent setup, AGENTS.md added or made lean, CLAUDE.md audited, or agent instructions scored or pruned. Not for remote, credential, publish, deploy, or irreversible changes.

OutlineDriven · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add OutlineDriven/odin-claude-plugin --skill agents-md

技能说明


name: agents-md description: 'Use when a repo needs agent setup, AGENTS.md added or made lean, CLAUDE.md audited, or agent instructions scored or pruned. Not for remote, credential, publish, deploy, or irreversible changes.'

Agents MD

Contract

FieldBound contract
TriggerUser asks to set up a repo for agents, add AGENTS.md, audit CLAUDE.md, make a repo agent-friendly, score agent instructions, prune long/generic/stale instructions, or produce a lean pointer-only AGENTS.md
AuthorityReversible local: writes only AGENTS.md, CLAUDE.md (or a symlink to AGENTS.md when a target tool reads solely CLAUDE.md), CLAUDE.local.md, .claude/settings.json, .cursor/rules/*.mdc, Cursor hooks.json, and supporting instruction files after user confirmation; rollback is restoring the pre-edit snapshot. No remote mutation.
Side effectLocal write to agent instruction files in the repo; no remote, credential, paid, published, deployed, or VCS mutation
DoneRepo has working, scored, non-contradictory AGENTS.md for every target tool, plus a CLAUDE.md only when a target tool reads solely CLAUDE.md; every surviving line passes the three-check admission gate (non-discoverable, operationally significant, actionable); lean variants stay under 100 lines with pointer-only sections

Inputs

  • Required: the repository root path to audit or set up.
  • Optional: target tool set (defaults to Claude Code, Codex, and Cursor); audit mode (quick or full, defaults to quick); target grade (defaults to 10/12 for quick, A for full); target file path (defaults to root AGENTS.md, then CLAUDE.md if AGENTS.md absent); scope limit (root-only versus hierarchical); owner name for the lean commit attribution line.

Procedure

AGENTS.md files are execution contracts, not knowledge bases. Every line must help an agent execute correctly with minimal context. AGENTS.md is temporary guidance, not permanent configuration: when a recurring issue has a fixable root cause in code or tooling (a lint rule, test, script, or structural change), prefer that fix and keep only the minimum instruction needed until the root cause is solved.

  1. Discover files and survey discoverability. Find every agent instruction file in the repo:

    find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "CLAUDE.local.md" \) 2>/dev/null | sort
    

    Also check ~/.claude/CLAUDE.md (applies to every session). For monorepos, include workspace-level files. Audit each level independently: root holds universal rules, child files hold directory-specific rules. Then survey source files to learn what is already discoverable: README, PROJECT.md, cursor rules (.cursor/rules/ or .cursorrules), Copilot instructions (.github/copilot-instructions.md), GEMINI.md, CI/workflow files, package manager config, CONTRIBUTING.md, and docs/. Record what an agent can infer from these alone; anything discoverable need not be restated.

    • Done when: every instruction file is listed and the discoverability survey records what an agent can learn without AGENTS.md.
  2. Choose a mode.

    • No agent instructions, or targeting a tool the repo is not wired for → Setup (Step 3), then Writing from scratch (Step 6), then Audit (Step 4).
    • File exists and the question is quality → Audit (Step 4).
    • File exists and is bloated (root over ~150 lines), stale, scored below target, long/generic/stale, or agents repeat avoidable mistakes → Refactor (Step 5).
    • Repo has convention docs and user wants a lean pointer file → Lean (Step 6, lean variant).
    • Done when: exactly one mode is selected and the entry step is identified.
  3. Setup: decide which files exist and which tool reads each.

    • AGENTS.md at the repo root is the source of truth. Claude Code, Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, and Zed all read it natively. Every other agent file is a pointer or tool-specific supplement, never a second copy. Two copies of a rule drift silently because nothing in the codebase contradicts either one.
    • Claude Code: nothing beyond AGENTS.md. Add CLAUDE.md -> AGENTS.md as a symlink only when a tool in use reads solely CLAUDE.md; a symlink keeps one source of truth where a copy would drift. Use .claude/settings.json for hooks and CLAUDE.local.md (gitignored) for personal overrides.
    • Codex: nothing beyond AGENTS.md.
    • Cursor: AGENTS.md covers prose. Add .cursor/rules/*.mdc only for rules needing Cursor glob scoping. Frontmatter is required; alwaysApply: true with empty globs duplicates AGENTS.md.
    • Check .gitignore: if agent config is ignored, decide per file whether it is personal (leave ignored) or repo knowledge (commit it). Do not put shared knowledge under .claude/; that path reads as Claude-only and is commonly gitignored.
    • The import trap: @import is Claude Code only. Codex and Cursor ignore @import lines without warning, so a rule behind an import is absent from most sessions while the file looks correct. Anything every tool must obey goes inline in AGENTS.md. Reserve @import for depth only Claude Code needs, never for safety, data-loss, or format-contract rules. @import chains stop resolving at 5 hops; deeper content silently disappears. @import lines do not evaluate inside code spans or fenced blocks.
    • Enforcement that survives tool choice: prefer, in order, a linter or formatter rule, a git hook (lefthook, husky) that fires whichever agent made the edit, a CI check, then tool-native hooks (.claude/settings.json, Cursor hooks.json). Tool-native hooks are the last rung because they cover one tool only. Move a prose rule down to an exit code whenever the check is mechanical, and delete the prose once the gate exists.
    • Done when: the file-to-tool mapping is decided and every tool's read path is confirmed.
  4. Audit: score each root file independently. Exclude N/A checks from the denominator.

    • **Qu
阅读完整来源 ↗