Documentation Audit: Primary User-Facing Files

Audit date: 2026-02-02 Auditor: Technical writing agent (Claude Opus 4.5) Scope: README.md, SKILLS_GUIDE.md, QUICKSTART.md, CONTRIBUTING.md Supporting context: docs/COMMON_GROUND.md, docs/WORKFLOW_COMMANDS.md, CHANGELOG.md, docs/ideas/documentation-site.md

---

Executive Summary

The four primary documents serve different audiences but suffer from significant content overlap, inconsistent naming conventions, and a structural problem: README.md tries to be both a landing page and a comprehensive reference. SKILLS_GUIDE.md is the strongest standalone document. QUICKSTART.md and CONTRIBUTING.md both contain stale installation instructions that diverge from the README. The biggest single improvement would be thinning the README to a focused landing page and letting specialized documents own their respective topics.

---

Per-File Findings

1. README.md

Purpose: Project landing page and primary discovery surface (GitHub, search engines, LLM retrieval).

Strengths:

• Strong visual presentation with badges, animated header, star history
• Clear "Quick Start" section at the top with copy-paste install command
• Well-structured project tree showing directory layout
• Good use of the Documentation section as a hub linking to specialized docs
• Tech Stack Coverage section serves as an effective keyword surface for search/discovery

Weaknesses:

1. Tries to be everything. At 438 lines, the README functions as landing page, architecture guide, skills catalog, installation manual, usage tutorial, contributing guide, and marketing page. No single audience can scan it efficiently. A first-time visitor looking for "how do I install this" must scroll past architecture diagrams and 65-skill category lists.

2. Duplicate installation instructions. Three installation options appear in the "Quick Start" section at the top AND again in "Installation Options" at line 305. These two sections use different option numbering (the Installation Options section has two entries both labeled "Option 2"), different ordering, and different levels of detail.

3. Skills Overview duplicates SKILLS_GUIDE.md. Lines 116-133 reproduce a condensed version of the skill catalog that also lives in SKILLS_GUIDE.md. When skills are added or recategorized, both must be updated. Neither is clearly the source of truth.

4. Context Engineering section duplicates docs/COMMON_GROUND.md. Lines 182-227 reproduce the overview, command examples, confidence tiers, and mermaid graph that all exist in greater detail in docs/COMMON_GROUND.md. This section is 45 lines of content that could be 5 lines and a link.

5. Project Workflow Commands section duplicates docs/WORKFLOW_COMMANDS.md. Lines 229-242 duplicate the phase table from the workflow docs. The README should link, not reproduce.

6. Contributing section duplicates CONTRIBUTING.md. Lines 362-401 contain a condensed "Adding a New Skill" guide that partially overlaps with CONTRIBUTING.md but uses different line-count guidance (200-400 lines per reference here vs. no specific range in CONTRIBUTING.md). The frontmatter example in the README uses name: My Skill (with spaces), while CONTRIBUTING.md uses a different description formula. CLAUDE.md says names must be "letters, numbers, and hyphens only."

7. Stale option numbering. Under "Installation Options," there are two sections both labeled "Option 2" (npx add-skill and Local Development). Option 3 (Direct Installation) should logically be Option 4, or the npx method should be Option 2 and Local Development should be Option 3.

8. Tech Stack Coverage is a wall of text. Lines 244-297 list every supported technology in a flat bullet list. This is useful for SEO keyword density on GitHub but provides no navigational value. A reader cannot determine which skill covers which technology from this list alone.

Recommendations:

• Thin the README to under 200 lines: hero, one-line description, single install command, 3-sentence "what is this," link hub to specialized docs, contributing CTA, license/support
• Move architecture details to a dedicated docs/ARCHITECTURE.md or let the future docs site own it
• Remove the inline skills catalog; replace with a single sentence and link to SKILLS_GUIDE.md
• Remove the inline Context Engineering section; replace with a 2-line summary and link to docs/COMMON_GROUND.md
• Remove the inline Workflow Commands section; link to docs/WORKFLOW_COMMANDS.md
• Remove the inline Contributing guide; link to CONTRIBUTING.md
• Fix the duplicate "Option 2" numbering immediately (this is a bug regardless of restructuring)
• Consider moving Tech Stack Coverage to SKILLS_GUIDE.md where it provides navigational context

---

2. SKILLS_GUIDE.md

Purpose: Quick reference for which skill to use when.

Strengths:

• Clear, scannable structure with consistent formatting throughout
• Decision trees are genuinely useful -- they answer the question "I have X problem, which skill do I use?"
• Skill Combinations section provides practical multi-skill workflow patterns
• Examples section with "Good Prompts" gives concrete, actionable guidance
• No unnecessary preamble; gets straight to content
• The flattest, most reference-like document in the set -- appropriate for its purpose

Weaknesses:

1. No introduction or context. The document opens with ## When to Use Each Skill with no preamble explaining what this document is, who it is for, or how it relates to the rest of the project. A single paragraph at the top would help.

2. Category counts diverge from README. The README lists 12 categories; SKILLS_GUIDE.md lists 12 categories but with different groupings. For example, README has "Workflow (2): Debugging Wizard, Fullstack Guardian" as a category, while SKILLS_GUIDE.md has the same skills under a "Workflow" heading. This is consistent, but the README's parenthetical counts (e.g., "Languages (12)") are not replicated here, making cross-reference verification manual.

3. Examples section is excessively long. Lines 257-322 contain 50+ example prompts across 7 subsections. This is valuable content, but the sheer volume makes it hard to scan. The most common use cases (top 10) should be separated from the exhaustive list.

4. No link back to README or installation. A reader who lands here directly (via search, deep link, or LLM referral) has no way to learn how to install the plugin. A single line at the top with a link to the README or QUICKSTART.md would solve this.

5. "Tips for Effective Use" is generic. The 5 tips at line 249-255 are so general ("Be Specific," "Context Matters") that they add little value. They duplicate the more concrete best practices in QUICKSTART.md.

6. Missing: which skills are new or recently updated. For returning users, a "What's New" callout at the top referencing the latest release would help.

Recommendations:

• Add a 2-3 line introduction with a link to README.md and QUICKSTART.md
• Trim the Examples section: keep the top 16 "Good Prompts" and move the framework-specific, language-specific, and platform-specific examples into a collapsible section or separate file
• Remove or merge "Tips for Effective Use" into QUICKSTART.md where it belongs
• Consider adding a "Last updated: vX.Y.Z" line at the top so readers know if content is current

---

3. QUICKSTART.md

Purpose: Get a new user from zero to working installation in minutes.

Strengths:

• Starts with installation immediately -- no preamble
• Three installation methods presented concisely
• "Test Your Installation" section is a strong inclusion -- gives the user a way to verify success
• "Quick Reference Card" at the bottom is a genuinely useful cheat sheet
• Reasonable length (208 lines)

Weaknesses:

1. Installation instructions diverge from README. QUICKSTART.md offers three methods: Marketplace, Install from GitHub (claude plugin install https://...), and Local Development (cp -r). README.md offers four methods: Marketplace, npx add-skill, Local Development, and Direct Installation. The "Install from GitHub" method in QUICKSTART.md (claude plugin install https://...) does not appear in the README at all. The npx method in the README does not appear in QUICKSTART.md. This is confusing and suggests neither document is the source of truth.

2. Skill counts may go stale. Lines 50-54 contain hardcoded counts ("12 Language Experts," "10 Backend Framework Experts," "7 Frontend & Mobile Experts"). These are not wrapped in `` markers and will not be updated by scripts/update-docs.py. The "10 Backend Framework Experts" claim conflicts with the README, which lists 7 in the "Backend Frameworks" category.

3. "First Steps" section mixes audiences. Subsections 1-4 cover what the plugin contains (reference), common use cases (tutorial), best practices (guidance), and skill activation examples (reference). This interleaving makes it hard to follow a linear getting-started path.

4. "Follow Recommended Workflows" duplicates SKILLS_GUIDE.md. The 7-step new feature workflow at lines 127-134 is identical to the "New Feature Development" workflow in SKILLS_GUIDE.md lines 96-104. One should link to the other.

5. References section at line 136-139 is incomplete. It lists README.md, SKILLS_GUIDE.md, and CONTRIBUTING.md, but omits docs/COMMON_GROUND.md and docs/WORKFLOW_COMMANDS.md.

6. Troubleshooting is thin. Only two scenarios are covered (skills not activating, need help). Common issues like "I installed but Claude does not seem to use the skills" or "how do I update to the latest version" are not addressed.

7. Closing tone is informal. "Happy coding!" with a rocket emoji is not consistent with the professional tone of the rest of the documentation set.

Recommendations:

• Consolidate installation instructions with the README. One document should be the canonical source; the other should link to it. Recommendation: QUICKSTART.md owns the detailed install instructions; README.md has a one-liner and a link.
• Fix the stale "10 Backend Framework Experts" count (should be 7 per README categories, or 8 if counting Express separately)
• Restructure "First Steps" into a linear flow: Install -> Verify -> Try your first prompt -> Learn more
• Remove the duplicated workflow; link to SKILLS_GUIDE.md
• Expand the Troubleshooting section with 2-3 more common scenarios
• Add "How to update" instructions
• Remove the closing emoji; end with the Support section

---

4. CONTRIBUTING.md

Purpose: Guide contributors through the process of adding or modifying skills.

Strengths:

• Clear step-by-step contribution workflow (fork, branch, change, test, commit, PR)
• Commit message format is well-defined
• Progressive Disclosure Pattern section is thorough and well-explained
• Token Efficiency Guidelines are specific and actionable
• Code Examples Best Practices section sets a clear standard
• Framework Version Requirements table pins versions -- good for consistency

Weaknesses:

1. Frontmatter schema conflicts with CLAUDE.md. CONTRIBUTING.md line 88 shows name: Skill Name (with a space), but CLAUDE.md explicitly states: "name: Letters, numbers, and hyphens only (no parentheses or special characters)." The description formula on line 103 ([Role] for [Domain]. Invoke for [triggers]. Keywords: [terms].) conflicts with CLAUDE.md's mandate: "descriptions must be TRIGGER-ONLY" and "Format: Use when [specific triggering conditions]." These are not minor style differences; they will produce skills that fail validation.

2. Missing validation step. The contribution workflow (steps 1-6) does not mention running python scripts/validate-skills.py before submitting a PR. Given that CI runs this check, contributors will hit failures they could have caught locally. This should be step 4.5.

3. Reference file guidance is vague. The README says "200-400 lines each" for references. CLAUDE.md says "100-600 lines per reference file." CONTRIBUTING.md's Progressive Disclosure section says "200 lines" as a threshold for when to split, but does not state a target range. Three different documents give three different numbers.

4. Testing instructions are impractical. Step 4 says to cp -r skills/* ~/.claude/skills/ and restart Claude Code. For marketplace-installed plugins, this method may not work or may conflict with the installed version. No guidance is given for testing with the marketplace/local plugin workflow.

5. No mention of the commands/ directory. The guide covers skill creation in detail but says nothing about creating or modifying workflow commands. A contributor looking to add a command has no guidance.

6. Code of Conduct is minimal. Three short subsections (Be Respectful, Be Collaborative, Be Professional) with two bullet points each. This is fine for a small project but may need expansion as community grows. Consider linking to a standard CoC (e.g., Contributor Covenant) instead of maintaining a custom one.

7. "Recognition" section references a CONTRIBUTORS.md file. This file does not appear in the project structure shown in README.md. If it exists, it should be linked. If it does not exist, this is a broken promise.

Recommendations:

• Align the frontmatter schema with CLAUDE.md immediately. The description formula must say "Use when [triggering conditions]," not the [Role] for [Domain] pattern. The name field must show a hyphenated example.
• Add python scripts/validate-skills.py --skill my-new-skill as an explicit step before submitting a PR
• Standardize reference file line guidance across all documents (CLAUDE.md's 100-600 range is the most permissive; pick one range and use it everywhere)
• Add a section on contributing workflow commands
• Link or create the CONTRIBUTORS.md file
• Add a note about testing with the marketplace install method

---

Cross-File Redundancy Map

The following content appears in multiple documents. For each topic, one document should be the single source of truth (SSoT); all others should link to it.