Code Quality Evaluator

Cross-platform code quality evaluation tool. Generates comprehensive scoring reports based on classic software engineering book rules, designed for AI coding tools and human developers.

Compatibility

This Skill has been verified on the following platforms:

• WorkBuddy — uses showwidget (chart) + readme module for radar chart visualization
• Claude Code — uses show_json / inline markdown tables as visualization fallback
• Codex / OpenClaw — uses markdown output + ASCII/text tables
• Generic — any environment that supports markdown

Cross-platform note: Visualization features degrade gracefully based on host tool capabilities. Core evaluation logic and report structure remain consistent across all platforms.

Use Cases

• Code review and quality assessment
• Quality baseline measurement before project handoff
• Tech debt inventory
• Portfolio preparation for interviews
• Team coding standard alignment
• Pre-refactoring status assessment

Trigger Intents

Triggers when the user expresses similar intents:

• "evaluate code quality"
• "score this project"
• "code review"
• "analyze project quality"
• "check code health"
• "evaluate this repo"

Execution Flow

Phase 1: Project Exploration

1. Determine Project Path

# General: list current directory
ls -la

# WorkBuddy
ls -la /path/to/project

# Claude Code / Codex
ls -la .

# Find project root (search upward for package.json, Cargo.toml, go.mod, etc.)

2. Identify Project Characteristics

Explore project structure to identify:

• Project type: Frontend / Backend / Full-stack / Library / CLI tool / Monorepo
• Tech stack: Languages, frameworks, build tools, package managers
• Project scale: File count, lines of code, directory depth
• Quality infrastructure: Test frameworks, linters, formatters, CI/CD configuration

3. Choose Sampling Strategy

4. Read Key Files

• Entry files (main.ts/index.js/main.go, etc.)
• Core business modules
• Config files (package.json/tsconfig.json/Cargo.toml, etc.)
• Test files (sampled)
• Documentation (README.md/CONTRIBUTING.md)

Phase 2: Five-Dimension Evaluation

Each dimension scored 0-100.

Dimension 1: Readability & Code Style — Weight 25%

Rule source: Clean Code (Robert C. Martin)

Checkpoints:

Scoring reference:

Dimension 2: Architecture Design — Weight 25%

Rule source: Clean Architecture (Robert C. Martin)

Checkpoints:

Scoring reference:

Dimension 3: Refactoring Health — Weight 20%

Rule source: Refactoring (Martin Fowler) & Refactoring.Guru

Checkpoints:

Scoring reference:

Dimension 4: Engineering Practices — Weight 15%

Rule source: The Pragmatic Programmer (Hunt & Thomas)

Checkpoints:

Scoring reference:

Dimension 5: Code Smell Detection — Weight 15%

Rule source: Refactoring.Guru

Six major categories of code smells:

Bloaters
├── Long Method
├── Large Class
├── Long Parameter List
├── Primitive Obsession
└── Data Clumps

Object-Orientation Abusers
├── Switch Statements
├── Temporary Field
└── Refused Bequest

Change Preventers
├── Divergent Change
├── Shotgun Surgery
└── Parallel Inheritance

Dispensables
├── Duplicated Code
├── Dead Code
├── Speculative Generality
└── Comments

Couplers
├── Inappropriate Intimacy
├── Message Chains
├── Middle Man
└── Incomplete Library Class

Scoring method:

Phase 3: Generate Scoring Report

Calculate Weighted Total

Total = Readability x 0.25 + Architecture x 0.25 + Refactoring x 0.20 + Engineering x 0.15 + Smells x 0.15

Grading Scale

Report Format (Cross-Platform Adaptation)

Universal Markdown format (all platforms):

# [Project Name] Code Quality Evaluation Report

**Date**: YYYY-MM-DD
**Project Path**: /path/to/project
**Scale**: X files, ~Y lines of code

---

## Composite Score

| Dimension              | Weight | Score | Grade |
|------------------------|--------|-------|-------|
| Readability & Style    | 25%    | 75    | B     |
| Architecture Design    | 25%    | 68    | C     |
| Refactoring Health     | 20%    | 70    | B     |
| Engineering Practices  | 15%    | 72    | B     |
| Code Smell Detection   | 15%    | 65    | C     |
| **Weighted Total**     | 100%   | **70.7** | **B** |

---

## Dimension Details

### Dimension 1: Readability & Code Style — 75 (B)

**Strengths**:
- Clear function naming (e.g., `fetchData`, `buildSchema`)
- Most functions are short (10-30 lines)

**Deductions**:
- Line 23: long function (58 lines)
- Line 45: unnamed magic number

---

## Top 5 Improvements

1. **[High] Extract shared module**
   - Issue: `app.ts` and `composer.ts` have duplicated logic
   - Fix: Create `services/schema.service.ts`
   - Files: `src/app/composer.ts`, `src/app/app.ts`

---

## Highlights

1. **Modern tech stack** — latest framework versions
2. **TypeScript type safety** — good type definitions

Visualization enhancement (WorkBuddy / platforms with HTML support):

<!-- Use show_widget with chart module to generate radar chart -->
<!-- First call read_me(modules: ["chart"]) -->
<!-- Then call show_widget to render the radar chart -->

Text table enhancement (Claude Code / Codex):

  Readability  ████████████████████░░░░ 75
  Architecture ███████████████░░░░░░░░ 68
  Refactoring  ████████████████░░░░░░░ 70
  Engineering  ████████████████░░░░░░░ 72
  Smells       █████████████░░░░░░░░░ 65

Important Rules

Scoring Principles

1. Evidence-driven — every deduction must cite specific file paths and line numbers; never guess
2. Positive reinforcement — always find highlights (at least 2), even in low-quality projects
3. Actionable — improvement suggestions must be specific, with file locations and modification direction
4. Context-aware — small scripts should not be graded by enterprise architecture standards
5. Language-adaptive — reports use the user's language; code terminology kept in English

Scoring Adjustments

Adjust expectations based on project type:

Rule Sources

Evaluation rules are distilled from these classic software engineering books:

Version History