style-guide
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
```[language]
[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
1. Create `.claude/` directory if needed
2. Write `.claude/codebase-style.md`
3. 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"