Clean Code Skill

A portable agent skill that holds a set of language-agnostic clean-code engineering standards: strong naming, small focused methods, explicit side effects, test-first development, and continuous refactoring.

It works with any coding agent that supports the open Agent Skills format, including Claude Code, Codex, and Cursor.

You do not need to paste anything into your AGENTS.md, CLAUDE.md, or system prompt. Once installed, the agent reads the skill's description and loads it on its own when you ask it to "write clean code", "follow clean-code principles", "refactor for clarity", "improve naming", "work test-first", or similar.

What's in the skill

The installable skill lives in skills/clean-code/:

• SKILL.md — the concise, mandatory operating contract (14 core rules).
• reference.md — expanded rationale, examples, and design heuristics the agent consults on demand.

Installation

Option 1 — npx skills (recommended)

The skills CLI installs the skill for every coding agent it detects on your machine:

npx skills add markoa/clean-code-skill

Useful follow-ups:

npx skills list      # show installed skills and which agents have them
npx skills update    # pull the latest version of installed skills
npx skills remove clean-code

Run npx skills add --help to see how to scope an install to specific agents.

Option 2 — Clone and copy

Clone the repo and copy the skill folder into your agent's skills directory.

git clone https://github.com/markoa/clean-code-skill.git

Global (available in every project):

cp -r clean-code-skill/skills/clean-code ~/.claude/skills/clean-code    # Claude Code
cp -r clean-code-skill/skills/clean-code ~/.codex/skills/clean-code     # Codex
cp -r clean-code-skill/skills/clean-code ~/.cursor/skills/clean-code    # Cursor

Per-project (checked into a single repo):

cp -r clean-code-skill/skills/clean-code .claude/skills/clean-code      # Claude Code
cp -r clean-code-skill/skills/clean-code .agents/skills/clean-code      # Codex & Cursor

Option 3 — Git submodule

Vendor the repo as a submodule and symlink the skill into place. Updating is then a git submodule update --remote.

git submodule add https://github.com/markoa/clean-code-skill.git vendor/clean-code-skill
ln -s ../../vendor/clean-code-skill/skills/clean-code .claude/skills/clean-code

Option 4 — Claude plugin (coming soon)

A Claude Code plugin distribution is planned so you can install via the plugin marketplace. Not available yet — use one of the options above for now.

Verifying it's installed

• Run npx skills list and confirm clean-code appears for your agent, or
• Ask your agent something like "follow clean code principles and refactor this function" and confirm it applies the standards.

How it triggers

Agent Skills are discovered through the description: field in SKILL.md. The agent matches your request against that description and loads the skill's instructions only when relevant — no manual context wiring, and no permanent cost to your prompt when you're doing unrelated work.

License

MIT