Skip to main content

​
Overview

The clean-code skill provides pragmatic coding standards focused on being concise, direct, and solution-focused. It emphasizes writing code that is easy to understand, maintain, and extend without over-engineering.

​
What This Skill Provides

  • Core Principles: SRP, DRY, KISS, YAGNI, Boy Scout Rule
  • Naming Rules: Clear, intentional naming conventions
  • Function Rules: Small, focused functions
  • Code Structure: Guard clauses, flat over nested, composition
  • AI Coding Style: Direct action over explanation
  • Anti-Patterns: What to avoid in code
  • Verification Scripts: Automated quality checks
  • Pre-Completion Checklist: Self-verification before finishing

​
Core Principles

PrincipleRule
SRPSingle Responsibility - each function/class does ONE thing
DRYDon’t Repeat Yourself - extract duplicates, reuse
KISSKeep It Simple - simplest solution that works
YAGNIYou Aren’t Gonna Need It - don’t build unused features
Boy ScoutLeave code cleaner than you found it

​
Naming Rules

ElementConvention
VariablesReveal intent: userCount not n
FunctionsVerb + noun: getUserById() not user()
BooleansQuestion form: isActive, hasPermission, canEdit
ConstantsSCREAMING_SNAKE: MAX_RETRY_COUNT
Rule: If you need a comment to explain a name, rename it.

​
Function Rules

RuleDescription
SmallMax 20 lines, ideally 5-10
One ThingDoes one thing, does it well
One LevelOne level of abstraction per function
Few ArgsMax 3 arguments, prefer 0-2
No Side EffectsDon’t mutate inputs unexpectedly

​
Code Structure

PatternApply
Guard ClausesEarly returns for edge cases
Flat > NestedAvoid deep nesting (max 2 levels)
CompositionSmall functions composed together
ColocationKeep related code close

​
AI Coding Style

SituationAction
User asks for featureWrite it directly
User reports bugFix it, don’t explain
No clear requirementAsk, don’t assume

​
Use Cases

​
When to Use This Skill

  • Writing new code
  • Refactoring existing code
  • Code review and quality checks
  • Teaching coding standards
  • Establishing team conventions

​
Example Scenarios

  1. New Feature: Apply clean code principles from the start
  2. Refactoring: Improve naming, reduce complexity, extract functions
  3. Code Review: Identify violations of clean code principles
  4. Debugging: Clean code makes bugs easier to find

​
Anti-Patterns to Avoid

❌ Pattern✅ Fix
Comment every lineDelete obvious comments
Helper for one-linerInline the code
Factory for 2 objectsDirect instantiation
utils.ts with 1 functionPut code where used
”First we import…”Just write code
Deep nestingGuard clauses
Magic numbersNamed constants
God functionsSplit by responsibility

​
Before Editing Files

THINK FIRST! Before changing a file, ask:
QuestionWhy
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
Rule: Edit the file + all dependent files in the SAME task. Never leave broken imports.

​
Self-Check Before Completing

Before saying “task complete”, verify:
CheckQuestion
✅ 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?

​
Verification Scripts

​
Agent → Script Mapping

AgentScriptCommand
frontend-specialistUX Auditpython .agent/skills/frontend-design/scripts/ux_audit.py .
frontend-specialistA11y Checkpython .agent/skills/frontend-design/scripts/accessibility_checker.py .
backend-specialistAPI Validatorpython .agent/skills/api-patterns/scripts/api_validator.py .
database-architectSchema Validatepython .agent/skills/database-design/scripts/schema_validator.py .
security-auditorSecurity Scanpython .agent/skills/vulnerability-scanner/scripts/security_scan.py .
test-engineerTest Runnerpython .agent/skills/testing-patterns/scripts/test_runner.py .
test-engineerPlaywrightpython .agent/skills/webapp-testing/scripts/playwright_runner.py <url>
Any agentLint Checkpython .agent/skills/lint-and-validate/scripts/lint_runner.py .
Any agentType Coveragepython .agent/skills/lint-and-validate/scripts/type_coverage.py .

​
Script Output Handling

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 with clear categories
  4. Wait for user confirmation before fixing
  5. After fixing → Re-run script to confirm
Format: 
## Script Results: [script_name.py]

### ❌ Errors Found (X items)
- [File:Line] Error description

### ⚠️ Warnings (Y items)
- [File:Line] Warning description

### ✅ Passed (Z items)
- Check passed

**Should I fix the X errors?**
  • code-review-checklist: Quality standards for reviews
  • testing-patterns: Clean test code
  • refactoring-patterns: Improving existing code
  • lint-and-validate: Automated quality checks

​
Which Agents Use This Skill

This is a CRITICAL SKILL used by ALL agents in the Antigravity Kit:
  • frontend-specialist
  • backend-specialist
  • database-architect
  • test-engineer
  • security-auditor
  • devops-engineer
  • mobile-developer
  • game-developer
  • And more…

​
Summary

DoDon’t
Write code directlyWrite tutorials
Let code self-documentAdd obvious comments
Fix bugs immediatelyExplain the fix first
Inline small thingsCreate unnecessary files
Name things clearlyUse abbreviations
Keep functions smallWrite 100+ line functions

​
Tools Available

  • Read, Write, Edit: Core file operations
Remember: The user wants working code, not a programming lesson. Be concise, direct, and solution-focused.

Build docs developers (and LLMs) love

Get started for freeTalk to us