audit-agents-md

name	audit-agents-md
description	Audit a project's AGENTS.md, CLAUDE.md, opencode.json, and .opencode resources for OpenCode compatibility, structure, bloat, stale references, and missing operational guidance.

Audit AGENTS.md for OpenCode

Audit the instruction files in the current project. This is read-only. Do not create, edit, install, remove, or delete anything.

Discovery

Check the project root for:

• AGENTS.md
• CLAUDE.md
• GEMINI.md
• .cursorrules
• .cursor/rules/
• .github/copilot-instructions.md
• opencode.json
• tui.json
• .opencode/agents/
• .opencode/commands/
• .opencode/skills/
• .opencode/plugins/
• .opencode/themes/

Also find nested instruction files:

find . -name AGENTS.md -o -name CLAUDE.md -o -name GEMINI.md

Read the root instruction file in full. If both AGENTS.md and CLAUDE.md exist, check for duplication or contradiction.

OpenCode-specific checks

Context loading

• OpenCode prefers AGENTS.md over CLAUDE.md when both exist in the same directory.
• Project rules are discovered by traversing up from the current directory.
• Global ~/.config/opencode/AGENTS.md is loaded after local rules.
• ~/.claude/CLAUDE.md is a fallback when no OpenCode global rules exist and Claude compatibility is enabled.
• Prefer AGENTS.md as the portable source of truth.
• If CLAUDE.md exists only to import AGENTS.md, that is good cross-tool compatibility.

Size

Lines	Verdict
0	FAIL Missing
1-30	WARN Probably too thin
31-150	OK Good
151-250	WARN Look for extraction candidates
251+	FAIL Too long

Essential sections

Check whether the file gives agents what they need:

• Commands: build, test, lint, run, deploy where relevant.
• Testing: framework, how to run targeted tests, expected quality gates.
• Project structure: important directories and ownership boundaries.
• Code style: concrete conventions and examples, not generic prose.
• Git workflow: branch, commit, PR rules.
• Boundaries: always, ask first, never.
• OpenCode resources: mention relevant .opencode/ agents, commands, skills, plugins, themes, or config.

Bloat and stale content

Flag:

• Long tutorials.
• Completed checklists.
• Historical notes that do not affect current work.
• Generic filler like "write clean code".
• Rules already enforced by linters, formatters, permissions, or plugins.
• Paths that do not exist.
• Commands whose binaries are not installed.
• Secret-looking values.

Cross-tool compatibility

• AGENTS.md is the broadest portable name.
• CLAUDE.md is useful for Claude Code compatibility.
• If both exist, prefer one source of truth with import rather than duplicated text.
• If opencode.json uses instructions, verify the referenced files exist and do not duplicate AGENTS.md unnecessarily.

Project OpenCode config

• Is opencode.json valid JSON or JSONC and schema-tagged?
• Does project config avoid personal global preferences?
• Are permissions too broad for a shared repo?
• Are project plugins small, reviewed, and necessary?
• Are local commands and skills named clearly and documented in AGENTS.md when useful?

Report format

# AGENTS.md Audit: [project]

## Summary
[1-2 sentences]

## File stats
- Root file: [path] ([N] lines)
- Nested instruction files: [count]
- OpenCode resources: [config/agents/commands/skills/plugins/themes found]
- Cross-tool: [AGENTS.md / CLAUDE.md / both]

## FAIL Problems
- [issue + location + fix]

## WARN Suggestions
- [improvement + rationale]

## OK Working
- [specific working choices]

## Next steps
1. [most important]
2. [second]
3. [third]

Keep the report under 80 lines.