Generate Comprehensive Style Guide
Perform a deep analysis of this codebase and generate (or regenerate) a STYLE_GUIDE.md file with full evidence citations for every convention.
When to use this vs /setup-ai: /setup-ai generates a quick-pass style guide as part of initial project setup. This skill is for when you need the thorough version — 17 sections, every convention backed by specific file citations, inconsistencies flagged for human decision. Run this after /setup-ai for more depth, or independently when conventions have drifted.
Rules
- ONLY document patterns you actually observe in the code. Never hallucinate or assume conventions.
- When patterns are inconsistent across the codebase, note the inconsistency and ask the user which convention to standardize on.
- Cite specific files as evidence: "Based on
src/services/UserService.ts, src/services/OrderService.ts..."
- If a STYLE_GUIDE.md already exists, read it first and improve/incorporate rather than overwriting.
Analysis Process
Step 1: Detect Tech Stack
Search for dependency and config files:
| File |
Stack |
package.json |
Node.js / JavaScript / TypeScript |
tsconfig.json |
TypeScript specifically |
Gemfile |
Ruby |
requirements.txt, pyproject.toml, Pipfile |
Python |
go.mod |
Go |
Cargo.toml |
Rust |
composer.json |
PHP |
pom.xml, build.gradle |
Java / Kotlin |
*.csproj, *.sln |
C# / .NET |
Read the dependency file to identify: language version, framework and version, key libraries, build tools, testing framework, linter/formatter configuration.
Step 2: Read Existing Configuration
Check for existing style/convention docs that define rules:
.eslintrc, .eslintrc.json, .eslintrc.js
.prettierrc, .prettierrc.json
.rubocop.yml
.editorconfig
biome.json, biome.jsonc
ruff.toml, pyproject.toml (ruff/black sections)
CLAUDE.md, AGENTS.md, .cursorrules
These are authoritative — extract rules from them directly.
Step 3: Sample Code for Patterns
Read 10-15 representative files — sample strategically, don't try to read everything:
- 3-4 "core" files (models, services, controllers, components)
- 2-3 test files
- 1-2 configuration/setup files
- 1-2 utility/helper files
- 1 entry point or router file
For each file, extract patterns for:
- Naming: camelCase, snake_case, PascalCase, kebab-case — for variables, functions, classes, files
- File naming:
*.service.ts, *_controller.rb, *.spec.js, etc.
- Imports: ordering (stdlib → external → internal), style (named vs default), path aliases
- Exports: named exports, default exports, module.exports, barrel files
- Error handling: try/catch, Result types, error middleware, rescue blocks
- Comments: style, density, JSDoc/RDoc/docstrings
- Types: TypeScript strict mode, JSDoc annotations, Python type hints, none
- Functions: arrow vs declaration, parameter patterns, return style, async/await
Step 4: Identify Testing Patterns
From the test files:
- Framework (Jest, Vitest, RSpec, pytest, Go testing, etc.)
- File naming convention (
*_test.rb, *.spec.ts, *.test.js, test_*.py)
- Test structure (describe/it, test(), class-based, table-driven)
- Fixture/factory patterns
- Mocking approach (jest.mock, factory_bot, unittest.mock)
- Assertion style (expect().toBe, assert, should)
- Test file co-location vs separate directory
Step 5: Check Git History (if available)
Run git log --oneline -20 to see:
- Commit message format (conventional commits? Ticket refs? Free-form?)
Run git branch -a | head -20 to see:
- Branch naming convention (feature/, fix/, etc.)
Generate: STYLE_GUIDE.md
Write to the project root. Use this structure:
# Coding Style Guide
> Auto-generated from codebase analysis on [date]. Review and adjust — these patterns were extracted from your existing code. Where patterns were inconsistent, the most common convention was chosen.
## Language & Formatting
[Indentation: tabs or spaces, width. Line length limit. Semicolons. Quote style. Trailing commas.]
**Evidence:** Based on [cite 2-3 representative files]
## Naming Conventions
### Files & Directories
[Pattern with real examples from the codebase]
### Variables & Functions
[camelCase / snake_case / etc. with real examples]
### Classes, Types & Interfaces
[PascalCase / etc. with real examples]
### Constants
[UPPER_SNAKE_CASE / etc.]
### Database
[Column naming (snake_case?), table naming (plural?), migration naming]
## Code Organization
### File Structure
[Standard order within a file: imports → types → constants → main logic → helpers → exports]
**Evidence:** [cite a file that exemplifies this pattern]
### Import Ordering
[Standard order: stdlib/framework → external packages → internal modules → relative imports]
[Are there path aliases? (@/ or ~/)]
## Function Patterns
[Arrow functions vs declarations. When to use each. Parameter destructuring. Return style. Async/await conventions.]
**Evidence:** [cite examples]
## Error Handling
[The standard error handling pattern — with a real code example copied from the codebase]
## Testing Standards
### File Naming
[Pattern: `*.spec.ts`, `*_test.rb`, etc.]
### Test Structure
[describe/it blocks, test() calls, class-based — with skeleton example]
### What to Test
[Unit tests for what, integration tests for what, what coverage is expected]
### Fixtures & Mocking
[How test data is set up. How external dependencies are mocked.]
## API Patterns
[Endpoint naming. Request validation. Response format (envelope? direct?). Error response format. Status code conventions.]
## Database Patterns
[Migration style. Model/schema definitions. Query conventions. Transactions.]
## Component Patterns (if frontend)
[Component file structure. Props patterns. State management. Styling approach.]
## Git Conventions
[Commit message format. Branch naming. PR description expectations.]
## Anti-Patterns — Do NOT Replicate
[Patterns found in the codebase that should NOT be followed in new code. Legacy approaches being phased out. Inconsistencies being resolved.]
After Generation
- Present a summary to the user: what you found, what looks solid, what was ambiguous
- Highlight any inconsistencies that need a human decision
- Tell the user: "Review this file. I extracted these patterns from your code but your team knows the intent. Edit anything that's wrong or aspirational rather than actual."
- If AGENTS.md doesn't exist yet, suggest: "Run
/setup-ai to generate your AGENTS.md and CLAUDE.md, then it will reference STYLE_GUIDE.md automatically."
- Suggest: "Run
/review-style-guide before PRs to automatically check new code against this style guide."
1---2name: generate-comprehensive-style-guide3description: "Deep codebase analysis to generate or regenerate STYLE_GUIDE.md with full evidence citations. Use when /setup-ai's quick pass isn't thorough enough, when conventions have drifted, or after a major refactor. Produces a 17-section style guide citing specific files as evidence."4allowed-tools: Bash, Read, Grep, Glob, Write, LS5metadata:6 source: https://skillmd.com/skills/skinnyandbald/generate-comprehensive-style-guide7---89# Generate Comprehensive Style Guide1011Perform a deep analysis of this codebase and generate (or regenerate) a **STYLE_GUIDE.md** file with full evidence citations for every convention.1213> **When to use this vs `/setup-ai`:** `/setup-ai` generates a quick-pass style guide as part of initial project setup. This skill is for when you need the thorough version — 17 sections, every convention backed by specific file citations, inconsistencies flagged for human decision. Run this after `/setup-ai` for more depth, or independently when conventions have drifted.1415## Rules1617- **ONLY document patterns you actually observe in the code.** Never hallucinate or assume conventions.18- When patterns are inconsistent across the codebase, note the inconsistency and ask the user which convention to standardize on.19- Cite specific files as evidence: "Based on `src/services/UserService.ts`, `src/services/OrderService.ts`..."20- If a STYLE_GUIDE.md already exists, read it first and improve/incorporate rather than overwriting.2122## Analysis Process2324### Step 1: Detect Tech Stack2526Search for dependency and config files:2728| File | Stack |29|------|-------|30| `package.json` | Node.js / JavaScript / TypeScript |31| `tsconfig.json` | TypeScript specifically |32| `Gemfile` | Ruby |33| `requirements.txt`, `pyproject.toml`, `Pipfile` | Python |34| `go.mod` | Go |35| `Cargo.toml` | Rust |36| `composer.json` | PHP |37| `pom.xml`, `build.gradle` | Java / Kotlin |38| `*.csproj`, `*.sln` | C# / .NET |3940Read the dependency file to identify: language version, framework and version, key libraries, build tools, testing framework, linter/formatter configuration.4142### Step 2: Read Existing Configuration4344Check for existing style/convention docs that define rules:45- `.eslintrc`, `.eslintrc.json`, `.eslintrc.js`46- `.prettierrc`, `.prettierrc.json`47- `.rubocop.yml`48- `.editorconfig`49- `biome.json`, `biome.jsonc`50- `ruff.toml`, `pyproject.toml` (ruff/black sections)51- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`5253These are authoritative — extract rules from them directly.5455### Step 3: Sample Code for Patterns5657Read 10-15 representative files — sample strategically, don't try to read everything:58- 3-4 "core" files (models, services, controllers, components)59- 2-3 test files60- 1-2 configuration/setup files61- 1-2 utility/helper files62- 1 entry point or router file6364For each file, extract patterns for:65- **Naming:** camelCase, snake_case, PascalCase, kebab-case — for variables, functions, classes, files66- **File naming:** `*.service.ts`, `*_controller.rb`, `*.spec.js`, etc.67- **Imports:** ordering (stdlib → external → internal), style (named vs default), path aliases68- **Exports:** named exports, default exports, module.exports, barrel files69- **Error handling:** try/catch, Result types, error middleware, rescue blocks70- **Comments:** style, density, JSDoc/RDoc/docstrings71- **Types:** TypeScript strict mode, JSDoc annotations, Python type hints, none72- **Functions:** arrow vs declaration, parameter patterns, return style, async/await7374### Step 4: Identify Testing Patterns7576From the test files:77- Framework (Jest, Vitest, RSpec, pytest, Go testing, etc.)78- File naming convention (`*_test.rb`, `*.spec.ts`, `*.test.js`, `test_*.py`)79- Test structure (describe/it, test(), class-based, table-driven)80- Fixture/factory patterns81- Mocking approach (jest.mock, factory_bot, unittest.mock)82- Assertion style (expect().toBe, assert, should)83- Test file co-location vs separate directory8485### Step 5: Check Git History (if available)8687Run `git log --oneline -20` to see:88- Commit message format (conventional commits? Ticket refs? Free-form?)8990Run `git branch -a | head -20` to see:91- Branch naming convention (feature/, fix/, etc.)9293## Generate: STYLE_GUIDE.md9495Write to the project root. Use this structure:9697```markdown98# Coding Style Guide99100> Auto-generated from codebase analysis on [date]. Review and adjust — these patterns were extracted from your existing code. Where patterns were inconsistent, the most common convention was chosen.101102## Language & Formatting103[Indentation: tabs or spaces, width. Line length limit. Semicolons. Quote style. Trailing commas.]104**Evidence:** Based on [cite 2-3 representative files]105106## Naming Conventions107108### Files & Directories109[Pattern with real examples from the codebase]110111### Variables & Functions112[camelCase / snake_case / etc. with real examples]113114### Classes, Types & Interfaces115[PascalCase / etc. with real examples]116117### Constants118[UPPER_SNAKE_CASE / etc.]119120### Database121[Column naming (snake_case?), table naming (plural?), migration naming]122123## Code Organization124125### File Structure126[Standard order within a file: imports → types → constants → main logic → helpers → exports]127**Evidence:** [cite a file that exemplifies this pattern]128129### Import Ordering130[Standard order: stdlib/framework → external packages → internal modules → relative imports]131[Are there path aliases? (@/ or ~/)]132133## Function Patterns134[Arrow functions vs declarations. When to use each. Parameter destructuring. Return style. Async/await conventions.]135**Evidence:** [cite examples]136137## Error Handling138[The standard error handling pattern — with a real code example copied from the codebase]139140## Testing Standards141142### File Naming143[Pattern: `*.spec.ts`, `*_test.rb`, etc.]144145### Test Structure146[describe/it blocks, test() calls, class-based — with skeleton example]147148### What to Test149[Unit tests for what, integration tests for what, what coverage is expected]150151### Fixtures & Mocking152[How test data is set up. How external dependencies are mocked.]153154## API Patterns155[Endpoint naming. Request validation. Response format (envelope? direct?). Error response format. Status code conventions.]156157## Database Patterns158[Migration style. Model/schema definitions. Query conventions. Transactions.]159160## Component Patterns (if frontend)161[Component file structure. Props patterns. State management. Styling approach.]162163## Git Conventions164[Commit message format. Branch naming. PR description expectations.]165166## Anti-Patterns — Do NOT Replicate167[Patterns found in the codebase that should NOT be followed in new code. Legacy approaches being phased out. Inconsistencies being resolved.]168```169170## After Generation1711721. Present a summary to the user: what you found, what looks solid, what was ambiguous1732. Highlight any inconsistencies that need a human decision1743. Tell the user: "Review this file. I extracted these patterns from your code but your team knows the intent. Edit anything that's wrong or aspirational rather than actual."1754. If AGENTS.md doesn't exist yet, suggest: "Run `/setup-ai` to generate your AGENTS.md and CLAUDE.md, then it will reference STYLE_GUIDE.md automatically."1765. Suggest: "Run `/review-style-guide` before PRs to automatically check new code against this style guide."