Best Practices Audit

---
name: best-practices-audit
description: Audits skills, instructions, hooks, agents and permissions against the newest vendor docs. Use after a Claude Code or Codex release.
---
<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

# Best-Practices Audit

Compare the harness files with the vendor documentation of today, not with what you remember.
The checklist in [references/checklist.md](references/checklist.md) is the offline floor.
A live page overrides it.

## Rules

- **Pull the docs before the audit.** A rule, a limit or a field can change in any release.
- **Fetch only the listed sources.** Ask the user before you fetch any other URL.
- **Cite the page for every finding.** A finding with no source is an opinion.
- **Mark an API-only rule "not applicable"** when the repository does not call the Messages API.
  Name that reason once in the report.
- **Fix the source, never the projection.** In a basicly repository, edit the catalog source and
  project it again.

## Workflow

Copy this list and check off each step:

```text
Audit progress:
- [ ] 1 Pull the current docs
- [ ] 2 Compare the docs with the checklist
- [ ] 3 Audit the harness files
- [ ] 4 Run the gates
- [ ] 5 Report and fix
```

**1 Pull the current docs.** Run the script from the directory of this skill. It needs Python 3
and no package:

```sh
python3 scripts/fetch_docs.py --out <scratch-dir>
```

| Exit | Meaning | Next |
| --- | --- | --- |
| 0 | Every page arrived | Continue |
| 1 | Some pages failed | Continue, and name each failed page in the report |
| 2 | Offline, nothing arrived | Audit against the checklist only, and put "docs not refreshed" in the first line of the report |

`python3 scripts/fetch_docs.py --list` prints the sources.

**2 Compare the docs with the checklist.** Read each fetched page for rules on skills,
instruction files, hooks, subagents, permissions, context and cache. For each rule that is new,
changed or absent from the checklist, record a finding "checklist stale", with the page and the
quoted sentence. Then read `claude-code-index.txt` for pages that are not in `--list` and cover the
same subjects. Name them in the report.

**3 Audit the harness files.** For each checklist row, record pass, fail or not applicable, with
`path:line` evidence:

| Subject | Files |
| --- | --- |
| Skills | `.claude/skills/*/SKILL.md`, and in basicly the `skill.yaml` sources |
| Instruction files | `CLAUDE.md`, `.claude/CLAUDE.md`, `AGENTS.md`, `.claude/rules/*.md` |
| Hooks | the `hooks` block of `.claude/settings.json` and each script it runs |
| Subagents | `.claude/agents/*.md` |
| Permissions and tools | the `permissions` block of `.claude/settings.json` |
| Context and cache | the run usage that the harness records, and the always-on files |

Measure a size on the delivered file, not on its source.

**4 Run the gates.** In a basicly repository, run each command and read its summary line:

```sh
basicly catalog lint
basicly skills-check
basicly check
basicly hooks-check
basicly agents-check
basicly permissions-check
```

A gate that fails is a finding. Fix its cause, never the gate.

**5 Report and fix.** Report one row per finding:

| Rule | Source | Evidence | Verdict | Fix |
| --- | --- | --- | --- | --- |

Put the findings that fail first. File one tracker record for each class of finding, then fix it.
When the checklist is stale, update `references/checklist.md` in the same change. When a mistake
can repeat, propose a lint or a test that refuses it.