docs: reconcile agent/skill counts (53/20) and add drift guard#90
Merged
PAMulligan merged 2 commits intoMay 25, 2026
Conversation
The README claimed 48 agents / 17 skills while the onboarding docs said 53 agents / 19 skills. The truth on disk is 53 agents (.claude/agents/) and 20 skills (.claude/skills/ dirs with a SKILL.md). The README also listed only 17 skills, omitting parallel-orchestration, screenshot-intake, and export-design-system. Update every live doc to 53/20 (README, onboarding/architecture.md and the rest of the onboarding set, react-development, CONTRIBUTING, CLAUDE.md, and the agent/skill catalogs). CHANGELOG.md is left untouched as a historical release record. Also fixes a stale "51 agents" tree comment in CLAUDE.md. Add scripts/check-doc-counts.sh: recounts .claude/agents/ and .claude/skills/ and fails on any documented count that disagrees (human-readable + --json). Wire it into the CI validate job and the husky pre-commit hook, with a matching test in scripts/__tests__/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
Resolve lint-and-format CI failure: - Reformat check-doc-counts.test.js per Prettier - Remove unused readdirSync import in verify-test-coverage.test.js - Remove unused fileName variable in generate-stories.js Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The README claimed 48 Custom Agents and 17 Development Skills, but the onboarding docs (and
docs/onboarding/architecture.md) referenced 53 agents, 19 skills. They disagreed, which confuses first-time readers.Ground truth on disk
Neither figure was fully correct:
.claude/agents/→ 53 agent.mdfiles.claude/skills/→ 20 skill directories (each with aSKILL.md)The README also enumerated only 17 skills, omitting
parallel-orchestration,screenshot-intake, andexport-design-system. A stale# 51 specialized agentstree comment inCLAUDE.mdwas also caught.Changes
Reconciled every live doc to 53 agents / 20 skills:
README.md— header, directory tree, agent category table (rebalanced to sum to 53), full 20-skill list, and documentation indexdocs/onboarding/architecture.md— system diagram, skills heading, and added the 20th skill (export-design-system).claude/skills/README.md— count + documented the 3 previously-missing skills (renumbered 1–20)CLAUDE.md,CONTRIBUTING.md,.claude/CUSTOM-AGENTS-GUIDE.md,docs/onboarding/README.md,docs/onboarding/quickstart.md,docs/react-development/README.mdCHANGELOG.mdis intentionally not modified — it is an auto-generated historical release record.New drift guard —
scripts/check-doc-counts.sh:.claude/agents/and.claude/skills/, then scans all Markdown (excludingCHANGELOG.mdanddocs/plans/) for anyN agents/N skillsclaim that disagrees. Human-readable output +--json; exits non-zero on drift.validatejob (.github/workflows/ci.yml) and the.husky/pre-commithook.scripts/__tests__/check-doc-counts.test.js, which recomputes expected counts from the filesystem so the test never goes stale.Verification
bash scripts/check-doc-counts.sh→✓ All agent/skill counts in docs match the entries on disk(exit 0), ~2.6sOut of scope (noted for a follow-up)
The
CLAUDE.mdfooter says "33 scripts" but there are ~35 — pre-existing drift in the script count, which this issue and the new checker do not cover.Closes #83
🤖 Generated with Claude Code