Best-Practices Audit
Compare the harness files with the vendor documentation of today, not with what you remember. The checklist in 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
--outinside 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:
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:
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.