cyclomatic-complexity-skill: a Claude skill that refactors code by the numbers
Claude skill: refactor code to reduce cyclomatic complexity
At a glance
- What is it?
- The skill measures per-function complexity with radon, eslint, gocyclo or lizard, then refactors the worst functions first and prints a before/after table. It is aimed at AI-generated codebases that work but branch heavily.
- Who is it for?
- Adopt it if a Claude-driven codebase has grown branch-heavy and you already have a test suite to catch regressions, because the skill's own example output claims behavior is verified by running the existing tests. Skip it if you want an automated gate in CI: this is a skill invoked inside Claude, not a linter, and the README documents no threshold enforcement or rollback.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 20 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: AI-generated code that branches like a jungle
The README states the motivation plainly: the skill is "Built for AI-generated code: it works, but branches like a jungle." That is a narrower audience than the general refactoring crowd. Code produced by a model often passes its tests while stacking conditionals, nested loops and special cases into a single function, and reviewers approve it because the behavior is correct. Nothing in the repository suggests the skill is a general-purpose complexity analyzer for a human-written legacy system, although it would not refuse such a codebase. The target user is someone who already works inside Claude and wants the assistant to treat complexity as a measurable quantity rather than a matter of taste. The skill's stated goal is to keep code "maintainable for humans and the long-term vision of the codebase," which frames the work as an ongoing discipline, not a one-off cleanup.
How the skill measures and refactors: worst hotspots first
The README describes a four-step loop. First, measure cyclomatic complexity per function using radon, eslint, gocyclo, lizard, or a manual count. Second, if the project has its own linter thresholds configured, respect those instead of imposing an outside number. Third, refactor the worst hotspots first, using guard clauses, extract function, lookup tables and named predicates. Fourth, end with a before/after complexity table.
The ordering matters. Working from the highest-complexity function down means the first refactor buys the most readability, and it also means the skill does not churn through a file alphabetically. The listed techniques are conventional; the interesting constraint is the refusal to cheat. The README says the skill "Refuses to game the metric. Complexity moves into well-named functions, not into clever one-liners." That is a design stance against the obvious failure mode of any complexity tool: splitting one tangled function into three tangled functions, or replacing a readable if-chain with a dense expression that scores lower and reads worse. Whether the skill holds that line in practice depends on the instructions in the skills/ directory, which the README does not reproduce.
Installing the skill in Claude Code, Claude.ai or the API
The README gives three installation paths. For Claude Code, two plugin commands are documented. Run them in order; the first registers the repository as a marketplace, the second installs the skill from it.
/plugin marketplace add saurabhkumar8112/cyclomatic-complexity-skill
/plugin install cyclomatic-complexity@cyclomatic-complexity-skillFor Claude.ai, the README says to download the `.skill` file from Releases, or zip the `skills/cyclomatic-complexity` folder, then upload it under Settings → Capabilities → Skills. Note that the repository listing shows no releases retrieved, so the zip route may be the only one available today. For the Claude API, the README points to the Skills API guide at docs.claude.com and says nothing further about authentication or upload format.
Once installed, the skill triggers automatically on refactoring, cleanup and code review requests. The README also shows a direct invocation:
"Use the cyclomatic complexity skill to refactor parser.py"The example output the README prints is a markdown table with columns for Function, Before and After, showing `parseOrder` going from 14 to 4, plus two lines noting which functions were extracted and that the existing test suite passes. A first real use is to point it at one file you already distrust and compare that table against your own reading of the diff.
Where the skill stops: no CI gate, no rollback, no threshold list
Three gaps are visible from the README alone. First, this is a Claude skill, not a standalone binary. It runs when Claude runs, so it cannot sit in a pre-commit hook or a CI pipeline the way radon, gocyclo or eslint would. If your goal is to fail a build when a function crosses a threshold, this project is the wrong tool. Second, the README does not document rollback. It says behavior is verified against the existing test suite, which is a claim about the example output, not a description of an undo mechanism. A refactor that passes tests can still change performance characteristics or error messages, and nothing in the README addresses that. Third, the measurement tool is listed as an either/or: radon, eslint, gocyclo, lizard, or manual count. The README never says how the skill chooses between them, so in a polyglot repository you should expect to state the tool yourself. A manual count is also the weakest option, since it depends on the model reading the code correctly rather than on a parser.
Compared with running radon or gocyclo directly
The obvious alternative is to skip the skill and run the underlying tools yourself. Radon for Python, gocyclo for Go and lizard for multi-language analysis all report complexity without an LLM in the loop, and they are deterministic. The difference in approach is the division of labor. A linter tells you which function is bad and stops there; you still decide what guard clause to introduce and where to cut the function. The skill wraps measurement around an edit: it measures, chooses the refactoring technique, applies it, and reports the delta. That is more ambitious and less predictable. A linter's output is reproducible on every machine; a skill's refactor depends on the model's judgment and on the surrounding context it was given. If your team wants a number to argue about, use radon directly. If you want the number plus a proposed rewrite, the skill is the layer that adds the rewrite, at the cost of determinism.
Maintenance, licence and what a refactor actually costs
The repository is not archived. Its last push was on 2026-08-26, which is recent enough that the skill reflects current Claude plugin conventions such as the `.claude-plugin/` directory at the top level and the `/plugin marketplace add` flow. No releases were retrieved, so there is no version history to pin against and no changelog describing breaking changes to the skill's instructions. Upgrading means re-pulling the repository or re-uploading the `.skill` file, and since the skill lives in `skills/cyclomatic-complexity`, the practical cost of an upgrade is re-reading that folder to see whether the refactoring rules changed. The licence is Apache-2.0, which permits commercial use and modification and requires that you keep the licence and notice files; the repository ships a LICENSE file at the top level. That is a permissive licence, but it says nothing about the output the model produces, which is governed by your Claude terms, not by this repository. Treat the licence question as two separate ones: the skill code, and the code Claude writes while using it.
Editorial conclusion
Adopt it if a Claude-driven codebase has grown branch-heavy and you already have a test suite to catch regressions, because the skill's own example output claims behavior is verified by running the existing tests. Skip it if you want an automated gate in CI: this is a skill invoked inside Claude, not a linter, and the README documents no threshold enforcement or rollback. Before trusting a refactor, confirm which tool the skill will measure with, since the README lists radon, eslint, gocyclo, lizard or a manual count without saying how it picks one, and check the skills/ directory for the actual instructions.
Frequently asked questions
What is cyclomatic complexity?
It is the count of independent paths through a function, which is the number the skill measures before and after each refactor. The README shows a function going from 14 to 4, meaning the refactored version has fewer branches to test.
What does cyclomatic mean?
The term comes from the graph measure of how many independent paths run through a piece of code. In this skill it is applied per function, which is why the report is a table of functions with a Before and After column.
What does a higher cyclomatic complexity score mean?
A higher number means more branches and therefore more paths that need testing. The skill treats the highest scores as the worst hotspots and refactors those first, using guard clauses, extract function, lookup tables and named predicates.
What tools can I use to measure cyclomatic complexity?
The README lists radon, eslint, gocyclo and lizard, plus a manual count as a fallback. If your project has its own linter thresholds configured, the skill respects those instead of imposing its own.
Community notes