repo-audit

repo-audit

A read-only survey of a repository against every other catalog skill's setup checks. It answers one question: which catalog skills apply here, and in what order?

What this skill is NOT for

• Applying a fix — a finding routes to the skill that owns it (oss-hygiene, gh-bootstrap, and so on); this skill never edits a file or calls a mutating API.
• Code review of application logic, tests, or business behavior — out of scope.
• Replacing a catalog skill's own protocol — the audit is a triage pass, not a substitute for reading that skill's SKILL.md.

Protocol

1. Run the bundled script from the repository root

python3 skills/repo-audit/scripts/repo_audit.py

Add --github to also run read-only gh api GET calls (merge settings, rulesets, delete_branch_on_merge, the CODEOWNERS errors endpoint). --github is opt-in; the default run only reads the working tree and local git metadata (git tag --list, git remote get-url origin).

Use --json for machine consumption or --markdown to paste the table into a PR comment. The script always exits 0 unless it errors itself — a missing or warn row is not a script failure.

2. The script checks, read-only, one row per catalog skill

Check	What it inspects	Route to
prek	prek.toml or .pre-commit-config.yaml	prek
oss-hygiene	LICENSE, CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, .github/ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE, .github/dependabot.yml, plus scorecard/codeql/dependency-review workflow presence	oss-hygiene
gh-bootstrap	.github/release.yml; with --github also merge settings and non-empty rulesets	gh-bootstrap
safe-settings	.github/settings.yml (informational)	safe-settings
config-review-bot	.coderabbit.yaml	config-review-bot
release	git tag --list and CHANGELOG.md	release
justfile	justfile	justfile
ci-optimize	workflows present with concurrency: (informational)	ci-optimize
build-optimize	skipped — needs measured wall-time data	build-optimize
github-copilot-repo-instructions	.github/copilot-instructions.md or .github/instructions/*.instructions.md	github-copilot-repo-instructions
codeowners	CODEOWNERS in root, docs/, or .github/; with --github also the codeowners/errors endpoint	codeowners
actions-pinning	count of uses: refs not pinned to a 40-hex commit SHA	actions-pinning
pr-title-lint	a workflow containing action-semantic-pull-request or commitlint	pr-title-lint
labels-as-code	.github/labels.yml or .github/labeler.yml	labels-as-code
repo-attributes	.gitattributes, .editorconfig, .gitignore	repo-attributes
branch-cleanup	with --github, delete_branch_on_merge	branch-cleanup
agents-md	AGENTS.md exists, under 32 KiB, under about 200 lines	agents-md

Each row's status is pass, warn, missing, or skipped. skipped means the check needs data this script cannot gather statically (build-optimize) or needs --github and it was not passed (branch-cleanup), not that the repository failed the check.

3. Read the table and propose an ordered plan

After the script prints its table, read the missing and warn rows and propose an ordered plan that names the catalog skill for each gap. Order gaps by dependency where one exists (for example, gh-bootstrap locks the merge surface before oss-hygiene adds contributor-facing files; actions-pinning matters more once workflows exist). Do not apply any fix yourself — hand each gap to its named skill.

4. No writes, no mutating calls

This skill and its script never create, edit, or delete a file, and never call a POST, PATCH, PUT, or DELETE GitHub API endpoint. --github only adds GET calls. If a user asks the audit to "just fix it", decline and restate the routing plan from step 3 instead.

References

• references/checks.md — one row per check, the file or endpoint it inspects, and a docs.github.com citation where an API is used.