# Best Practices Audit

> Audits skills, instructions, hooks, agents and permissions against the newest vendor docs. Use after a Claude Code release, or when asked if the harness still follows Anthropic guidance.

- Skill: `niksavis/best-practices-audit` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add niksavis/best-practices-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/niksavis/best-practices-audit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: niksavis (https://skillmd.com/u/niksavis)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/niksavis/best-practices-audit

---

<!-- 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.
- **Keep fetched pages in the scratch directory; never commit them.** The script refuses an `--out` inside a git working tree.
- **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.

## 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.11 or later
and no package:

```sh
python3 scripts/fetch_docs.py
```

| Exit | Meaning | Next |
| --- | --- | --- |
| 0 | Every page arrived | Continue |
| 1 | Some pages failed | Continue, and name each failed page in the report |
| 2 | Refused: `--out` is a file or inside a git tree | Omit `--out` |
| 3 | 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 projected file, not on the catalog YAML.

**4 Run the gates.** In a basicly repository, run the projection gates that `CLAUDE.md` lists, plus `basicly catalog lint`, and read each summary line. A gate that fails is a finding.

**5 Report and fix.** A finding is a checklist row that fails, a stale checklist rule or a failed gate. Report one row per finding, and the count of passing and not-applicable rows in one line:

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

File one tracker record for each class of finding, then fix it. Fix a skill, fragment or agent in its catalog YAML as `catalog-authoring` shows, never the projected file.
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.

