Skip to main content
affpapa.org
RU EN
skill CX Codex

code-quality · zernie — Claude Code skill for TS/JS quality

A skill for refactoring TypeScript and JavaScript: tightens types, removes impossible states, and separates logic from IO.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add zernie/vigiles --skill code-quality -a claude-code
Open on GitHub

What code-quality does

The skill fires when you ask to refactor, clean up, harden or review the design of code or a public API. It does not hunt bugs — that job belongs to /code-review. Five techniques sit inside, each with its own reference file: the principle, a before/after from the repo, and the smells to grep for.

The techniques cover parsing at the boundary instead of re-validating primitives, types that make illegal states unrepresentable, exhaustiveness guards on switch and if chains over unions, pure functions with injected seams for spawn, fetch and fs, and the shape of public exports. Read the reference that matches the code in front of you, not all five at once.

The workflow is strict. Name the decision out loud first, then change the type and let tsc point at every call site, fix them, run the tests. One technique per change, tests stay green. An abstraction for a difference that does not exist yet is the bug this skill exists to prevent, so rule-of-three and YAGNI cut against you here.

What it helps with

  • stop re-validating the same primitive at many call sites
  • make an impossible field combination fail to compile
  • add an exhaustiveness guard to a switch over a union
  • pull pure logic away from fetch and fs so it can be tested
  • narrow a public export to a clear shape

Example prompts for the agent

  • refactor the orders module and apply parse-don't-validate at the boundary
  • drop the boolean flags on Job and make illegal states unrepresentable
  • go through the package's public exports and tighten their shape

How to install code-quality

1Skills CLI (Vercel)

npx skills add zernie/vigiles --skill code-quality -a claude-code

2Manually: put the files in place

~/.claude/skills/code-quality/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/code-quality/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about code-quality

How do I install code-quality in Claude?

Run npx skills add zernie/vigiles --skill code-quality -a claude-code. The skill lands at ~/.claude/skills/code-quality/SKILL.md.

What does code-quality do?

It applies a set of type-driven techniques to TypeScript and JavaScript: parsing at boundaries, unrepresentable illegal states, exhaustive union matching, pure functions with injected seams, and public-API hygiene.

How is code-quality different from code-review?

One works on shape and design, the other hunts bugs. The skill states plainly that bug hunting is not its job.

Source text

SKILL.md · MIT 
---
name: code-quality
description: Improve the quality and type-safety of TypeScript/JavaScript being written or refactored — parse-don't-validate, make-illegal-states-irrepresentable, exhaustive matching, pure-function/IO separation, and public-API hygiene. Use when asked to refactor, clean up, improve, harden, or review the design/quality of code or an API. NOT for hunting bugs (that's /code-review) and NOT for vigiles's own spec/lint rules.
---

Apply a small set of **type-driven** quality techniques when writing or refactoring code. Each technique has its own reference — the principle, a real before/after from this repo, and the smells to grep for. **Read the reference(s) that match the code in front of you; don't apply all five blindly.**

## When this fires

A request to _refactor / clean up / improve / harden / tighten_ code or an API — or when you're about to write a new module/type/public export and want it right the first time. Not a bug hunt (use `/code-review`).

## The techniques — read the matching reference

| Smell in front of you                                                                                                       | Technique                               | Reference                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| a magic `0` / `""` / `-1`; the same primitive re-validated at many sites; `"x" in obj` repeated                             | **Parse, don't validate**               | [`references/parse-dont-validate.md`](references/parse-dont-validate.md)                                 |
| a field that's always `""`; boolean-flag soup; a sentinel standing in for "absent"; an impossible combo that still compiles | **Make illegal states irrepresentable** | [`references/make-illegal-states-irrepresentable.md`](references/make-illegal-states-irrepresentable.md) |
| a `switch`/`if`-chain on a union with no exhaustiveness guard                                                               | **Exhaustive matching**                 | [`references/exhaustive-matching.md`](references/exhaustive-matching.md)                                 |
| logic tangled with IO (`spawn`/`fetch`/`fs`); a function that's hard to test                                                | **Pure functions + injected seams**     | [`references/pure-functions.md`](references/pure-functions.md)                                           |
| a public export with a fuzzy shape; a `string` that means an enum; a leaked internal helper                                 | **Public-API quality**                  | [`references/public-api-quality.md`](references/public-api-quality.md)                                   |

## How to apply

1. **Name the decision out loud** before you change the shape — what illegal state it forbids, where the parse boundary sits (the `surface-architecture-decisions` reflex). A quality change the reviewer can't see is churn.
2. **One technique at a time, tests stay green.** Change the type, let `tsc` show you every call site, fix them, run the tests. Never batch five refactors into one unreviewable diff.
3. **Don't over-abstract** (rule-of-three / YAGNI). A tagged union for 3 real variants is good; an abstraction for a difference that doesn't exist yet is the bug this skill is supposed to prevent.
4. **Prefer the strongest option the DECIDABILITY allows** — a type that can't express the bad state beats a runtime check that hopes to catch it; but a runtime guard at a boundary beats nothing when the input is genuinely dynamic.

## Guardrails

- **Quality only, not correctness.** This skill improves shape/design; it does not hunt for bugs — that's `/code-review`.
- **Every change removes a real failure mode.** If you can't name the bug the new shape prevents, don't make the change.
- **Keep the public surface small.** A new `export` is a contract (see the public-API reference); don't widen it to make a refactor convenient.

© zernie · MIT · zernie/vigiles

Similar skills

All skills for Code review and refactoring →

code-quality by other authors comes first.

code-quality tursodatabase Correctness rules, Rust patterns, and anti-over-engineering guidance for coding agents working in your repo. CX Codex +1 1,800installs typescript-quality claude-dev-suite A skill for TypeScript and JavaScript code quality: ESLint, Biome and strict tsconfig setups. Useful when lint rules pile up and types start drifting. CX Codex +1 1,100installs coding-standards affaan-m Baseline cross-project coding conventions for naming, immutability, and clean code principles. Useful for code reviews and refactoring. CX Codex +1 5,700installs dry-refactoring kucherenko This skill automates refactoring of copy-paste clones found by jscpd. It guides you through extraction strategies—function, parameterization, module or class—and highlights which files to start with. CX Codex +1 3,600installs principle-type-system-discipline backnotprop Enforces strict type system rules: brand semantic primitives, parse external data at boundaries, and derive types directly from schemas. CX Codex +1 5,300installs improve-code-quality wondelai Guides untested prototypes toward production code with tests, clean boundaries, and system resilience. Useful when code works but feels too fragile to touch. CX Codex +1 2,300installs typescript-variables mkosir Applies TypeScript variable conventions: const assertions, enum replacement with literal types, unions over boolean flags, null vs undefined distinction. CX Codex +1 3,800installs

From the same set7

test-harness A skill that tests the Claude harness: hooks, skills, agents, settings and CLAUDE.md. It picks the right test tier and writes the test. CX Codex +1 2,100installs strengthen Scans vigiles specs and swaps guidance() rules for enforce(), matching each one to a linter rule that already exists. Useful when written conventions should fail CI on their own. CX Codex +1 2,100installs linter-docs A reference for rules in ESLint, Ruff, Pylint, RuboCop, Stylelint and Clippy. Use it when writing or debugging a vigiles enforce() rule. CX Codex +1 2,000installs adopt-spec Turns an existing CLAUDE.md or AGENTS.md into a typed CLAUDE.md.spec.ts without touching the original file. Useful when you want lint-checked instructions but dread rewriting them. CX Codex +1 1,800installs debug-my-harness Reads the local .vigiles/runs.jsonl ledger to explain why an agent harness misbehaved. Use it when a skill stopped firing, a hook let something through, or a subagent broke its tool contract. CX Codex +1 1,500installs verify-docs-findable Checks whether repo docs actually answer reader questions. Spawns cheap Haiku agents that read only the docs and expose where answers get lost. CX Codex +1 340installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor