project-auditor

Project Auditor Skill

You are an expert at evaluating how well a codebase is set up for productive use with Grok Build (and similar agentic coding tools).

Goals

• Give an accurate 0-100 "Grok Readiness Score".
• Identify concrete strengths and gaps.
• Provide prioritized, actionable recommendations.
• Support both human-readable and machine-readable output.

Steps

1. Understand the target

   • Accept a directory path (default to current working directory or .).
   • Confirm the path exists using list_dir or run_terminal_command (ls or test -d).

2. Load ignore rules

   • Read .grokignore (if present) and .gitignore (if present) from the target root.
   • Build an effective ignore matcher (respect both; .grokignore takes precedence for agent reads).
   • Never read files that would be ignored (node_modules, dist, .grok/sessions, large binaries, logs, etc.).

3. Scan for Grok Build signals (use list_dir + read_file + grep selectively)

   • Look for project rule files in this priority: AGENTS.md, Agents.md, AGENT.md, CLAUDE.md etc. (see official project-rules docs).
   • Count and inspect files under .grok/skills/*/SKILL.md.
   • For each skill: read the frontmatter, verify name + description exist and description is specific.
   • Detect test frameworks:
     • package.json → look for vitest, jest, mocha, ava, tap, scripts.test
     • pyproject.toml / pytest.ini / setup.cfg for pytest
     • go.mod + _test.go files, etc.
   • Detect CI:
     • .github/workflows/ (any *.yml or *.yaml)
     • .gitlab-ci.yml, Jenkinsfile, circle.yml, buildkite.yml, etc.
   • Git hygiene:
     • Is it a git repo? (git rev-parse --is-inside-work-tree)
     • Recent commits, clean/dirty status, branch name.
   • Other positive signals: README with "Grok", "agent", or "Plan Mode" mentions; CONTRIBUTING.md; .grok/ other dirs (hooks, agents).

4. Score the project (0-100) Base scoring on these weighted signals (adjust reasonably for project type):

   • AGENTS.md (or equivalent) present and substantial (≥800 chars, has multiple clear sections): +25
   • At least 2-3 well-formed skills in .grok/skills/: +20
   • Real test setup with passing tests or clear test command: +20
   • CI configuration present: +10
   • Good ignore hygiene (.grokignore present or comprehensive .gitignore): +8
   • Recent, clean git history + sensible branch discipline: +7
   • Bonus for explicit verification language ("run tests before commit", "use check skill", Plan Mode guidance): +5-10
   • Penalties for anti-patterns (huge unignored node_modules in scans, no tests, AGENTS.md is just a one-liner, etc.)