agentleFS
mertdeveci5mertdeveci5/skills/skills/kiss/SKILL.md

kiss

Skill1 starsChanged 5 months agoMITView on GitHub

Apply KISS engineering principles while planning, implementing, reviewing, or simplifying code. Use when the user invokes $kiss, asks to keep code simple, reduce complexity, fix root causes, remove dead code, or evaluate architecture against simplicity.

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

28 rules. 0 are common, 27 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 27

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill as engineering guidance loaded into your own context.

    line 8
  2. Distinctive:

    Read the relevant code first and let the existing ownership boundaries guide the change.

    line 12
  3. Distinctive:

    Prefer removing, replacing, or simplifying code over adding more code.

    line 13
  4. Distinctive:

    Keep one clear behavior path.

    line 15
  5. Distinctive:

    Avoid speculative abstractions, feature flags, options, env vars, wrappers, and helpers.

    line 16
  6. Distinctive:

    Keep error boundaries, validation, and user-visible failure messages where data enters or leaves the system.

    line 17
  7. Distinctive:

    Do not scan for AGENTS.md or CLAUDE.md.

    line 24
  8. Distinctive:

    Do not create missing instruction files.

    line 25
  9. Distinctive:

    Do not add a KISS section to project docs.

    line 26
  10. Distinctive:

    Do not add pointer lines that reference this skill.

    line 27
  11. Distinctive:

    If the user separately asks to edit docs, only edit the files and content they requested.

    line 28
  12. Distinctive:

    No legacy fallbacks or backward compatibility shims.

    line 34
  13. Distinctive:

    No magic values. Avoid hardcoded strings or numbers that only make sense if you wrote them.

    line 37
  14. Distinctive:

    When a bug or bad behavior appears, do not patch only where the symptom appears.

    line 44
  15. Distinctive:

    If the problem is architectural, fix the architecture.

    line 50
  16. Distinctive:

    After a codebase reaches meaningful complexity, the right move is often to reduce code rather than add code.

    line 54
  17. Distinctive:

    Do not pull in a library for something that is straightforward local code.

    line 64
  18. Distinctive:

    Do not create base classes, interfaces, factories, or generic helpers for one implementation.

    line 65
  19. Distinctive:

    Do not add wrapper layers around libraries unless there is a real boundary to isolate.

    line 66
  20. Distinctive:

    Do not add logging, metrics, retry logic, caching, or toggles unless they solve the current problem.

    line 67
  21. Distinctive:

    Prefer direct imports over barrel files that only re-export.

    line 68
  22. Distinctive:

    No unused parameters, options, types, helpers, or files.

    line 73
  23. Distinctive:

    No types or interfaces that mirror data one-to-one without adding constraints.

    line 74
  24. Distinctive:

    If a function takes more than four parameters, check whether it is doing too much.

    line 75
  25. Distinctive:

    If a file is large because it mixes concerns, split by ownership rather than by arbitrary helper categories.

    line 76
  26. Distinctive:

    If a function needs a comment to explain what it does, prefer a clearer name or smaller function.

    line 77
  27. Very specific:

    No abbreviations unless they are universal, such as id, url, or db.

    line 78
  28. Distinctive:

    If I delete any piece of what I added, does something visibly break?

    line 87

“Common” is measured: kept by at least 6 in 10 of the 5 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

KISS — Keep It Simple

Use this skill as engineering guidance loaded into your own context. Do not inject, append, or copy these instructions into a repository's AGENTS.md, CLAUDE.md, README, or other project docs unless the user explicitly asks for documentation edits.

Operating Rules

  • Read the relevant code first and let the existing ownership boundaries guide the change.
  • Prefer removing, replacing, or simplifying code over adding more code.
  • Fix root causes instead of layering patches over symptoms.
  • Keep one clear behavior path. Do not leave old paths alive as hidden fallbacks.
  • Avoid speculative abstractions, feature flags, options, env vars, wrappers, and helpers.
  • Keep error boundaries, validation, and user-visible failure messages where data enters or leaves the system.
  • Report what was simplified or removed when that matters for the user's review.

Do Not Modify Project Docs By Default

Loading this skill is not a request to modify repository instruction files.

  • Do not scan for AGENTS.md or CLAUDE.md.
  • Do not create missing instruction files.
  • Do not add a KISS section to project docs.
  • Do not add pointer lines that reference this skill.
  • If the user separately asks to edit docs, only edit the files and content they requested.

Core Principles

Simplicity means building a system that does a limited set of things in specific ways, reducing the surface area where bugs can happen. Simple does not mean fragile, naive, or incomplete; it means every piece earns its place.

  • No legacy fallbacks or backward compatibility shims. When you change something, change it. If something is removed, tell the user what was removed and why.
  • Linear code flow. A reader should be able to follow the codebase top-to-bottom without jumping between unrelated files to understand what happens.
  • Mutually exclusive structure. Directories own their domain. Files own their responsibility. Functions own their task.
  • No magic values. Avoid hardcoded strings or numbers that only make sense if you wrote them. Configuration should be minimal and intentional.
  • One change, one path. Replace behavior instead of layering a new path beside the old path.
  • Small failure surface. Do fewer things, but do them completely. Error boundaries and validation make a simple system trustworthy.
  • Flat over nested. If logic is buried three or more levels deep, flatten it with guard clauses, early returns, or clearer ownership.

Fix From The Root

When a bug or bad behavior appears, do not patch only where the symptom appears. Step back and ask:

  1. Why did this happen?
  2. Is this a design flaw, a responsibility in the wrong place, or a missing boundary?
  3. Can the fix make the architecture smaller or clearer?

If the problem is architectural, fix the architecture. Patching symptoms leads to repeated patches; fixing structure reduces future bugs.

Reduce Before Adding

After a codebase reaches meaningful complexity, the right move is often to reduce code rather than add code.

  • For bug fixes, the fix should ideally make the code shorter or clearer.
  • For enhancements, simplify the existing path first, then add the smallest necessary behavior.
  • For refactors, the result should usually have fewer concepts, fewer branches, or clearer ownership.

Adding substantial code is justified for genuinely new functionality, but even then look for what can be removed or replaced first.

Dependency And Abstraction Discipline

  • Do not pull in a library for something that is straightforward local code.
  • Do not create base classes, interfaces, factories, or generic helpers for one implementation.
  • Do not add wrapper layers around libraries unless there is a real boundary to isolate.
  • Do not add logging, metrics, retry logic, caching, or toggles unless they solve the current problem.
  • Prefer direct imports over barrel files that only re-export.

Code Hygiene

  • No commented-out code.
  • No unused parameters, options, types, helpers, or files.
  • No types or interfaces that mirror data one-to-one without adding constraints.
  • If a function takes more than four parameters, check whether it is doing too much.
  • If a file is large because it mixes concerns, split by ownership rather than by arbitrary helper categories.
  • If a function needs a comment to explain what it does, prefer a clearer name or smaller function.
  • No abbreviations unless they are universal, such as id, url, or db.

Before Finishing

Ask:

  1. Did I add code that could have been avoided by removing or simplifying something?
  2. Is there exactly one code path for the changed behavior?
  3. Can someone read the change top-to-bottom without bouncing through unrelated files?
  4. If I delete any piece of what I added, does something visibly break?
  5. Am I fixing the root cause or only a symptom?

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.