clean-code skill

An agent skill that makes Claude Code, opencode, and other SKILL.md-compatible coding agents write and review code to professional craftsmanship standards.

It distills two of Robert C. Martin's books into one skill your agent loads on demand:

• Clean Code — naming, functions, formatting, comments, error handling, and code smells.
• The Clean Coder — TDD discipline, honest estimation, acceptance testing, and knowing when to say no.

Once installed, your agent applies these standards automatically on any non-trivial coding task — writing, refactoring, fixing bugs — and can produce structured, prioritized code reviews on request.

Installation

Requires Node.js ≥ 16. No clone, no config — npx fetches the package and copies the skill straight into the directory your agent reads.

# Interactive — pick where to install
npx @mahmoud_abied/clean-code-skill

# Or target a destination directly:
npx @mahmoud_abied/clean-code-skill claude    # ~/.claude/skills  (Claude Code; opencode reads this too)
npx @mahmoud_abied/clean-code-skill opencode  # ~/.config/opencode/skills
npx @mahmoud_abied/clean-code-skill all       # both of the above
npx @mahmoud_abied/clean-code-skill project   # ./.claude/skills  (current project only)

| Target | Installs to | Read by | |---|---|---| | claude | ~/.claude/skills/clean-code/ | Claude Code, Claude Desktop, opencode | | opencode | ~/.config/opencode/skills/clean-code/ | opencode | | project | ./.claude/skills/clean-code/ | Claude Code & opencode, for that repo only |

Claude Code and opencode both read ~/.claude/skills/, so claude alone covers most setups. Use all only if you keep opencode skills in its own config directory.

Shell one-liner (macOS / Linux / WSL — no Node required):

curl -fsSL https://raw.githubusercontent.com/mahmoudabied/clean_code_skill/main/install.sh | bash

From a clone (lets you inspect first):

git clone https://github.com/mahmoudabied/clean_code_skill.git
cd clean_code_skill
./install.sh                 # interactive; or --claude | --opencode | --all | --project | --uninstall

Windows (PowerShell, native):

git clone https://github.com/mahmoudabied/clean_code_skill.git
cd clean_code_skill
.\install.ps1                # interactive; or -Target all | -Uninstall

Make: make install · make install-all · make uninstall

Usage

Restart your agent (or start a fresh session) after installing so it picks up the skill.

Verify it loaded — in Claude Code, run /skills; clean-code should appear in the list.

Then just work normally. The skill activates on its own whenever you:

• write new code, implement a feature, refactor, or fix a bug;
• ask for a code review (e.g. "review this file for clean code issues");
• ask "is this clean?", or mention code quality, technical debt, naming, or test coverage;
• ask the agent to follow TDD (e.g. "implement X test-first").

You don't need to name the skill — the agent consults it by default for non-trivial work.

What's inside

skills/clean-code/
├── SKILL.md                          # triggers + core principles (always loaded)
└── references/
    ├── writing-clean-code.md         # naming, functions, comments, errors, smells
    ├── professional-discipline.md    # TDD laws, test pyramid, estimates, saying no
    └── review-checklist.md           # severity-graded review checklist

The skill uses progressive disclosure: the agent always sees the short SKILL.md and loads a detailed reference file only when a task needs it — keeping token usage low.

Updating & uninstalling

npx @mahmoud_abied/clean-code-skill all        # re-run to update to the latest version
npx @mahmoud_abied/clean-code-skill uninstall  # remove from all known locations

License & attribution

MIT — see LICENSE.

The principles summarize ideas from Clean Code and The Clean Coder by Robert C. Martin. This package contains original wording, not text from the books, and is not affiliated with or endorsed by the author or publisher.