Style Guide: Multi-Agent Convention Analyzer
Spawns specialized analyzer agents to discover and document a codebase's conventions, patterns, and style. Each agent focuses on one aspect and explores independently.
Use this when:
- Starting work on an unfamiliar codebase
- You want AI to match existing patterns exactly
- Making implicit conventions explicit
- Before running feature-council on a new project
Output
Generates .claude/codebase-style.md - a comprehensive style guide that can be referenced by other skills and agents.
CRITICAL: Language-Agnostic Design
Each analyzer:
- Discovers the language/framework first - Don't assume anything
- Finds relevant files itself - Uses Glob, Grep, LS to explore
- Extracts patterns from what exists - Not what "should" exist
- Reports findings in structured format - For synthesis
This works for: Python, JavaScript, TypeScript, Go, Rust, Java, C#, Ruby, PHP, Swift, Kotlin, or any other language.
Workflow
Step 0: Check for Existing Style Guide
Before starting, check if .claude/codebase-style.md already exists.
If it exists, ask the user:
A style guide already exists for this codebase (.claude/codebase-style.md).
Options:
1. View the existing style guide
2. Regenerate it (will overwrite)
3. Cancel
What would you like to do?Only proceed with analysis if the user chooses to regenerate.
Step 1: Quick Language/Framework Detection
Before spawning analyzers, do a quick check:
# Check for common indicators
ls -la # Look for package.json, requirements.txt, go.mod, Cargo.toml, etc.Note the primary language(s) and framework(s) detected. Pass this context to analyzers.
Step 2: Spawn Analyzer Agents IN PARALLEL
Spawn ALL analyzers simultaneously with the same context:
CONTEXT: [Primary language/framework detected in Step 1]
TASK: Analyze the codebase for [YOUR SPECIALTY] conventions and patterns.
Return a structured report of what you find.Task(agent: "style-structure", prompt: "CONTEXT: [lang/framework]. Analyze folder structure, file organization, and module patterns.")
Task(agent: "style-naming", prompt: "CONTEXT: [lang/framework]. Analyze naming conventions for files, variables, functions, classes, constants.")
Task(agent: "style-patterns", prompt: "CONTEXT: [lang/framework]. Analyze code patterns: error handling, data access, configuration, logging.")
Task(agent: "style-testing", prompt: "CONTEXT: [lang/framework]. Analyze testing patterns: file locations, naming, structure, assertions.")
Task(agent: "style-frontend", prompt: "CONTEXT: [lang/framework]. Analyze frontend/UI patterns if applicable: components, styling, state. If not a frontend project, report 'N/A'.")ALL agents spawn in the SAME batch - parallel execution.
Step 3: Track Progress
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ANALYZER PROGRESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
☐ Structure Analyzer - Working...
☐ Naming Analyzer - Working...
☐ Patterns Analyzer - Working...
☐ Testing Analyzer - Working...
☐ Frontend Analyzer - Working...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━Update as each completes.
Step 4: Collect and Synthesize
Each analyzer returns structured findings. Merge into a unified style guide.
Handle conflicts: If analyzers disagree (rare), note both patterns.
Step 5: Generate Style Guide
Create .claude/codebase-style.md:
# Codebase Style Guide
> Auto-generated by codebase-style skill on [DATE]
> Primary: [Language] | Framework: [Framework] | [X] files analyzed
---
## Project Structure
[From style-structure analyzer]
### Directory Layout
- `src/` - Source code
- `tests/` - Test files
- ...
### File Organization Pattern
[Description with examples]
---
## Naming Conventions
[From style-naming analyzer]
| Element | Convention | Example |
|---------|------------|---------|
| Files | [pattern] | `user_service.py` |
| Classes | [pattern] | `UserService` |
| Functions | [pattern] | `get_user_by_id` |
| Variables | [pattern] | `user_count` |
| Constants | [pattern] | `MAX_RETRIES` |
---
## Code Patterns
[From style-patterns analyzer]
### Error Handling[Actual example from codebase]
### Data Access Pattern
[Actual example from codebase]
### Logging Pattern
[Actual example from codebase]
### Configuration Pattern
[Description]
---
## Testing Patterns
[From style-testing analyzer]
### Test Location
[Where tests live relative to source]
### Test Naming
[Convention for test files and functions]
### Test Structure
[Actual example from codebase]
### Assertion Style
[What assertion library/style is used]
---
## Frontend Patterns (if applicable)
[From style-frontend analyzer, or "N/A - Not a frontend project"]
### Component Structure
[Pattern]
### Styling Approach
[CSS-in-JS, Tailwind, CSS Modules, etc.]
### State Management
[Pattern]
---
## Quick Reference
| Category | Convention |
| --- | --- |
| File naming | [pattern] |
| Function naming | [pattern] |
| Error handling | [pattern name] |
| Test files | [location pattern] |
| Imports | [order/style] |
---
## Examples to Follow
### Good Example (matches codebase style)
[Real example from codebase that exemplifies the patterns]
### Anti-pattern (avoid this)
[What NOT to do based on codebase conventions]
Step 6: Save and Report
- Create
.claude/directory if needed - Write
.claude/codebase-style.md - Report summary to user
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ CODEBASE STYLE ANALYSIS COMPLETE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Analysis Summary
| Analyzer | Files Checked | Patterns Found |
| --- | --- | --- |
| Structure | [N] | [N] |
| Naming | [N] | [N] |
| Patterns | [N] | [N] |
| Testing | [N] | [N] |
| Frontend | [N or N/A] | [N or N/A] |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 Generated:.claude/codebase-style.md
Key Findings:
- Language: [Primary language]
- Framework: [If detected]
- Naming: [Quick summary, e.g., "snake_case for files, PascalCase for classes"]
- Structure: [Quick summary, e.g., "Feature-based organization"]
- Testing: [Quick summary, e.g., "pytest, tests/ directory"]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 This style guide will be referenced by other skills to ensure consistent code that matches your codebase conventions.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Agents
5 specialized analyzer agents in agents/ directory:
| Agent | Focus | What It Looks For |
|---|---|---|
style-structure | Organization | Folders, modules, file grouping, imports |
style-naming | Naming | Files, variables, functions, classes, constants |
style-patterns | Code patterns | Error handling, data access, logging, config |
style-testing | Testing | Location, naming, structure, assertions |
style-frontend | Frontend/UI | Components, styling, state (if applicable) |
All analyzers:
- Explore the codebase independently
- Language-agnostic (detect, don't assume)
- Return structured findings
- Use Read, Grep, Glob, LS tools
Integration with Other Skills
The generated .claude/codebase-style.md can be referenced by:
- feature-council - Agents can check style guide before implementing
- debug-council - Ensure fixes match codebase patterns
- parallel-builder - Each builder follows the style guide
To explicitly include:
Before implementing, read.claude/codebase-style.md to understand codebase conventions.
When to Re-run
Run codebase-style again when:
- Major refactoring has occurred
- New patterns have been introduced
- Moving to a new framework/library
- Style guide feels outdated
Triggers
"style guide" "generate style guide" "analyze codebase style" "what are the conventions in this codebase" "codebase conventions" "analyze this codebase" "extract code style" "document coding patterns"