docs-audit
Skill490 starsChanged 6 days agoApache-2.0View on GitHub
Assess an existing Box documentation page (docs/user/, docs/design/, or a crate README.md) for accuracy against the code and its tests, placement, and voice, and recommend what to fix. Use before a rewrite, when a page may have drifted from the code, or when asked to "audit this page", "is this page still true", or "what is wrong with this doc".
We split this skill into the rules it gives an agent
5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 10 edited versions we read keep these.
4
Distinctive
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 24
Read the page. Classify its guide and its content type.
- Very specific: line 29
Follow claim-verification.md.
- Distinctive: line 35
Check each of these:
- Distinctive: line 55
Check the list in "Readers that are people and readers that are agents" in the voice guide.
- Distinctive: line 59
Run this step only for a design page about a topic that other sandboxes also document: the architecture, the security model, containment, …
“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Documentation audit
Assess one existing page, and produce a structured assessment with the fixes in priority order.
How this differs from docs-reviewer. The reviewer is a voice gate for a draft. The audit is
for a page that already exists: it checks each claim against the code and its tests, finds the
gaps, and decides what needs work. Use the audit to decide what to fix. Use the reviewer to decide
that a draft can ship.
Inputs
- Target page: a path in the repository.
- Context (optional): an issue, a changed behavior, or a concern.
Process
Step 1: Read and classify
Read the page. Classify its guide and its content type. A page that mixes types is itself a finding, and it is the most common structural problem.
Step 2: Accuracy
Follow claim-verification.md. List each claim on the
page, and check it against the code and the test that pins it.
The code is the authority. Where the page and the code disagree, the page is wrong. Name the symbol or the test that the page disagrees with. Never recommend a code change to agree with a page.
Check each of these:
- Each
box.tomlkey, type, and default against the configuration parser. - Each CLI verb, flag, and exit code against the argument parser.
- Each policy action and field against
strands-box policy generate-schema. - Each binary name against what ships (
Cargo.toml, and the staging step in.github/workflows/deploy-box-artifact.yml). - A test still pins each claim. A test name on a design page is itself a finding.
- Each
decisions.mdanchor still exists, and the decision still says what the page says. - Each relative link resolves.
- Each claim that a test pins is not stated more broadly than the test.
Step 3: Voice
Walk the five layers of voice-guide.md: structure, framing,
register, hard constraints, and authenticity. Run
.agents/skills/docs-reviewer/check-prose.sh <page> for the mechanical part.
Step 4: Stands alone
Check the list in "Readers that are people and readers that are agents" in the voice guide.
Step 5: Comparison (optional)
Run this step only for a design page about a topic that other sandboxes also document: the architecture, the security model, containment, egress, or credentials. Read one to three pages from comparable projects, for example the gVisor architecture guide, the Firecracker design document, or a coding-agent sandbox's security page. Cite each URL and the date you read it. Give one observation for each of coverage, depth, and structure. Copy structure or coverage only, never voice.
Output format
## Docs audit: <page title>
**Path:** <path>
**Guide and type:** <guide>, <type>
**Verdict:** Strong | Needs work | Significant gaps
| Layer | Score | Key finding |
|---|---|---|
| Structure | ... | ... |
| Framing | ... | ... |
| Register | ... | ... |
| Constraints | ... | <count of hits> |
| Authenticity | ... | ... |
### Accuracy issues
- <The claim, the line, and the symbol or the test it disagrees with.> Or "None found".
### Stands-alone issues
- <Each issue.> Or "Passes".
### Recommended actions
1. <The fix with the highest priority.>
2. ...
### Comparison (if run)
- <One observation per axis, with the source.>What this skill does not do
- Rewrite the page. That is
docs-writer. - Edit any file, or commit.
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- mastra-ai/mastra★ 29ksame name
- strands-agents/sdk-python★ 9ksame name
- strands-agents/harness-sdk★ 8.9ksame name
- hiroppy/tmux-agent-sidebar★ 545same name
- me2resh/apexyard★ 532same name
- Seekers2001/docs-governance★ 320same name
- qshanx/docs-governance★ 253same name
- willdady/platypus★ 126same name
- colonyops/hive★ 39same name
- hay-kot/hive-desktop★ 4same name
3 more not listed
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.
Used alongsideProjects with it also use docs-diagrams, writing-for-agents and 2 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
VercelSkilldocs-diagrams
Draw diagrams for the Next.js docs in the style of the ones already published there: the light/dark PNGs an mdx references with `<Image srcLight="/docs/light/<name>.png" srcDark="/docs/dark/<name>.png">`. Use when a guide or API reference needs a new diagram or an existing one needs a change. Hand-written SVG from a primitives library, rendered by headless Chrome at 2x. No AI image generation.
Also in 3 projects that use this
MicrosoftSkillwriting-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
Also in 3 projects that use this
GoogleSkilldomain-modeling
Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
Also in 3 projects that use this
- MicrosoftSkill
release
Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).
Also in 3 projects that use this
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- authoring-box-policySkill
- debug-os-failure-on-githubSkill
- docs-plannerSkill
- docs-reviewerSkill
- docs-syncSkill
- docs-writerSkill
- exploreSkill
- kdSkill
- setting-up-a-boxSkill
- specSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
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.