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:

1. Discovers the language/framework first - Don't assume anything
2. Finds relevant files itself - Uses Glob, Grep, LS to explore
3. Extracts patterns from what exists - Not what "should" exist
4. 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

```[language] [Actual example from codebase]

### Logging Pattern
```[language]
[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

```[language] [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)
```[language]
[Real example from codebase that exemplifies the patterns]

Anti-pattern (avoid this)

```[language] [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"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: michaelboeding
• Source: michaelboeding/skills
• License: MIT

Install and usage instructions live in the source repository linked above.