Clean Code
- 901 installs
- 29.9k repo stars
- Updated July 27, 2026
- davila7/claude-code-templates
clean-code is a Claude Code skill that enforces pragmatic coding standards—concise, direct, and free of over-engineering—for developers using AI agents to write production code.
About
clean-code is a CRITICAL-priority Claude Code skill (version 2.0) from davila7/claude-code-templates that keeps agent-generated codebases concise, readable, and free of over-engineering. It codifies SRP, DRY, KISS, YAGNI, and Boy Scout principles with explicit rules against unnecessary comments and bloated abstractions. Allowed tools are Read, Write, and Edit so the skill shapes code as agents produce it. Developers invoke clean-code when AI output drifts verbose, over-abstracted, or comment-heavy and they want consistent pragmatic standards across functions and classes.
- Enforces 5 core principles: SRP, DRY, KISS, YAGNI, Boy Scout Rule
- Implements strict naming conventions that reveal intent without comments
- Limits functions to 20 lines maximum with 0-3 arguments and no side effects
- Applies guard clauses, early returns, and single level of abstraction
- CRITICAL priority skill that leaves every file cleaner than it was found
Clean Code by the numbers
- 901 all-time installs (skills.sh)
- +26 installs in the week ending Jul 28, 2026 (Skillselion tracking)
- Ranked #143 of 1,382 Code Review & Quality skills by installs in the Skillselion catalog
- Security screen: HIGH risk (skills.sh audit)
- Data as of Jul 28, 2026 (Skillselion catalog sync)
npx skills add https://github.com/davila7/claude-code-templates --skill clean-codeAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 901 |
|---|---|
| repo stars | ★ 29.9k |
| Security audit | 1 / 3 scanners passed |
| Last updated | July 27, 2026 |
| Repository | davila7/claude-code-templates ↗ |
How do you stop AI agents from over-engineering code?
Make every agent-generated codebase concise, readable, and free of over-engineering.
Who is it for?
Developers using Claude Code agents who want CRITICAL-priority guardrails against verbose or over-engineered generated code.
Skip if: Teams needing formal security audits or lint rule enforcement should use dedicated review or linter skills instead of clean-code style guidance.
When should I use this skill?
Agent output is verbose, over-abstracted, comment-heavy, or violates SRP, DRY, KISS, or YAGNI principles.
What you get
Refactored concise code, reduced abstractions, pragmatic functions following clean-code rules
- Simplified code changes
- Refactored functions
By the numbers
- Skill version 2.0 with CRITICAL priority
- Allowed tools: Read, Write, Edit
Files
Clean Code - Pragmatic AI Coding Standards
CRITICAL SKILL - Be concise, direct, and solution-focused.
---
Core Principles
| Principle | Rule |
|---|---|
| SRP | Single Responsibility - each function/class does ONE thing |
| DRY | Don't Repeat Yourself - extract duplicates, reuse |
| KISS | Keep It Simple - simplest solution that works |
| YAGNI | You Aren't Gonna Need It - don't build unused features |
| Boy Scout | Leave code cleaner than you found it |
---
Naming Rules
| Element | Convention |
|---|---|
| Variables | Reveal intent: userCount not n |
| Functions | Verb + noun: getUserById() not user() |
| Booleans | Question form: isActive, hasPermission, canEdit |
| Constants | SCREAMING_SNAKE: MAX_RETRY_COUNT |
Rule: If you need a comment to explain a name, rename it.
---
Function Rules
| Rule | Description |
|---|---|
| Small | Max 20 lines, ideally 5-10 |
| One Thing | Does one thing, does it well |
| One Level | One level of abstraction per function |
| Few Args | Max 3 arguments, prefer 0-2 |
| No Side Effects | Don't mutate inputs unexpectedly |
---
Code Structure
| Pattern | Apply |
|---|---|
| Guard Clauses | Early returns for edge cases |
| Flat > Nested | Avoid deep nesting (max 2 levels) |
| Composition | Small functions composed together |
| Colocation | Keep related code close |
---
AI Coding Style
| Situation | Action |
|---|---|
| User asks for feature | Write it directly |
| User reports bug | Fix it, don't explain |
| No clear requirement | Ask, don't assume |
---
Anti-Patterns (DON'T)
| ❌ Pattern | ✅ Fix |
|---|---|
| Comment every line | Delete obvious comments |
| Helper for one-liner | Inline the code |
| Factory for 2 objects | Direct instantiation |
| utils.ts with 1 function | Put code where used |
| "First we import..." | Just write code |
| Deep nesting | Guard clauses |
| Magic numbers | Named constants |
| God functions | Split by responsibility |
---
🔴 Before Editing ANY File (THINK FIRST!)
Before changing a file, ask yourself:
| Question | Why |
|---|---|
| What imports this file? | They might break |
| What does this file import? | Interface changes |
| What tests cover this? | Tests might fail |
| Is this a shared component? | Multiple places affected |
Quick Check:
File to edit: UserService.ts
└── Who imports this? → UserController.ts, AuthController.ts
└── Do they need changes too? → Check function signatures🔴 Rule: Edit the file + all dependent files in the SAME task.
🔴 Never leave broken imports or missing updates.
---
Summary
| Do | Don't |
|---|---|
| Write code directly | Write tutorials |
| Let code self-document | Add obvious comments |
| Fix bugs immediately | Explain the fix first |
| Inline small things | Create unnecessary files |
| Name things clearly | Use abbreviations |
| Keep functions small | Write 100+ line functions |
Remember: The user wants working code, not a programming lesson.
---
🔴 Self-Check Before Completing (MANDATORY)
Before saying "task complete", verify:
| Check | Question |
|---|---|
| ✅ Goal met? | Did I do exactly what user asked? |
| ✅ Files edited? | Did I modify all necessary files? |
| ✅ Code works? | Did I test/verify the change? |
| ✅ No errors? | Lint and TypeScript pass? |
| ✅ Nothing forgotten? | Any edge cases missed? |
🔴 Rule: If ANY check fails, fix it before completing.
---
Verification Scripts (MANDATORY)
🔴 CRITICAL: Each agent runs ONLY their own skill's scripts after completing work.
Agent → Script Mapping
| Agent | Script | Command |
|---|---|---|
| frontend-specialist | UX Audit | python ~/.claude/skills/frontend-design/scripts/ux_audit.py . |
| frontend-specialist | A11y Check | python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py . |
| backend-specialist | API Validator | python ~/.claude/skills/api-patterns/scripts/api_validator.py . |
| mobile-developer | Mobile Audit | python ~/.claude/skills/mobile-design/scripts/mobile_audit.py . |
| database-architect | Schema Validate | python ~/.claude/skills/database-design/scripts/schema_validator.py . |
| security-auditor | Security Scan | python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py . |
| seo-specialist | SEO Check | python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py . |
| seo-specialist | GEO Check | python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py . |
| performance-optimizer | Lighthouse | python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url> |
| test-engineer | Test Runner | python ~/.claude/skills/testing-patterns/scripts/test_runner.py . |
| test-engineer | Playwright | python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url> |
| Any agent | Lint Check | python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py . |
| Any agent | Type Coverage | python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py . |
| Any agent | i18n Check | python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py . |
❌ WRONG:test-engineerrunningux_audit.py
✅ CORRECT:frontend-specialistrunningux_audit.py
---
🔴 Script Output Handling (READ → SUMMARIZE → ASK)
When running a validation script, you MUST:
1. Run the script and capture ALL output 2. Parse the output - identify errors, warnings, and passes 3. Summarize to user in this format:
## Script Results: [script_name.py]
### ❌ Errors Found (X items)
- [File:Line] Error description 1
- [File:Line] Error description 2
### ⚠️ Warnings (Y items)
- [File:Line] Warning description
### ✅ Passed (Z items)
- Check 1 passed
- Check 2 passed
**Should I fix the X errors?**4. Wait for user confirmation before fixing 5. After fixing → Re-run script to confirm
🔴 VIOLATION: Running script and ignoring output = FAILED task.
🔴 VIOLATION: Auto-fixing without asking = Not allowed.
🔴 Rule: Always READ output → SUMMARIZE → ASK → then fix.
Related skills
Improve Codebase ArchitectureSafely deepen clusters of shallow modules into cohesive, testable units while respecting their external dependencies.531k185k
Caveman ReviewGet ultra-compressed, one-line code review comments that cut noise while keeping every actionable fix.260k92.5kCodebase DesignShared vocabulary for designing deep modules: improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable.233k185kCavecrewDelegate coding tasks to specialized subagents that return compressed output, keeping the main context window usable for much longer sessions.210k92.5k
Requesting Code ReviewDispatch a consistent, high-signal code reviewer subagent that catches plan deviations and quality issues before merging or continuing development.178k260kCode ReviewReviews a branch or PR diff on two axes at once: conformance to coding standards plus a code-smell baseline, and whether it actually implements the original spec.167k185kForks & variants (1)
Clean Code has 1 known copy in the catalog totaling 2 installs. They canonicalize to this original listing.
- xenitv1 - 2 installs
How it compares
Use clean-code for ongoing pragmatic style guardrails; use formal code-review skills when you need structured PR checklists or security-focused review.
FAQ
What principles does clean-code enforce?
clean-code (v2.0) enforces SRP, DRY, KISS, YAGNI, and Boy Scout rules, prioritizing concise, direct solutions without unnecessary comments or over-engineered abstractions in agent-written code.
When should developers enable clean-code?
Developers should enable clean-code when AI agents produce verbose, over-abstracted, or comment-heavy code and they want CRITICAL-priority pragmatic standards applied during Read, Write, and Edit operations.
Is Clean Code safe to install?
skills.sh reports 1 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.