best-practices-audit
Skill2 starsChanged 34 days agoMITView on GitHub
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.
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- niksavis/basiclyedited, first seen Nov 15, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- niksavis/basicly★ 273% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository60 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- catalog-authoringSkill
- cli-toolsSkill
- conventional-commitsSkill
- councilSkill
- decompose-planSkill
- falsify-firstSkill
- find-skillsSkill
- harness-clientSkill
- harness-loopSkill
- hill-climbSkill
- interface-factsSkill
- no-commentsSkill
- nodeSkill
- plain-englishSkill
- pythonSkill
- release-processSkill
- repair-in-placeSkill
- retention-probeSkill
- root-causeSkill
- session-finishSkill
- skill-creatorSkill
- swarmSkill
- test-disciplineSkill
- tier-injectionSkill
- validate-as-consumerSkill
- work-trackerSkill
- worktree-isolationSkill
- wslSkill
- best-practices-auditSkill
- catalog-authoringSkill
- cli-toolsSkill
- conventional-commitsSkill
- councilSkill
- decompose-planSkill
- falsify-firstSkill
- find-skillsSkill
- harness-clientSkill
- harness-loopSkill
- hill-climbSkill
- interface-factsSkill
- no-commentsSkill
- nodeSkill
- plain-englishSkill
- pythonSkill
- release-processSkill
- repair-in-placeSkill
- retention-probeSkill
- root-causeSkill
- session-finishSkill
- skill-creatorSkill
- swarmSkill
- test-disciplineSkill
- tier-injectionSkill
- validate-as-consumerSkill
- work-trackerSkill
- worktree-isolationSkill
- wslSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Mark an API-only rule "not applicable": when the repository does not call the Messages API.
- Distinctive: line 36
1 Pull the current docs: Run the script from the directory of this skill.
- Very specific: line 58
When the fetch used --out, pass the same directory to discovery.
- Distinctive: line 62
Treat either condition as incomplete discovery.
- Distinctive: line 66
2 Compare the docs with the checklist: Read each fetched page for rules on skills, instruction files, hooks, subagents, permissions, …
- Very specific: line 70
Read both claude-code-index.txt and claude-platform-index.txt for relevant pages outside the discovery routes.
- Distinctive: line 74
Use requirement only for explicit constraints on the interface in use.
- Distinctive: line 77
Do not treat a recommendation as a vendor requirement.
- Very specific: line 100
When the checklist is stale, update references/checklist.md in the same change.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- 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 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 listed sources by default. Discovery reports unlisted candidates without downloading them. Fetch an unlisted URL only within existing authorization or after approval.
- 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 fix1 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.
Discover model guides from the saved vendor indexes without a network call:
python3 scripts/fetch_docs.py --discoverWhen the fetch used --out, pass the same directory to discovery.
Discovery scans known prompting, migration, model update, effort, and advisor routes.
It excludes listed sources and limits the candidate report.
Exit code 1 reports unreadable indexes or omitted candidates.
Treat either condition as incomplete discovery.
Inspect the saved indexes when candidates were omitted.
An empty report does not prove that no relevant guide exists.
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. Review the model prompting guide against the models actually in use.
Read both claude-code-index.txt and claude-platform-index.txt for relevant pages outside the discovery routes.
Name unlisted sources in the report before deciding whether to fetch them.
Label each finding as a vendor requirement, vendor recommendation, or repository choice. Use requirement only for explicit constraints on the interface in use. For recommendations, state the observed problem and proposed measurement. For repository choices, cite the owning instruction or user decision. Do not treat a recommendation as a vendor requirement.
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 failed checklist row, stale rule, or failed gate. Report each finding with its classification, source, repository evidence, verdict, and proposed fix. Give passing and not-applicable counts separately.
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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

