Auditing Developer Docs

In this tutorial, you will load the developer-docs-authoring bundle from the Musher Hub and use its agents and skills to audit and improve a project's developer documentation. By the end, you will have a repeatable documentation quality workflow powered by a community bundle.

Prerequisites

• musher CLI installed
• A Musher account (see Getting Started)
• A project with some existing documentation (even a README counts)
• An AI coding agent (Claude Code, Codex, or similar)

Step 1: Find the Bundle on the Hub

Browse the Musher Hub to find the developer-docs-authoring bundle published by Musher. You can search for it directly or browse the documentation category.

You can also search from the CLI. Run musher search to open the interactive search TUI, or use it non-interactively:

musher hub info musher/developer-docs-authoring

The bundle page shows you what's inside before you install anything:

• 6 agents — specialized roles like docs-designer, quality-reviewer, and site-architect
• 15 skills — covering navigation design, content quality auditing, accessibility compliance, and more

Take a moment to read the bundle's description and review its asset list. Understanding what a bundle provides helps you use it effectively.

Step 2: Load the Bundle

Now that you know what the bundle contains, load it into your project. The load command downloads the bundle, shows a preview of its contents, and lets you select a harness:

musher load musher/developer-docs-authoring

The CLI opens an interactive TUI where you can review the bundle's assets and choose how to use it. In non-interactive environments (CI, scripts), use --harness to specify the target directly:

musher load musher/developer-docs-authoring --harness claude

Step 3: Run with Your Harness

If you want to download, install, and launch your harness in a single step, use musher run instead:

musher run musher/developer-docs-authoring --harness claude

This downloads the bundle (if not already cached), materializes the assets into your harness's directory layout, launches the harness, and cleans up injected files when the session ends.

For Claude Code, agents land in .claude/agents/ and skills in .claude/skills/. Your AI agent automatically picks them up from these paths.

Step 4: Run a Documentation Audit

Open your AI coding agent in the project directory. The installed agents are now available. Start with the quality-reviewer to get a baseline score of your documentation:

Score our developer documentation against the editorial quality rubric —
check findability, accuracy, clarity, task orientation, and readability.

The quality-reviewer agent evaluates your docs across five dimensions and produces a structured report with scores and specific remediation guidance. A typical output looks like:

Documentation Quality Audit
===========================

Findability:      7/10  — Navigation is clear but missing breadcrumbs on nested pages
Accuracy:         8/10  — Code examples are current; one outdated API parameter found
Clarity:          6/10  — Several pages mix tutorial and reference content
Task Orientation: 5/10  — Getting started guide assumes too much prior knowledge
Readability:      7/10  — Good use of headings; some paragraphs exceed 4 sentences

Overall: 6.6/10 — NEEDS IMPROVEMENT

Top 3 Recommendations:
1. Separate tutorial content from reference pages (Clarity, Task Orientation)
2. Add prerequisite callouts to the getting started guide (Task Orientation)
3. Add breadcrumb navigation to nested documentation (Findability)

You can also use the site-architect agent for a structural analysis — coverage gaps, orphan pages, and broken navigation paths:

Analyze our documentation site architecture — find orphan pages,
coverage gaps, and broken navigation paths.

Step 5: Act on the Results

Now use the audit results to improve your documentation. The page-scaffolder agent generates structurally correct pages based on the gaps you found:

Scaffold a quickstart page for our Python SDK with Diataxis-aligned
structure and working code examples.

The scaffolder produces a complete page following the quickstart archetype — introduction, prerequisites, numbered steps with working code, and next steps.

For existing pages that scored low, use the docs-designer agent to restructure and improve them:

Redesign our getting started guide — improve task orientation,
add prerequisite callouts, and separate tutorial from reference content.

After making improvements, run the quality-reviewer again to measure your progress against the baseline.

What You Accomplished

In this tutorial, you:

1. Discovered a bundle on the Hub and reviewed its contents
2. Loaded the bundle and selected a harness with musher load
3. Ran a documentation audit with the quality-reviewer and site-architect
4. Improved your docs using the page-scaffolder and docs-designer

This workflow is repeatable — run the quality audit before any documentation release to catch regressions. As the bundle is updated with new skills and improvements, load the latest version to keep your workflow current.

Next Steps