Synchronizes CLAUDE.md navigation indexes and README.md architecture docs across a repository. Use when asked to "sync docs", "update CLAUDE.md files", "ensure documentation is in sync", "audit documentation", or when documentation maintenance is needed after code changes.
Synchronizes CLAUDE.md navigation indexes and README.md architecture documentation across repository directories.
/plugin marketplace add rjmurillo/ai-agents/plugin install project-toolkit@ai-agentsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Maintains the CLAUDE.md navigation hierarchy and optional README.md architecture docs across a repository. This skill is self-contained and performs all documentation work directly.
| Trigger Phrase | Operation |
|---|---|
sync docs | Repository-wide CLAUDE.md audit and update |
update CLAUDE.md files | Repository-wide index refresh |
sync docs in src/parser/ | Directory-scoped index update |
audit documentation | Full discovery, audit, and drift report |
update CLAUDE.md for config.py | Single-file parent directory update |
Use this skill when:
Use direct editing instead when:
After execution:
Determine scope FIRST:
| User Request | Scope |
|---|---|
| "sync docs" / "update documentation" / no specific path | REPOSITORY-WIDE |
| "sync docs in src/validator/" | DIRECTORY: src/validator/ and descendants |
| "update CLAUDE.md for parser.py" | FILE: single file's parent directory |
For REPOSITORY-WIDE scope, perform a full audit. For narrower scopes, operate only within the specified boundary.
Use tabular format with What and When columns:
## Files
| File | What | When to read |
| ----------- | ------------------------------ | ----------------------------------------- |
| `cache.rs` | LRU cache with O(1) operations | Implementing caching, debugging evictions |
| `errors.rs` | Error types and Result aliases | Adding error variants, handling failures |
## Subdirectories
| Directory | What | When to read |
| ----------- | ----------------------------- | ----------------------------------------- |
| `config/` | Runtime configuration loading | Adding config options, modifying defaults |
| `handlers/` | HTTP request handlers | Adding endpoints, modifying request flow |
cache.rs, config/-Given task "add a new validation rule", can an LLM scan the "When to read" column and identify the right file?
ROOT CLAUDE.md:
# [Project Name]
[One sentence: what this is]
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
## Build
[Copy-pasteable command]
## Test
[Copy-pasteable command]
## Development
[Setup instructions, environment requirements, workflow notes]
SUBDIRECTORY CLAUDE.md:
# [directory-name]/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
Critical constraint: Subdirectory CLAUDE.md files are PURE INDEX. No prose, no overview sections, no architectural explanations. Those belong in README.md.
Create README.md ONLY when the directory contains knowledge NOT visible from reading the code:
DO NOT create README.md when:
For each sentence in README.md, ask: "Could a developer learn this by reading the source files?"
README.md earns its tokens by providing INVISIBLE knowledge: the reasoning behind the code, not descriptions of the code.
# [Component Name]
## Overview
[One paragraph: what problem this solves, high-level approach]
## Architecture
[How sub-components interact; data flow; key abstractions]
## Design Decisions
[Tradeoffs made and why; alternatives considered]
## Invariants
[Rules that must be maintained; constraints not enforced by code]
Map directories requiring CLAUDE.md verification:
# Find all directories (excluding .git, node_modules, __pycache__, etc.)
find . -type d \( -name .git -o -name node_modules -o -name __pycache__ -o -name .venv -o -name target -o -name dist -o -name build \) -prune -o -type d -print
For each directory in scope, record:
For each directory, check for drift and misplaced content:
<audit_check dir="[path]">
CLAUDE.md exists: [YES/NO]
Has table-based index: [YES/NO]
Files in directory: [list]
Files in index: [list]
Missing from index: [list]
Stale in index (file deleted): [list]
Triggers are task-oriented: [YES/NO/PARTIAL]
Contains misplaced content: [YES/NO] (architecture/design docs that belong in README.md)
README.md exists: [YES/NO]
README.md warranted: [YES/NO] (invisible knowledge present?)
</audit_check>
Critical: If CLAUDE.md contains content that does NOT belong there, migrate it:
Content that MUST be moved from CLAUDE.md to README.md:
Migration process:
For each directory needing work:
Creating/Updating CLAUDE.md:
Creating README.md (only when warranted):
After all updates complete, verify:
## Doc Sync Report
### Scope: [REPOSITORY-WIDE | directory path]
### Changes Made
- CREATED: [list of new CLAUDE.md files]
- UPDATED: [list of modified CLAUDE.md files]
- MIGRATED: [list of content moved from CLAUDE.md to README.md]
- CREATED: [list of new README.md files]
- FLAGGED: [any issues requiring human decision]
### Verification
- Directories audited: [count]
- CLAUDE.md coverage: [count]/[total] (100%)
- Drift detected: [count] entries fixed
- Content migrations: [count] (architecture docs moved to README.md)
- README.md files: [count] (only where warranted)
DO NOT index:
DO index:
| Avoid | Why | Instead |
|---|---|---|
| Vague "When to read" triggers | Matches everything, helps nothing | Use specific action verbs: "implementing", "debugging" |
| Putting architecture prose in subdirectory CLAUDE.md | CLAUDE.md is pure index | Move to README.md, index the README |
| Recreating CLAUDE.md from memory | Misses files, wrong format | Run discovery phase, use template |
| Syncing a single file without checking parent index | Creates partial drift | Always verify parent directory index too |
| Creating README.md for simple directories | Token waste, redundant with code | Apply invisible knowledge test first |
Too vague (matches everything):
| `config/` | Configuration | Working with configuration |
Content description instead of trigger:
| `cache.rs` | Contains the LRU cache implementation | - |
Missing action verb:
| `parser.py` | Input parsing | Input parsing and format handling |
| `cache.rs` | LRU cache with O(1) get/set | Implementing caching, debugging misses, tuning eviction |
| `config/` | YAML config parsing, env overrides | Adding config options, changing defaults, debugging config loading |
For additional trigger pattern examples, see references/trigger-patterns.md.
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.