Installation

Installation

Requirements

• Codex or ChatGPT desktop for Skill use.
• Python 3.10 or newer for the standalone tools.
• Git if you choose clone-based installation or use the git-visible/tracked scan modes.

The Python tools use only the standard library.

Option 1: ask the built-in installer

In Codex, ask:

Use $skill-installer to install https://github.com/1838904818/audit-repo.

This is the simplest installation path.

Option 2: clone into the user Skill directory

macOS or Linux:

mkdir -p "$HOME/.agents/skills"
git clone https://github.com/1838904818/audit-repo.git "$HOME/.agents/skills/audit-repo"

Windows PowerShell:

$skillRoot = Join-Path $HOME ".agents\skills"
New-Item -ItemType Directory -Force -Path $skillRoot | Out-Null
git clone https://github.com/1838904818/audit-repo.git (Join-Path $skillRoot "audit-repo")

To upgrade a clone-based installation later:

git -C "$HOME/.agents/skills/audit-repo" pull --ff-only

Option 3: install a checksummed release archive

Download both audit-repo-vX.Y.Z.zip and audit-repo-vX.Y.Z.zip.sha256 from Releases. Verify before extracting.

The current v1.10.7 release targets commit 479d552d, and its annotated tag object is 1cf374e27e6bb79e68804bd7be12e9464740b37d. The audit-repo-v1.10.7.zip SHA-256 is 321c835d668f043cf1740c71dc5d523ac8dea9629ddadba60212c47027918779; the audit-repo-v1.10.7.zip.sha256 sidecar SHA-256 is c25ccdd356793a1ea93d2da5f0fa9f3bf9af17bf70bcd61fae25dadeac83bfc8. This is the first audit-repo Release published with immutable=true and a GitHub-generated signed release attestation. Verify the sidecar against its published digest, then use it to verify the archive before extracting.

Linux:

version=v1.10.7
sha256sum --check "audit-repo-${version}.zip.sha256"
mkdir -p "$HOME/.agents/skills"
unzip "audit-repo-${version}.zip" -d "$HOME/.agents/skills"

macOS:

version=v1.10.7
shasum -a 256 --check "audit-repo-${version}.zip.sha256"
mkdir -p "$HOME/.agents/skills"
unzip "audit-repo-${version}.zip" -d "$HOME/.agents/skills"

Windows PowerShell:

$version = "v1.10.7"
$archive = "audit-repo-$version.zip"
$checksum = "audit-repo-$version.zip.sha256"
$expected = ((Get-Content $checksum -Raw).Trim() -split "\s+")[0]
$actual = (Get-FileHash $archive -Algorithm SHA256).Hash
if ($actual.ToLowerInvariant() -ne $expected.ToLowerInvariant()) {
    throw "SHA-256 checksum mismatch"
}
$skillRoot = Join-Path $HOME ".agents\skills"
New-Item -ItemType Directory -Force -Path $skillRoot | Out-Null
Expand-Archive $archive -DestinationPath $skillRoot

For an upgrade, extract into a temporary directory first, verify that it contains one top-level audit-repo directory, and replace the existing installation only after preserving any local changes.

GitHub Action pin

Pin the released composite Action in production workflows:

- uses: 1838904818/audit-repo@v1.10.7

Invoke the Skill

Codex CLI or IDE extension:

Use $audit-repo to audit this repository and prioritize the most important fixes.

You can also open /skills and select it. In ChatGPT desktop, type @ and choose Audit Repo.

Codex may invoke the Skill automatically for repository health, release readiness, maintainability, security posture, technical debt, and audit comparison requests.

Verify an installation

Check that these runtime files exist under $HOME/.agents/skills/audit-repo:

SKILL.md
README.md
CHANGELOG.md
LICENSE
agents/openai.yaml
scripts/check_repo.py
scripts/collect_repo_signals.py
scripts/compare_repo_signals.py
references/check-selection.md
references/rubric.md

Then run:

python "$HOME/.agents/skills/audit-repo/scripts/collect_repo_signals.py" --help

Codex detects installed Skill changes automatically. If the Skill is still missing from the picker, restart Codex and confirm that SKILL.md is directly inside the audit-repo directory rather than nested one level deeper.