best-practices-audit
Skill2 starsChanged 7 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/handilyedited, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- niksavis/handily★ 278% 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 repository58 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- 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
- 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
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Fetch only the listed sources: Ask the user before you fetch any other URL.
- Distinctive: line 19
Mark an API-only rule "not applicable": when the repository does not call the Messages API.
- Distinctive: line 35
1 Pull the current docs: Run the script from the directory of this skill.
- Distinctive: line 51
2 Compare the docs with the checklist: Read each fetched page for rules on skills, instruction files, hooks, subagents, permissions, …
- Very specific: line 79
When the checklist is stale, update references/checklist.md in the same change.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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 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 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.
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.
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.