clean-code
Skill911 starsChanged 3 days agoApache-2.0View on GitHub
Read before writing, refactoring, or reviewing code in any language in this repository. Gives the checkable clean-code rules for names, function shape, nesting, boolean flags, side effects, file size, dead code, duplication, error handling, lint suppressions, and comments.
124 other projects use a version of this.
Adopted by
Most recently taken up by
- bryanus1/agent-skillstheir own version, first seen Nov 16, 2026
- AtilaMedeiros/skillstheir own version, first seen Nov 16, 2026
- Ayobami6/skillstheir own version, first seen Nov 16, 2026
- travissmithv1/claude-skillstheir own version, first seen Nov 16, 2026
- kiaramaldonado/my-favorite-claude-skillstheir own version, first seen Nov 16, 2026
- Ajustor/claude-skillstheir own version, first seen Nov 16, 2026
Used with
Projects with it also use intelligent-routing, nextjs-react-expert and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
SKB3002Skillintelligent-routing
Automatic agent selection and intelligent task routing. Analyzes user requests and automatically selects the best specialist agent(s) without requiring explicit user mentions.
Also in 5 projects that use this
SKB3002Skillnextjs-react-expert
React and Next.js performance optimization from Vercel Engineering. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, reviewing code for performance issues, or implementing server/client-side optimizations.
Also in 3 projects that use this
xfstudioSkillbash-pro
Master of defensive Bash scripting for production automation, CI/CD
Also in 4 projects that use this
xfstudioSkillcode-refactoring-tech-debt
You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create acti
Also in 4 projects that use this
grndlvlSkillpragmatic-programmer
Software craftsmanship principles from The Pragmatic Programmer. Use this skill when discussing best practices, debugging strategies, career development, or pragmatic approaches to software development. Auto-activates for DRY violations, debugging sessions, and development workflow improvements.
Also in 3 projects that use this
nek1987Skillsolid-principles
SOLID object-oriented design principles for maintainable code
Also in 5 projects that use this
- +3 more from xfstudio
Other versions124 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 124
- superplanehq/superplane★ 10ksame name
- vudovn/ag-kit★ 8.2ksame name
- vudovn/antigravity-kit★ 8.2ksame name
- Openpanel-dev/openpanel★ 7.3ksame name
- ciembor/agent-rules-books★ 2.8ksame name
- wondelai/skills★ 2.7ksame name
- decebals/claude-code-java★ 763same name
- operately/operately★ 621same name
- liza-mas/liza★ 418same name
- Mindrally/skills★ 275same name
114 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- backend-guideSkill
- changelogSkill
- frontend-guideSkill
- glossarySkill
- pull-requestsSkill
- python-guideSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 9 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 117 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Use the term from the glossary skill for a domain noun.
- Distinctive: line 34
Use guard clauses. Keep the nesting depth at 2 levels or less.
- Distinctive: line 35
Do not add a boolean argument that selects between two behaviors.
- Very specific: line 58
Do not add noqa, type: ignore, or eslint-disable to pass a lint or type check.
- Distinctive: line 61
If a function is longer than approximately 20 lines, make sure that it still does one thing.
- Distinctive: line 62
Keep a file under 400 lines.
- Distinctive: line 66
Delete dead code and commented-out code.
- Very specific: line 71
Do not catch an exception that you do not handle.
- Distinctive: line 77
If a comment says what the code does, rename or extract until the comment is not necessary.
- Distinctive: line 78
Keep an inline comment short, one line if possible.
- Distinctive: line 81
Write comments, docstrings, and error messages in ASD-STE100 Simplified Technical English: short sentences, active voice, present tense, …
“Common” is measured: kept by at least 6 in 10 of the 117 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Clean Code
Code must be self-descriptive. A reader understands it from the names and the structure, without comments. The language guides add the rules for Python, the backend, and the frontend.
Names
- A name states what the value is or what the function does. Do not use
data,info,tmp,handle, orprocessalone. - Use the term from the glossary skill for a domain noun.
- Give a complex expression a name. Do not write it inline.
# Bad
if sample.width * sample.height > 1024 * 1024 and not sample.tags:
...
# Good
is_large = sample.width * sample.height > MAX_PIXELS
is_untagged = not sample.tags
if is_large and is_untagged:
...Functions
- A function does one thing. You can describe it without the word "and".
- A function has one level of abstraction. It calls helpers or it does the detail work, not both.
- Use guard clauses. Keep the nesting depth at 2 levels or less.
- Do not add a boolean argument that selects between two behaviors. Write two functions.
- A function that returns a value does not change its inputs or global state.
- A function or component accepts only the data that it uses, not the full object.
- Combine small units. Do not build a deep class hierarchy.
# Bad
def export(samples, as_json):
if samples:
for sample in samples:
if sample.is_valid:
...
# Good
def export_json(samples):
for sample in samples:
if not sample.is_valid:
continue
...Size
- Do not add
noqa,type: ignore, oreslint-disableto pass a lint or type check. Fix the code; for a complexity error, split the function. A suppression is acceptable only for an exception that a language guide lists. - If a function is longer than approximately 20 lines, make sure that it still does one thing.
- Keep a file under 400 lines. The frontend guide has a lower limit for components.
Dead Code and Duplication
- Delete dead code and commented-out code.
- Extract duplicated code at the third copy, not before.
Errors
- Do not catch an exception that you do not handle. Do not write a bare
except Exceptionor an emptycatch.
Comments
- The code says what it does. A comment gives a reason that the code cannot show.
- If a comment says what the code does, rename or extract until the comment is not necessary.
- Keep an inline comment short, one line if possible. A longer comment is acceptable for inner logic that names cannot explain. The contract of the function goes in the docstring.
- Describe the current state, not the change.
- Write comments, docstrings, and error messages in ASD-STE100 Simplified Technical English: short sentences, active voice, present tense, and one meaning for each word.
# Bad: Says what the code does.
# Loop over the samples and skip the invalid ones.
# Good: Gives the reason.
# The embedding model accepts at most 64 images in one batch.Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

