Index of every page on this site: llms.txt
All skills
davila7 avatar

/clean-code

@053feb2
Run it yourself

Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments

Use this Skill: https://skilld.dev/gh/davila7/claude-code-templates/clean-code

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈26 tokens for metadata: the name and description. ≈1.6k when used: this file.

Description uses 1.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈103 characters, or 1.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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-engineer running ux_audit.py ✅ CORRECT: frontend-specialist running ux_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?**
  1. Wait for user confirmation before fixing
  2. 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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings27d5 checks · Risk MEDIUM
  • Gen Agent Trust Hub27d

    The skill mandates the execution of external Python scripts from a hidden system directory and encourages direct code modifications without verification of potential instructions embedded in source files.

  • Socket27d

    1 alert: gptSecurity

  • Snyk27d

    Risk: LOW · No issues

  • Runlayer9mo

    1 file scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 053feb2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month
What it can do
Reads files Edits files
metadata
{
  "version": 2,
  "priority": "CRITICAL"
}
All 3 allowed tools
ReadWriteEdit

README badge

README badge for davila7/claude-code-templates/clean-code