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:

bash

# 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

markdown

# 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"

undefined

style-guide

NPX Install

Tags

SKILL.md Content

Style Guide: Multi-Agent Convention Analyzer

Output

CRITICAL: Language-Agnostic Design

Workflow

Step 0: Check for Existing Style Guide

Step 1: Quick Language/Framework Detection

Step 2: Spawn Analyzer Agents IN PARALLEL

Step 3: Track Progress

Step 4: Collect and Synthesize

Step 5: Generate Style Guide

Data Access Pattern

Logging Pattern

Configuration Pattern

Testing Patterns

Test Location

Test Naming

Test Structure

Assertion Style

Frontend Patterns (if applicable)

Component Structure

Styling Approach

State Management

Quick Reference

Examples to Follow

Good Example (matches codebase style)

Anti-pattern (avoid this)