Skip to content

majiayu000/spellbook / skills/repo-agent-context-audit

repo-agent-context-audit

Verified

Audit and recommend improvements for a repository's agent-readable context, including AGENTS.md, CLAUDE.md, WARP.md, CONTRIBUTING.md, .agents/skills, and specs/ PRODUCT.md and TECH.md contracts. Use when asked to review, score, assess, or standardize repo instructions, agent onboarding, spec workflows, or cross-repo agent-context conventions. Use agentsmd-scaffold instead when the user wants to generate or apply root/scoped AGENTS.md files.

FileKindSize
SKILL.mdskill md7.5 KB
references/standards.mdmarkdown3.7 KB
references/templates.mdmarkdown3.5 KB
scripts/scan_repo_context.pyscript5.2 KB

references/standards.md

View on GitHub
# Repo Agent Context Standard

Use this reference when scoring a repository's agent-readable context.

## Target Shape

| Layer | Purpose | Good Size | Contents |
|---|---|---:|---|
| Top-level router | Tell agents where to start and what must be obeyed | 80-150 lines | Scope, build/test commands, required workflows, high-risk rules |
| Skills | Repeatable procedures | 40-200 lines each | One task workflow, concrete steps, when to read references |
| Specs | Change-specific contracts | 40-200 lines normally | PRODUCT behavior invariants, TECH implementation and validation |
| References | Detailed context | Any size | Architecture notes, examples, schemas, historical context |

## Scoring Rubric

Score each category 0-2.

| Category | 0 | 1 | 2 |
|---|---|---|---|
| Top-level routing | Missing or unclear | Exists but noisy or incomplete | Short, scoped, points to deeper docs |
| Progressive disclosure | Everything in one file | Some splitting but unclear loading | Router, skills, specs, references are distinct |
| Procedural workflows | Vague advice | Partial checklist | Concrete ordered steps for common tasks |
| Decision gates | No "when to spec/test/escalate" rules | Some prose guidance | Tables or clear gates with defaults |
| Production examples | Pseudocode or none | Some real paths | Real repo paths, commands, snippets |
| Spec quality | No specs for complex work | Specs exist but mix product/tech | PRODUCT behavior and TECH implementation are separate |
| Validation mapping | "Run tests" only | Commands listed | Behavior invariants map to tests/artifacts |
| Staleness risk | Contradicts code or commands | Unknown freshness | Current, cited, and easy to verify |

Suggested interpretation:

- 14-16: healthy; avoid adding ceremony.
- 10-13: usable; make one or two focused improvements.
- 6-9: fragile; add a router or split overloaded docs.
- 0-5: missing core context; scaffold minimal structure before major agent work.

## Good Top-Level Router

A good `AGENTS.md` or repo-equivalent:

- states its scope
- lists exact build, typecheck, test, and lint commands
- says when specs are required
- points to task skills or deeper docs
- names high-risk rules, such as auth, migrations, generated files, or UI verification
- avoids long architecture explanations
- avoids repeating README content unless agents need a different workflow

## Good Product Spec

`PRODUCT.md` is the source of truth for behavior. It should:

- describe the consumer perspective, not implementation
- use numbered, testable behavior invariants
- include default, empty, loading, error, permission, cancellation, race, and accessibility states when relevant
- define non-goals when scope can drift
- avoid validation sections if the repo uses `TECH.md` for validation mapping

## Good Tech Spec

`TECH.md` is the implementation contract. It should:

- cite current code and files with line references when practical
- explain current state before proposed changes
- list modules, types, APIs, state, and data flow that will change
- call out rejected alternatives when there is a real tradeoff
- map product behavior numbers to tests, manual checks, screenshots, or release gates
- stay current as implementation changes

## Red Flags

- a 300+ line top-level instruction file with mixed rules, workflows, architecture, and examples
- many "do not" rules without "use this instead"
- spec templates that produce boilerplate "None" sections
- product specs that prescribe internal types
- tech specs that ignore current code and read like generic architecture
- generated or dependency-modified high-context files
- multiple instruction files with overlapping scope and no precedence note
- stale commands or paths that fail when run
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall