The Problem

AI-generated code accumulates deeply nested conditionals: if/else chains, nested loops, and compound boolean expressions that work but are hard for humans to follow and modify. Cyclomatic complexity is the standard metric for this, but measuring it and deciding where to refactor is manual work most teams skip.

What This Does

This is not a code library. It's a Claude skill — a Markdown instruction file (skills/cyclomatic-complexity/SKILL.md) that tells Claude how to measure complexity, find hotspots, and refactor them. The README.md documents install and usage; .claude-plugin/marketplace.json makes it installable as a plugin.

The skill measures per-function complexity using radon, eslint, gocyclo, lizard, or manual count, and respects the project's own linter thresholds when configured. It refactors worst hotspots first via guard clauses, extract function, lookup tables, and named predicates. It explicitly refuses to game the metric — complexity moves into well-named functions, not clever one-liners. Every refactor ends with a before/after complexity table.

How It Is Wired

There is no runtime code, so no conventional call graph exists. The wiring is: .claude-plugin/marketplace.json declares the plugin to Claude Code; skills/cyclomatic-complexity/SKILL.md is the behavior definition Claude loads and follows. That file is the single entry point — Claude reads it, applies its instructions, and executes refactoring through its own tool use. The only external touches are the complexity tools (radon, eslint, gocyclo, lizard) and the project's existing test suite, which the skill verifies against after each refactor.

The blast radius lives entirely in SKILL.md; anyone changing it changes how Claude refactors code. README.md documents behavior but does not drive it. The module graph for this repo has not been mapped beyond these files — there are only five, and no deeper dependency structure exists to analyze.

How To Use It

Setup, per the README:

/plugin marketplace add saurabhkumar8112/cyclomatic-complexity-skill
/plugin install cyclomatic-complexity@cyclomatic-complexity-skill

Claude.ai: download the .skill file from Releases or zip skills/cyclomatic-complexity and upload under Settings → Capabilities → Skills. Claude API: upload via the Skills API.

No configuration files, environment variables, or build steps exist — this is a skill definition, not an application. Invoke it directly: "Use the cyclomatic complexity skill to refactor parser.py". It also triggers automatically on refactoring, cleanup, and code review requests.

Real-World Use

A team with a legacy Python module where parseOrder has complexity 14. The developer asks Claude to refactor it. The skill measures, identifies the worst function, extracts validateHeader and resolveDiscount, and reports:

| Function | Before | After |
|----------|--------|-------|
| parseOrder | 14 | 4 |

The skill runs the existing test suite and confirms it passes before finishing.

Code Health & Issues

Static analysis flags two SDLC gaps:

  • Med - No test files detected — the skill has no automated validation that its instructions produce correct refactors. Repository-wide.
  • Med - No CI/CD pipeline — no build or test gate; changes to SKILL.md ship unverified. No .github/ or CI config present.

Deep analysis has not run beyond structural inspection. The repo is five files: a skill definition, a marketplace manifest, a README, an Apache 2.0 license, and a .gitignore.

The Bottom Line

A focused, well-scoped skill that does one thing: makes Claude measure and reduce cyclomatic complexity without gaming the metric. The upstream (100 stars) suggests the approach is proven. The lack of tests and CI is acceptable for a prompt-based skill but means behavior changes are validated only by manual use. Teams generating code with Claude and wanting complexity discipline should use it; teams needing a programmatic analysis tool should look elsewhere.