| name | codebase-analyzer |
| description | This skill should be used when the user asks to "initialize auto-memory", "create CLAUDE.md", "set up project memory", or runs the /auto-memory:init command. Analyzes codebase structure and generates CLAUDE.md files using the exact template format with AUTO-MANAGED markers. |
Codebase Analyzer
Analyze project structure and generate CLAUDE.md files interactively.
Guidelines
MANDATORY: All rules below must be followed exactly. Violations produce incorrect CLAUDE.md content.
@../shared/references/guidelines.md
Algorithm
1. Check Existing CLAUDE.md
If CLAUDE.md already exists, ask the user how to handle it:
- Migrate: Convert to auto-managed format (add markers)
- Backup: Create CLAUDE.md.backup and generate fresh
- Merge: Keep manual sections, add auto-managed sections
- Cancel: Abort initialization
2. Scan Directory Structure
Detect frameworks and build systems:
package.json - Node.js/JavaScriptpyproject.toml, setup.py - PythonCargo.toml - Rustgo.mod - GoMakefile - Make-based buildsDockerfile - Container builds
Extract build/test/lint commands from config files.
3. Identify Subtree Candidates
Look for framework boundaries that warrant separate CLAUDE.md files:
src/ with 10+ source fileslib/ directorypackages/* (monorepo packages)apps/* (monorepo applications)
4. Detect Code Patterns
Analyze source files for conventions:
- Naming: PascalCase, camelCase, snake_case usage
- Imports: ES6 modules, CommonJS, ordering patterns
- Architecture: Feature-based, layered, MVC patterns
- Style: Indentation, quotes, semicolons
5. Fetch Memory Guidelines (Optional)
If network available, fetch from https://code.claude.com/docs/en/memory:
- Use WebFetch tool
- Extract relevant sections for context
- Reference official guidelines above as primary source
6. Present Findings
Use AskUserQuestion to confirm:
- Detected framework and commands
- Suggested subtree locations
- Detected patterns
7. Generate Memory Files
Read .claude/auto-memory/config.json to determine which files to generate based on memoryFiles:
memoryFiles value | Files to generate |
|---|
absent or ["CLAUDE.md"] | CLAUDE.md only (full content) |
["AGENTS.md"] | AGENTS.md only (full content) |
["CLAUDE.md", "AGENTS.md"] | AGENTS.md (full content) + CLAUDE.md (redirect) |
Generate full-content files using the EXACT template structure. Follow these steps precisely:
- Copy template skeleton - Use the appropriate template (CLAUDE or AGENTS) as the base structure
- Use exact marker format - See Marker Syntax section below
- Replace placeholders - Substitute
{{PLACEHOLDER}} with detected content
- Include all required sections - Even if content is minimal, include the section
- Add MANUAL section at the end for user notes
- Size limits: Root 150-200 lines, Subtrees 50-75 lines
When both CLAUDE.md and AGENTS.md are configured, also generate redirect files:
- At the root: write
CLAUDE.md using CLAUDE.redirect.md.template (static pointer, no markers)
- For each subtree that gets an
AGENTS.md: write a matching CLAUDE.md redirect alongside it
Marker Syntax
CRITICAL: Use the EXACT marker format below. Do NOT use variations.
<!-- AUTO-MANAGED: section-name -->
## Section Heading
Content goes here
<!-- END AUTO-MANAGED -->
For user-editable content:
<!-- MANUAL -->
## Custom Notes
Add project-specific notes here. This section is never auto-modified.
<!-- END MANUAL -->
Common mistakes to avoid:
<!-- BEGIN AUTO-MANAGED: name --> - WRONG (no BEGIN prefix)<!-- END AUTO-MANAGED: name --> - WRONG (no name in closing tag)<!-- AUTO-MANAGED section-name --> - WRONG (missing colon)
Section Definitions
Root CLAUDE.md Sections
Generate these sections in order:
| Section Name | Heading | Required | Placeholder | Content |
|---|
project-description | ## Overview | Yes | {{DESCRIPTION}} | Project name, tagline, key features |
build-commands | ## Build & Development Commands | Yes | {{BUILD_COMMANDS}} | Build, test, lint, run commands |
architecture | ## Architecture | Yes | {{ARCHITECTURE}} | Directory tree, key files, data flow |
conventions | ## Code Conventions | Yes | {{CONVENTIONS}} | Naming, imports, formatting rules |
patterns | ## Detected Patterns | Yes | {{PATTERNS}} | AI-detected recurring code patterns |
git-insights | ## Git Insights | No | {{GIT_INSIGHTS}} | Key commits, design decisions |
best-practices | ## Best Practices | No | {{BEST_PRACTICES}} | From official Claude Code docs |
Subtree CLAUDE.md Sections
Generate these sections in order:
| Section Name | Heading | Required | Placeholder | Content |
|---|
module-description | ## Purpose | Yes | {{DESCRIPTION}} | Module purpose and responsibility |
architecture | ## Module Architecture | Yes | {{ARCHITECTURE}} | Module structure, key files |
conventions | ## Module-Specific Conventions | Yes | {{CONVENTIONS}} | Module-specific rules |
dependencies | ## Key Dependencies | Yes | {{DEPENDENCIES}} | Module dependencies |
Templates
Reference the template files for exact structure:
CLAUDE.md Root Template
@templates/CLAUDE.root.md.template
CLAUDE.md Subtree Template
@templates/CLAUDE.subtree.md.template
AGENTS.md Root Template
@templates/AGENTS.root.md.template
AGENTS.md Subtree Template
@templates/AGENTS.subtree.md.template
CLAUDE.md Redirect Template (when both files configured)
@templates/CLAUDE.redirect.md.template
User Interactions
Use AskUserQuestion for:
- Existing CLAUDE.md handling (migrate/backup/merge/cancel)
- Subtree location confirmation
- Final approval before writing files
Output
After generating files, report:
- Files created/modified
- Sections populated
- Any warnings or suggestions
