# Project Auditor

> Perform a thorough Grok Build readiness audit on a project directory. Detects presence and quality of AGENTS.md, .grok/skills, test setup, CI configuration, git hygiene, and ignore files. Produces a 0-100 score plus actionable recommendations. Use when asked to "audit", "gbs audit", "check grok readiness", "is this project agent-friendly", "grok build readiness", or when building/using the gbs audit command.

- Skill: `cobusgreyling/project-auditor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cobusgreyling/project-auditor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cobusgreyling/project-auditor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cobusgreyling (https://skillmd.com/u/cobusgreyling)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cobusgreyling/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.)

   Produce a single integer score and a short justification.

5. **Generate recommendations**
   - Always give 2-5 concrete, prioritized next actions.
   - Examples: "Add a readiness-scorer skill", "Document the test command in AGENTS.md", "Create .grokignore", "Add a GitHub Action that runs `npm test` on PRs".

6. **Output**
   - Human mode (default): nice formatted report with score, ✓/△/✗ bullets, and recommendations list.
   - `--json`: machine-readable object with score, findings[], recommendations[].
   - `--md`: markdown suitable for pasting into issues or PRs.
   - If the auditor itself is being implemented, emit the exact data structures the CLI will render.

## Important Principles
- Be evidence-based. Quote file paths, char counts, and specific signals you actually read.
- Respect ignore files strictly — do not waste tokens or time on noise.
- A project without any Grok signals can still score 30-40 if it has excellent tests + CI + clean git (the basics transfer).
- The goal is improvement, not shaming. Frame gaps positively ("Opportunity: ...").

## Tool Usage Notes
- Prefer `list_dir`, `read_file`, `grep`, and targeted `run_terminal_command` (for git).
- For large trees, start at root, then drill into promising subdirs only.
- When auditing this repo itself, expect a very high score and use it as the "good-project" reference.

This skill can (and should) be used both interactively and by the `gbs` CLI implementation.