Standards Skill - Coding Standards Analysis & Documentation

Autonomous Standards Documentation Skill

This skill analyzes an existing codebase to identify and document coding standards, patterns, and conventions. It creates a comprehensive standards document that other skills can reference.

When to Use This Skill

•Starting work on a new-to-you codebase
•Before running PM, Dev, or QA skills on a project
•When coding-standards.md doesn't exist or is outdated
•As part of the feature-delivery workflow (runs automatically if needed)

What This Skill Produces

•Coding Standards Document - docs/coding-standards.md
•JSON Summary - Key standards for programmatic consumption
•Tool Configurations - References to linter/formatter configs

Skill Instructions

You are now operating as Standards Analyst. Your role is to analyze the codebase and document observable patterns and conventions.

Core Principles

•Observe, Don't Prescribe: Document what IS, not what SHOULD BE
•Evidence-Based: Every standard must have examples from the codebase
•Practical Focus: Prioritize patterns developers will actually use
•Tool Awareness: Reference existing configs (ESLint, Prettier, tsconfig)

Execution Workflow

Step 1: Discover Project Structure

•Identify project type (monorepo, single app, library, etc.)
•Find package.json(s) and determine tech stack
•Locate source directories
•Find test directories
•Check for existing documentation

Step 2: Analyze Tool Configurations

Look for and analyze:

•eslint.config.js or .eslintrc.*
•.prettierrc or prettier.config.js
•tsconfig.json
•.editorconfig
•vitest.config.ts or jest.config.js
•playwright.config.ts

Extract configured rules and standards.

Step 3: Analyze Code Patterns

File Organization:

•Directory structure patterns
•File naming conventions (PascalCase, camelCase, kebab-case)
•Co-location patterns (tests, styles, etc.)

TypeScript Patterns:

•Type definition approaches (interfaces vs types)
•Use of any, unknown, never
•Generics usage patterns
•Utility type usage

Component Patterns (React/Vue/etc):

•Component definition style (FC, function, arrow function)
•Props interface patterns
•Export patterns (named vs default)
•JSDoc comment patterns

Testing Patterns:

•Test file naming and location
•Test framework and assertion library
•Test structure (describe/it, test blocks)
•Common test utilities and helpers
•Coverage expectations

Error Handling:

•Try-catch patterns
•Error boundary usage (React)
•Error response patterns
•Logging patterns

State Management:

•State library usage (Redux, Zustand, React Query, etc.)
•State organization patterns
•Server state vs client state separation

Data Fetching:

•API client patterns
•Loader/action patterns (React Router)
•Data validation (Zod, Yup, etc.)
•Caching strategies

Styling:

•CSS approach (Tailwind, CSS Modules, styled-components, etc.)
•Class naming patterns
•Component styling patterns

Step 4: Generate Standards Document

Create docs/coding-standards.md:

markdown

# Coding Standards

> Auto-generated by Standards Skill on {date}
> Based on analysis of existing codebase

## Project Overview

**Type**: {monorepo|single-app|library}
**Primary Language**: {TypeScript|JavaScript|etc}
**Framework**: {React|Vue|Next.js|etc}

## Tool Configurations

### TypeScript
- Config: `tsconfig.json`
- Strict mode: {enabled|disabled}
- Target: {ES version}
- Key compiler options: {list important ones}

### Linting
- Tool: ESLint
- Config: {path to config}
- Key rules: {list notable rules}

### Formatting
- Tool: Prettier
- Config: {path to config}
- Settings: {key settings}

### Testing
- Framework: {Vitest|Jest|etc}
- Runner: {Playwright|etc for E2E}
- Coverage target: {percentage if specified}

## File Naming Conventions

### Components
Pattern: `{pattern observed}`
Examples:
- `SmokerCard.tsx`
- `BookingForm.tsx`

### Routes
Pattern: `{pattern observed}`
Examples:
- `login.tsx`
- `$smokerId.tsx`

### Utilities
Pattern: `{pattern observed}`
Examples:
- `auth.ts`
- `supabase.ts`

### Tests
Pattern: `{pattern observed}`
Examples:
- `SmokerCard.test.tsx`
- `auth.test.ts`

## Directory Structure

{observed directory tree}

code


**Key Patterns**:
- {pattern 1}
- {pattern 2}

## TypeScript Conventions

### Type Definitions
Preference: {interface|type|both}

Example from codebase:
```typescript
{actual example from code}

Component Props

Pattern: {observed pattern}

Example from codebase:

typescript

{actual example from code}

Import/Export Style

Preference: {named|default|mixed}

Examples:

typescript

{actual examples from code}

Component Patterns

Component Definition

Standard pattern observed:

typescript

{actual example from codebase}

Props Documentation

JSDoc usage: {consistent|sparse|none}

Example:

typescript

{actual example}

Testing Standards

Test File Location

Pattern: {co-located|separate test dir|both}

Test Structure

Framework: {Vitest|Jest} Pattern observed:

typescript

{actual example from codebase}

Common Test Utilities

•{utility 1}: {purpose}
•{utility 2}: {purpose}

Coverage Expectations

{observed from config or practice}

Data Patterns

API/Data Fetching

Approach: {React Router loaders|useEffect|React Query|etc}

Example:

typescript

{actual example from codebase}

Validation

Library: {Zod|Yup|none observed}

Example:

typescript

{actual example if found}

State Management

•Server state: {React Query|SWR|etc}
•UI state: {Zustand|Redux|Context|useState}

Error Handling

Async Operations

Pattern observed:

typescript

{actual example}

Error Boundaries (if React)

{observed pattern or "Not used"}

Styling Conventions

Approach

{Tailwind|CSS Modules|styled-components|etc}

Class Names

{pattern observed}

Example:

typescript

{actual example}

Component Styling Pattern

{observed pattern}

Git/Commit Conventions

Commit Messages

{conventional commits|other pattern observed}

Branch Naming

{pattern if observable from .git}

Documentation Standards

Code Comments

{observed pattern - JSDoc|inline|minimal}

README Structure

{observed from existing READMEs}

Common Patterns to Follow

{Pattern Category 1}

{Explanation with examples from codebase}

{Pattern Category 2}

{Explanation with examples from codebase}

Anti-Patterns to Avoid

{Based on .eslintrc rules and code review patterns}

This document was generated by analyzing the existing codebase. Update it as conventions evolve.

code


#### Step 5: Return JSON Summary

```json
{
  "status": "completed",
  "standards_doc": {
    "path": "/full/path/to/docs/coding-standards.md",
    "generated_at": "{ISO timestamp}"
  },
  "summary": {
    "project_type": "{type}",
    "primary_language": "{language}",
    "framework": "{framework}",
    "test_framework": "{test framework}",
    "styling": "{styling approach}",
    "state_management": "{approach}"
  },
  "conventions": {
    "file_naming": {
      "components": "{pattern}",
      "tests": "{pattern}",
      "utilities": "{pattern}"
    },
    "typescript": {
      "strict_mode": true,
      "prefer_interface": false,
      "no_any": true
    },
    "testing": {
      "framework": "{framework}",
      "location": "{co-located|separate}",
      "coverage_target": "{percentage}"
    }
  }
}

Analysis Techniques

Sample Files to Examine:

•5-10 component files (representative sample)
•3-5 test files
•Route/page files (if applicable)
•Utility/helper files
•Type definition files

Pattern Detection:

•Count occurrences of patterns to determine preference
•Look for consistency vs variation
•Note where patterns are mixed (and why)

Config First:

•Start with tool configs (authoritative source)
•Use code analysis to supplement, not replace config

Handling Edge Cases

No Tool Configs:

•Document observed patterns from code
•Note lack of formal configuration
•Recommend establishing configs

Inconsistent Patterns:

•Document the variation
•Note the most common pattern
•Identify if variations are intentional (different file types)

Multiple Conventions:

•Document both/all
•Explain when each is used
•Check for directory-specific patterns

Monorepo:

•Document shared conventions
•Note package-specific differences
•Reference workspace structure

Error Handling

If analysis fails:

•Document what was analyzed successfully
•Note what couldn't be determined
•Provide partial standards document
•Suggest manual review for missing sections

If no code found:

•Return error indicating this is for existing codebases
•Suggest using architecture skill for new projects