majiayu000/spellbook / skills/repo-agent-context-audit
repo-agent-context-audit
VerifiedAudit 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.5 KB |
| references/standards.md | markdown | 3.7 KB |
| references/templates.md | markdown | 3.5 KB |
| scripts/scan_repo_context.py | script | 5.2 KB |
scripts/scan_repo_context.py
View on GitHub#!/usr/bin/env python3
"""Read-only scanner for repository agent context files."""
from __future__ import annotations
import argparse
import os
import re
from pathlib import Path
IGNORE_DIRS = {
".git",
".hg",
".svn",
"node_modules",
"target",
"dist",
"build",
".next",
".turbo",
".venv",
"venv",
"__pycache__",
}
HIGH_CONTEXT_ANY_NAMES = {
"AGENTS.md",
"CLAUDE.md",
"WARP.md",
"RULES.md",
}
TOP_LEVEL_CONTEXT_NAMES = {
"CONTRIBUTING.md",
"README.md",
}
HIGH_CONTEXT_REL = {
".claude/instructions.md",
".github/copilot-instructions.md",
}
SPEC_NAMES = {
"PRODUCT.md",
"product.md",
"TECH.md",
"tech.md",
}
def iter_files(root: Path):
for dirpath, dirnames, filenames in os.walk(root):
dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS]
current = Path(dirpath)
for filename in filenames:
yield current / filename
def rel(path: Path, root: Path) -> str:
try:
return path.relative_to(root).as_posix()
except ValueError:
return path.as_posix()
def text_stats(path: Path) -> dict[str, int]:
try:
text = path.read_text(encoding="utf-8")
except UnicodeDecodeError:
text = path.read_text(encoding="utf-8", errors="replace")
lines = text.splitlines()
return {
"lines": len(lines),
"headings": sum(1 for line in lines if line.startswith("#")),
"tables": sum(1 for line in lines if line.startswith("|")),
"code_fences": sum(1 for line in lines if line.startswith("```")),
"numbered": sum(1 for line in lines if re.match(r"^\s*\d+\.\s+", line)),
}
def is_skill_file(relative: str) -> bool:
return (
re.match(r"^\.agents/skills/[^/]+/SKILL\.md$", relative) is not None
or re.match(r"^skills/[^/]+/SKILL\.md$", relative) is not None
or re.match(r"^skills/[^/]+\.SKILL\.md$", relative) is not None
)
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("root", nargs="?", default=".", help="repository root to scan")
args = parser.parse_args()
root = Path(args.root).resolve()
high_context = []
supporting_docs = []
skills = []
specs = []
for path in iter_files(root):
relative = rel(path, root)
if (
path.name in HIGH_CONTEXT_ANY_NAMES
or relative in HIGH_CONTEXT_REL
or (path.parent == root and path.name in TOP_LEVEL_CONTEXT_NAMES)
):
high_context.append(path)
elif path.name == "README.md":
supporting_docs.append(path)
if is_skill_file(relative):
skills.append(path)
if "/specs/" in f"/{relative}" and path.name in SPEC_NAMES:
specs.append(path)
print(f"# Repo Agent Context Scan: {root}")
print()
print("## High-Context Files")
if not high_context:
print("- none found")
for path in sorted(high_context):
stats = text_stats(path)
print(
f"- `{rel(path, root)}`: {stats['lines']} lines, "
f"{stats['headings']} headings, {stats['code_fences']} code fences"
)
print()
print("## Supporting README Files")
if not supporting_docs:
print("- none found")
else:
print(f"- files: {len(supporting_docs)}")
for path in sorted(supporting_docs)[:40]:
stats = text_stats(path)
print(f"- `{rel(path, root)}`: {stats['lines']} lines")
if len(supporting_docs) > 40:
print(f"- ... {len(supporting_docs) - 40} more")
print()
print("## Repo Skills")
if not skills:
print("- none found")
for path in sorted(skills):
stats = text_stats(path)
print(f"- `{rel(path, root)}`: {stats['lines']} lines")
print()
print("## Specs")
if not specs:
print("- none found")
else:
by_name: dict[str, int] = {}
by_dir: dict[str, set[str]] = {}
for path in specs:
by_name[path.name] = by_name.get(path.name, 0) + 1
parent = rel(path.parent, root)
by_dir.setdefault(parent, set()).add(path.name)
print(f"- files: {len(specs)}")
for name in sorted(by_name):
print(f"- {name}: {by_name[name]}")
print("- directories:")
for directory in sorted(by_dir)[:80]:
names = ", ".join(sorted(by_dir[directory]))
print(f" - `{directory}`: {names}")
if len(by_dir) > 80:
print(f" - ... {len(by_dir) - 80} more")
print()
print("## Quick Signals")
top = [p for p in high_context if p.parent == root and p.name in {"AGENTS.md", "CLAUDE.md", "WARP.md"}]
print(f"- top-level router candidates: {len(top)}")
print(f"- repo-local skills: {len(skills)}")
print(f"- spec contract files: {len(specs)}")
overloaded = [p for p in high_context if text_stats(p)["lines"] > 200]
if overloaded:
names = ", ".join(f"`{rel(p, root)}`" for p in overloaded)
print(f"- possible overloaded high-context files: {names}")
else:
print("- possible overloaded high-context files: none")
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |