agentleFS
niksavisniksavis/handily/.agents/skills/best-practices-audit/SKILL.md

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

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
  1. Distinctive:

    Mark an API-only rule "not applicable": when the repository does not call the Messages API.

    line 20
  2. Distinctive:

    1 Pull the current docs: Run the script from the directory of this skill.

    line 36
  3. Very specific:

    When the fetch used --out, pass the same directory to discovery.

    line 58
  4. Distinctive:

    Treat either condition as incomplete discovery.

    line 62
  5. Distinctive:

    2 Compare the docs with the checklist: Read each fetched page for rules on skills, instruction files, hooks, subagents, permissions, …

    line 66
  6. Very specific:

    Read both claude-code-index.txt and claude-platform-index.txt for relevant pages outside the discovery routes.

    line 70
  7. Distinctive:

    Use requirement only for explicit constraints on the interface in use.

    line 74
  8. Distinctive:

    Do not treat a recommendation as a vendor requirement.

    line 77
  9. Very specific:

    When the checklist is stale, update references/checklist.md in the same change.

    line 100

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- 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 --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:

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
ExitMeaningNext
0Every page arrivedContinue
1Some pages failedContinue, and name each failed page in the report
2Refused: --out is a file or inside a git treeOmit --out
3Offline, nothing arrivedAudit 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 --discover

When 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:

SubjectFiles
Skills.claude/skills/*/SKILL.md, and in basicly the skill.yaml sources
Instruction filesCLAUDE.md, .claude/CLAUDE.md, AGENTS.md, .claude/rules/*.md
Hooksthe hooks block of .claude/settings.json and each script it runs
Subagents.claude/agents/*.md
Permissions and toolsthe permissions block of .claude/settings.json
Context and cachethe 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.