Agent Skills: Code Quality Expert

Code Quality Expert

clean code

When reviewing or writing code, apply these guidelines:

Clean Code Guidelines

Constants Over Magic Numbers

• Replace hard-coded values with named constants
• Use descriptive constant names that explain the value's purpose
• Keep constants at the top of the file or in a dedicated constants file

Meaningful Names

• Variables, functions, and classes should reveal their purpose
• Names should explain why something exists and how it's used
• Avoid abbreviations unless they're universally understood

Smart Comments

• Don't comment on what the code does - make the code self-documenting
• Use comments to explain why something is done a certain way
• Document APIs, complex algorithms, and non-obvious side effects

Single Responsibility

• Each function should do exactly one thing
• Functions should be small and focused
• If a function needs a comment to explain what it does, it should be split

DRY (Don't Repeat Yourself)

• Extract repeated code into reusable functions
• Share common logic through proper abstraction
• Maintain single sources of truth

Clean Structure

• Keep related code together
• Organize code in a logical hierarchy
• Use consistent file and folder naming conventions

Encapsulation

• Hide implementation details
• Expose clear interfaces
• Move nested conditionals into well-named functions

Code Quality Maintenance

• Refactor continuously
• Fix technical debt early
• Leave code cleaner than you found it

Testing

• Write tests before fixing bugs
• Keep tests readable and maintainable
• Test edge cases and error conditions

Version Control

• Write clear commit messages
• Make small, focused commits
• Use meaningful branch names

code quality and best practices

When reviewing or writing code, apply these guidelines:

• Adhere to code quality and best practices.
• Apply relevant paradigms and principles.
• Use semantic naming and abstractions.

code quality standards

When reviewing or writing code, apply the principles above consistently. Focus on:

• Readability over cleverness
• Consistency within the codebase
• Progressive improvement (leave code better than you found it)

Consolidated Skills

This expert skill consolidates 1 individual skills:

• code-quality-expert

Iron Laws

1. ALWAYS leave code cleaner than you found it — every change is an opportunity for progressive improvement; accumulating small improvements prevents large-scale refactors from becoming necessary.
2. NEVER use magic numbers — hard-coded values without context make code unreadable and unmaintainable; always extract to named constants with descriptive names that explain the purpose.
3. ALWAYS write self-documenting code first, then add comments only for "why" — comments explaining "what" the code does are redundant and become stale; reserve comments for non-obvious design decisions.
4. NEVER allow functions to do more than one thing — single responsibility is the strongest predictor of testability and maintainability; a function needing a "and" in its name should be split.
5. NEVER optimize prematurely — write clear, correct code first; profile to identify actual bottlenecks before optimizing; premature optimization produces complex code with unmeasured benefit.

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | -------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------- | | Magic numbers in logic | if (status === 200) is opaque; value could change | Extract to const HTTP_OK = 200 with clear name | | Comments explaining "what" not "why" | Code changes make comments stale and misleading | Write self-documenting code; comment only design rationale | | God functions (>50 lines, multiple concerns) | Hard to test, debug, and modify independently | Extract single-purpose functions with clear names | | Premature optimization | Adds complexity before proving a bottleneck exists | Profile first; only optimize measured hot paths | | Duplicated code blocks | Bug fixes must be applied in N places | Extract to reusable function; DRY principle |

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.