Code Quality Skill

Purpose

Enable coding agents to learn and enforce project-specific code quality patterns via automated scanning, config discovery, conflict resolution, anti-pattern detection, and persisted outputs.

When to use

• User asks for code quality, coding patterns, style guide, conventions, consistency, linting rules, or code standards.
• Before generating code to align with existing patterns.
• After detecting inconsistent patterns or conflicting configs.
• During greenfield setup to seed best-practice configs.
• When reviewing code for potential issues or technical debt.
• To identify anti-patterns, code smells, or complexity hotspots.

Inputs

Outputs

• patterns.md — Detailed pattern report
• .code-quality.json — Machine-readable patterns and rules
• Linter suggestions — ESLint/Prettier config fragments
• Anti-pattern report — Code smells and complexity issues
• Metrics summary — LOC, function lengths, nesting depths
• Conflict MCQs — Interactive resolution for ambiguous patterns

OS detection (run once per session)

• Unix/macOS: uname -s => Linux/Darwin; prefer bash/zsh; use jq for JSON if available.
• Windows: $env:OS => Windows_NT; use PowerShell JSON cmdlets.
• If jq is unavailable on Unix, fall back to Node.js one-liner merges.

Workflow

Phase 1: Configuration Discovery (config-reader agent)

• Scan for ESLint, Prettier, EditorConfig, TSConfig, pyproject, etc.
• Normalize rules; detect conflicts (indent, semi, quotes, line endings, strictness).
• Build priority-ordered rule set.

Phase 2: Distributed Pattern Scanning (pattern-scanner agents)

• For each major directory (src, lib, apps, packages, tests): spawn haiku agent.
• Structure analysis: File organization, module boundaries, dependency flow.
• Pattern detection: Naming, imports, API calls, state management, components, errors, tests, docs.
• Anti-pattern detection: Code smells, complexity, coupling, duplication, security issues.
• Metrics collection: LOC, function length, nesting depth, import counts.

Phase 3: Consolidation & Scoring

• Merge pattern data from all agents.
• Compute confidence scores using multi-factor algorithm:
  • Occurrence frequency (25%)
  • Consistency ratio (25%)
  • File coverage (20%)
  • Recency weight (10%)
  • Author distribution (8%)
  • Context consistency (7%)
  • Config alignment (5%)
• Tag confidence tiers: High (85-100), Medium-High (70-84), Medium (50-69), Low (25-49), Very Low (0-24).

Phase 4: Conflict & Ambiguity Resolution (conflict-resolver agent)

• If conflicts or medium confidence: invoke sonnet agent to craft MCQs.
• Provide pros/cons and recommended option.
• Offer “Dig Deeper” when 5+ variations exist.
• Allow custom responses.

Phase 5: Output Generation

• Write patterns.md using template.
• Write or merge .code-quality.json with:
  • Confirmed/detected/custom patterns
  • Custom rules
  • Excluded paths
  • Integration settings
  • Anti-pattern baseline
• Generate recommended linter/formatter rule changes.
• Create anti-pattern report with severity levels and fix suggestions.

Thoroughness Levels

Resumable sessions

• Each pattern-scanner returns agent_id and optional checkpoint.
• Resume interrupted scans with resume_from parameter.
• Checkpoints: phase_1_complete, phase_2_partial, phase_3_complete, etc.

Best-practice source priority

1. User-defined (.code-quality.json custom_rules)
2. Project configs (EditorConfig > ESLint > Prettier > TSConfig > language-specific)
3. Detected patterns (high confidence)
4. Model inference for stack version
5. Industry standards for detected framework/library

Interaction rules

• Read-only on source files; only write output files.
• MCQ confirmation for medium confidence or conflicts.
• Auto-apply only for high confidence patterns.
• Context-aware: respect boundaries (auth vs public, tests vs prod, components vs utils).
• Persist decisions to .code-quality.json for future runs.

File conventions

• Outputs live at repo root unless user specifies otherwise.
• Default exclusions: node_modules, dist, build, coverage, .git, vendor, pycache, tmp.

Error handling

• If config parse fails: report file and error; continue scanning others.
• If no patterns detected (<100 LOC): switch to greenfield flow with best-practice bundle.
• If agent fails: log checkpoint; allow resume from last known state.
• Surface all errors in final report with suggested remediation.

Anti-Pattern Severity Levels