agentleFS
lightly-ailightly-ai/lightly-studio/.agents/skills/clean-code/SKILL.md

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

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.
  • SKB3002Skill

    intelligent-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

  • SKB3002Skill

    nextjs-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

  • xfstudioSkill

    bash-pro

    Master of defensive Bash scripting for production automation, CI/CD

    Also in 4 projects that use this

  • xfstudioSkill

    code-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

  • grndlvlSkill

    pragmatic-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

  • nek1987Skill

    solid-principles

    SOLID object-oriented design principles for maintainable code

    Also in 5 projects that use this

  • +3 more from xfstudio

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
  1. Distinctive:

    Use the term from the glossary skill for a domain noun.

    line 15
  2. Distinctive:

    Use guard clauses. Keep the nesting depth at 2 levels or less.

    line 34
  3. Distinctive:

    Do not add a boolean argument that selects between two behaviors.

    line 35
  4. Very specific:

    Do not add noqa, type: ignore, or eslint-disable to pass a lint or type check.

    line 58
  5. Distinctive:

    If a function is longer than approximately 20 lines, make sure that it still does one thing.

    line 61
  6. Distinctive:

    Keep a file under 400 lines.

    line 62
  7. Distinctive:

    Delete dead code and commented-out code.

    line 66
  8. Very specific:

    Do not catch an exception that you do not handle.

    line 71
  9. Distinctive:

    If a comment says what the code does, rename or extract until the comment is not necessary.

    line 77
  10. Distinctive:

    Keep an inline comment short, one line if possible.

    line 78
  11. Distinctive:

    Write comments, docstrings, and error messages in ASD-STE100 Simplified Technical English: short sentences, active voice, present tense, …

    line 81

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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, or process alone.
  • 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, or eslint-disable to 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 Exception or an empty catch.

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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.