arthai-marketplace

/docs

Audit and generate documentation for skills, agents, and hooks — including full per-skill customer doc pages.

Synopsis

/docs <audit|write|check> [skill-name]

When to use it

• You’ve added a project-specific skill, agent, or hook and want its documentation written to the same standard as the toolkit’s own pages
• You want a coverage report: which skills have full doc pages, which have quality drift (stale one-liners, broken links, missing sections)
• In CI or a pre-PR hook, to gate new skills on meeting the documentation bar
• Not for: writing your application’s docs (READMEs, API docs for your product code) — /docs documents the toolkit surface (skills/agents/hooks), not your app

Quickstart

/docs audit

What you’ll see: a report listing which skills meet the full documentation bar, which are missing pages, and which have quality issues (e.g., a synopsis that drifted from the skill’s actual usage string), with a next action per item.

Examples

/docs audit              # coverage + quality report, no writes
/docs write my-skill     # generate the full doc page for one skill
/docs write              # sweep mode — fix README/GETTING-STARTED mention gaps and list skills needing pages (no page generation)
/docs check              # silent pass/fail gate — exit 1 if a newly added skill lacks docs

Arguments & flags

Argument	Values	Default	What it does
mode	audit, write, check	audit	Report gaps / generate docs / CI gate
[skill-name]	any skill (optional)	—	With write: generate that skill’s full page. Without a skill name, write runs sweep mode instead — it fixes README/GETTING-STARTED mention gaps and lists which skills still need pages; it does not generate any page.

What it does

1. Detects scope — in check mode, only skills/agents/hooks added in the current branch (requires the project to be git-initialized with a main branch to diff against); in audit/write mode, every user-invocable skill.
2. Checks each item against the documentation bar — a doc page exists with all required sections: Synopsis, When to use it, Quickstart, Examples, What it does, Output, Troubleshooting, and Related (defined in customer-docs/skills-page-required-sections.txt); the page’s one-liner matches the skill’s frontmatter description (the description text before its “Usage:” clause — anything after “Usage:” is stripped before comparing); the synopsis matches its usage string; the skill is reachable from at least one task surface (routing table, workflow guide); relative links resolve; the name is mentioned in the README and getting-started guide.
3. Audit mode — prints the report: items at full bar, items missing pages (the backfill queue), and quality issues per item. No writes.
4. Write mode with a skill name — reads the skill’s SKILL.md in full (requires customer-docs/docs/skills/_TEMPLATE.md to exist) and generates the page from the template: phases become the “What it does” list, confirmation gates are marked explicitly, artifacts and troubleshooting come from the skill body. Inferred prose is marked <!-- draft: review --> for human review. It also proposes the task-surface placement — the exact routing-table row or workflow entry where the new skill should appear. You then run ./generate-docs.sh && ./generate-site.sh yourself to regenerate the reference tables and render the page on the site (verify zero WARN lines) — the skill does not run the generators for you.
5. Write mode without a name — fixes README/getting-started mention gaps and lists which skills still need pages; it deliberately does not mass-generate pages, since each page needs review.
6. Check mode — exits 0 silently when complete, exits 1 with the gap list when a new skill is below the bar (used by the pre-PR docs hook and CI).

Output & artifacts

• Audit/check report in the conversation (check mode also sets the exit code for CI)
• Write mode: a new per-skill doc page with all required sections, plus a proposed task-surface placement. Run ./generate-docs.sh && ./generate-site.sh afterward to regenerate the reference tables/site so the page is linked — the skill itself does not run these generators.
• README and getting-started mention entries where missing

Troubleshooting

Problem	Fix
A reference-table row is wrong	Fix the source (the skill’s frontmatter description), not the generated file — then re-run the generators
Generated page sections feel generic	That’s what the <!-- draft: review --> markers are for — review and edit; a page that parrots its one-liner into every section fails audit
check fails your PR for a new skill	Run /docs write <name>, review the page, and add the skill to a task surface
Page exists but audit still flags it	Likely drift: the one-liner or synopsis no longer matches the skill’s frontmatter — update whichever is stale
write <name> fails to generate a page	Confirm customer-docs/docs/skills/_TEMPLATE.md exists — write mode requires it
New page isn’t showing up on the site/reference tables	Write mode doesn’t run the generators for you — run ./generate-docs.sh && ./generate-site.sh and check for zero WARN lines

Related

• /calibrate — creates the project-specific skills and agents you’ll want documented
• /scan — populates CLAUDE.md project context; /docs covers the toolkit surface
• /pr — the pre-PR docs check runs as part of shipping a new skill