Context Verifier

Philosophy

Generating context files is solved — ai-context handles that. Preventing decay is not. This skill validates that AI context files remain accurate, lean, and consistent. Overstuffed context files reduce AI task success by ~3% (ETH Zurich, 2026).

Verification Checks

1. Line Budget Compliance

Check line counts and estimate tokens (lines × 4). Apply budgets:

Warn on bridge length only when the extra lines appear to restate shared AGENTS.md content rather than genuine tool-specific instructions.

2. Discoverable Content Detection

Flag file tree characters (├──, └──, │), "Project Structure" sections with directory listings, dependency lists mirroring manifests, and architecture descriptions visible from source code. Report specific line numbers.

3. Stale Path Detection

Extract backtick-quoted paths from context files and verify each exists on disk. Report stale paths.

4. AGENTS-to-Bridge Consistency

Treat AGENTS.md as the canonical shared context. Bridge files may subset or reference it, but they must not contradict key commands, hard rules, naming conventions, or security notes. Flag missing bridge references (for example @AGENTS.md in CLAUDE.md) and bridges that duplicate AGENTS sections instead of staying thin.

5. MEMORY.md Drift

If a project MEMORY.md exists, check for convention-like patterns ("Always", "Never", "Use") not yet promoted to CLAUDE.md.

6. Context Guard Status (Claude Code, Gemini CLI, Copilot, Cursor)

Check for hook scripts and registration entries. In Claude Code: .claude/hooks/context-*.sh and .claude/settings.json. Other platforms use their own hook directories.

7. Context Load (Aggregate Token Estimate)

Calculate per-tool aggregate token load using the tool-to-file mapping from .claude/rules/context-quality.md. Thresholds: <5,000 tokens healthy, 5,000–10,000 warning, >10,000 over budget.

Report format shows per-tool totals with file-level breakdown and top contributors:

Context Load:
  Claude Code: ~3,200 tokens (~1.6% of 200K window) ✓
    CLAUDE.md — 320 tokens
    AGENTS.md — 480 tokens
    .claude/rules/*.md — 2,400 tokens ← top contributor

8. @import Path Validation

If any CLAUDE.md contains @path/to/file import lines, verify each target exists on disk. Report broken imports with the source file and line number.

9. Rule Path-Scope Validation

If any .claude/rules/*.md has paths: YAML frontmatter, verify each glob pattern matches at least one existing file. Report orphaned path-scope rules where globs match nothing.

10. Rule Symlink Targets

If any .claude/rules/*.md is a symlink, verify the target file exists. Report broken symlinks with the rule name and dangling target path.

11. .mcp.json Validation

If .mcp.json exists, validate JSON structure — check mcpServers object exists, each server has a valid command or url field, and referenced commands exist on PATH or as relative paths. Report structural errors and invalid server entries.

12. Agent Memory Directory Hygiene

Check if .claude/agent-memory/ or .claude/agent-memory-local/ directories are tracked in git (they should be gitignored — these contain per-agent runtime state). Warn if tracked. Check for .gitignore entries covering these paths.

13. Plugin Manifest Completeness

If .claude-plugin/plugin.json exists, verify required fields: name, version, description. Warn on missing optional fields: keywords, author, repository. Report missing fields.

14. Modern Cursor Layout Check

If .cursorrules exists but .cursor/rules/ does not, warn that current Cursor versions ignore the legacy single-file format in Agent mode. Suggest migrating to .cursor/rules/agents.mdc with description, globs, and alwaysApply frontmatter. If both exist, note that the legacy file is redundant. If only .cursor/rules/ exists, mark as healthy.

15. Modern Cline Layout Check

If .clinerules is a flat file (not a directory), suggest migrating to .clinerules/ directory mode with optional paths: frontmatter for path-scoped rules. If .clinerules/ directory exists, validate that each Markdown file has either no frontmatter or valid paths: frontmatter pointing to existing files.

16. Copilot Bridge Optionality (advisory only)

If .github/copilot-instructions.md exists and AGENTS.md is present, count unique non-trivial lines in the Copilot bridge that aren't in AGENTS.md. If fewer than 5, suggest deletion (Copilot loads AGENTS.md natively since Aug 2025). Advisory only — never deducts.

Scoring

Grade Bands

Report includes per-dimension breakdown and specific actions to reach grade A.

The new layout checks (14, 15) deduct 2 points each for using legacy formats; check 16 is advisory and never deducts.

Standalone CLI

For platforms without skill support, or for CI pipelines, use the standalone script:

bin/context-verify.sh              # Interactive report
bin/context-verify.sh --ci         # CI mode (exit 1 below threshold)
bin/context-verify.sh --ci --min-score 90  # Custom threshold

The CLI implements checks 1, 3, 5–16 automatically (bash + git). Check 2 (discoverable content) and check 4 (bridge consistency) are partially automated — full semantic analysis requires this AI-powered skill.

CI Integration

With ci argument (skill or CLI), output machine-readable format and exit code 1 on failures. Accept --min-score N to fail the CI job below a threshold.