Skip to content
Skills Library
Programming · Review & audit

code-quality-audit

/code-quality-audit

Audit code for smells, error-handling gaps, and maintainability issues with actionable fixes. Use for a general code-quality pass not tied to project rules. To audit against the project's golden-principles.yaml use /quality-audit instead.

Licence
MIT
Last repository change
21.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Audit code for smells, error-handling gaps, and maintainability issues with actionable fixes. Use for a general code-quality pass not tied to project rules. To audit against the project's golden-principles.yaml use /quality-audit instead.

Original author description

Audit code for smells, error-handling gaps, and maintainability issues with actionable fixes. Use for a general code-quality pass not tied to project rules. To audit against the project's golden-principles.yaml use /quality-audit instead.

How it works

  1. Core Rule
  2. Kit Context
  3. When to Use
  4. Default Behavior
  5. Scope Rules
  6. Context Gathering
  7. Process
  8. Output Format
  9. Report Guidelines
  10. Notes
Original SKILL.md headings · 155 lines, 882 words
SKILL.md preview
---
name: code-quality-audit
description: Audit code for smells, error-handling gaps, and maintainability issues with actionable fixes. Use for a general code-quality pass not tied to project rules. To audit against the project's golden-principles.yaml use /quality-audit instead.
user-invocable: true
---

# Code Quality Audit

## Core Rule

Surface issues that affect maintainability and correctness, not stylistic preferences. Recommend fixes only with concrete reproduction steps; never apply edits in a report-only request.

## Kit Context

Before starting this skill, ensure you have completed session boot:
1. Read `CODEBASE_MAP.md` for project understanding
2. Read `CLAUDE.project.md` if it exists for project-specific rules
3. Read `tasks/lessons/_index.md` for accumulated corrections (Top Rules + index)

If any of these haven't been read in this session, read them now before proceeding.

## When to Use

Invoke with `/code-quality-audit` when:

- Reviewing a codebase for code smells before a refactoring sprint
- Onboarding to a new project and assessing code health
- Preparing for a code review or due diligence assessment
- After rapid development to identify accumulated technical debt

## Default Behavior

When the user asks to audit, scan, review, or "give me a report" for code quality, produce the full code-quality-audit report automatically using the Process and Output Format sections below. Do not require the user to specify fields.

Only modify files when the user explicitly requests implement / fix / apply / refactor. By default, this skill is **report-only**.

## Scope Rules

- Analyze ONLY the files and directories relevant to this skill's purpose
- Do not refactor, fix, or modify code — this is a read-only analysis unless explicitly stated otherwise
- Log unrelated issues found during analysis under `tasks/todo.md > ## Not Now`
- State every assumption explicitly before acting on it
- If the user specified a scope (files, directories, modules), respect it strictly

## Context Gathering

Before analysis, map the project:
1. Read project config (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.)
2. Identify the tech stack, frameworks, and key dependencies
3. Map source directories — skip `node_modules`, `vendor`, `build`, `.next`, `dist`, `__pycache__`
4. Check for existing configurations relevant to this analysis (linters, formatters, CI configs)
5. If the user specified a scope, narrow to those files/directories only

## Process

### Phase 1: Inventory (first-pass leads)

This pass produces **candidates**, not findings. Treat counts as leads for deeper inspection in later phases. Do not report Phase 1 raw output as the final result.

Determine audit scope:

1. If the user specifies files/directories, audit those
2. Otherwise, identify key source directories by reading project structure
3. Skip generated code, vendor directories, lock files, and build output

### Phase 2: Code Smells Analysis

Scan for these categories of code smells:

**Complexity Smells**
- Functions/methods exceeding 50 lines
- Deeply nested conditionals (3+ levels)
- Cyclomatic complexity > 10 per function
- God classes/modules with too many responsibilities
- Long parameter lists (5+ parameters)

**Duplication Smells**
- Repeated code blocks (3+ occurrences of similar logic)
- Copy-paste patterns with minor variations
- Parallel inheritance hierarchies
- Identical conditional structures across files

**Coupling Smells**
- Feature envy (method uses another class's data more than its own)
- Inappropriate intimacy (classes accessing each other's internals)
- Message chains (a.b.c.d.method())
- Circular dependencies between modules

**Naming Smells**
- Inconsistent naming conventions within the same codebase
- Overly abbreviated or cryptic names
- Boolean parameters without named arguments
- Generic names (data, info, manager, handler) without context

### Phase 3: Error Handling Analysis

Check for error handling issues:

- **Swallowed errors**: empty catch blocks, catch-and-log-only without re-throw
- **Over-catching**: catching base Exception/Error when specific types are appropriate
- **Missing error handling**: async operations without try/catch, unchecked return values
- **Inconsistent patterns**: mix of exceptions, error codes, Result types without clear convention
- **Error information loss**: re-throwing without preserving original stack trace
- **Missing cleanup**: no finally/defer/cleanup for resources in error paths
- **User-facing errors**: raw stack traces or internal errors exposed to users

### Phase 4: Maintainability Assessment

Evaluate:

- **Readability**: Can a new developer understand the code without external context?
- **Testability**: Can units be tested in isolation? Are dependencies injectable?
- **Changeability**: How many files need to change for a typical feature addition?
- **Consistency**: Are patterns applied uniformly across the codebase?

## Output Format

```markdown
# Code Quality Audit Report

## Executive Summary
[1-2 paragraphs: overall quality assessment, critical findings count]

## Critical Issues (Must Fix)
| # | Category | Location | Issue | Suggested Fix |
|---|----------|----------|-------|---------------|
| 1 | smell    | file:line | ...   | ...           |

## Major Issues (Should Fix)
| # | Category | Location | Issue | Suggested Fix |
|---|----------|----------|-------|---------------|

## Minor Issues (Consider)
| # | Category | Location | Issue | Suggested Fix |
|---|----------|----------|-------|---------------|

## Metrics
- Files analyzed: N
- Code smells found: N (critical/major/minor)
- Error handling gaps: N
- Estimated tech debt: low/medium/high

## Positive Patterns
[List well-implemented patterns worth preserving]
```

## Report Guidelines

- Use tables for structured findings — they're scannable and diffable
- Include file paths with line numbers (`file.ts:42`) for every finding
- Separate findings by severity: Critical > Major > Minor
- End with actionable recommendations, not just observations
- If no issues found in a category, state it explicitly — don't omit the section

## Notes

- This audit focuses on code-level quality, not architecture (see `/architecture-review`)
- Security issues should be flagged but detailed security review is separate (use security-reviewer agent)
- Adapt smell thresholds to the project's language conventions (e.g., functional languages may have longer functions)

Versions

RepositoryScoreLicence
This page · tansuasici/claude-code-kit100MIT
mhylle/claude-skills-collection100MIT

Database snapshot: 13.11.2026 · package version 2be05a73310e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100quality-audit
    Audit the codebase against the project's golden-principles.yaml — runs deterministic detection rules and updates docs/QUALITY_SCORE.md. Use to enforce project-specific principles. For a generic smell pass with no rules file use /code-quality-audit.
  • 100code-quality
    Code review to find quality issues, style violations, and code smells. Triggers on: review, code review, quality, lint, code smell, analyze code.
  • 100code-review
    Review code for quality, bugs, security issues, and suggest improvements. Use when asked to review, audit, or improve code.
  • 90code-audit
    Review code for correctness bugs, concurrency and lifecycle errors, type-safety holes, error handling gaps, API-contract breaks, and maintainability problems, with every finding gated on a concrete failure scenario. Use when asked to review code, check a diff or branch for bugs,…
  • 100code-review
    Reviews code for quality, best practices, and potential issues. Use when asked to review, audit, or check code for problems.
  • 100refactoring-advisor
    Analyze code for structural issues and code smells, then recommend prioritized refactoring patterns with before/after examples. Use when the user asks to refactor, clean up, or improve code structure, when a module has grown hard to change or test, or when a review surfaces maintainability problems.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.