agentleFS
mannobeatsmannobeats/hyper-taste/skills/build/SKILL.md

build

Skill1 starsChanged 4 days agoMITView on GitHub

How to write code in any project so it stays one coherent system - read the code first, reuse what exists, build in thin tested slices, check the official docs, and finish every part a change touches. Use when implementing a feature or story, fixing a bug, adding an API, or choosing a library or dependency.

167 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use backprop, finances 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.
  • JuliusBrusseeSkill

    backprop

    Bug → spec protocol. When a bug is found or a test fails, trace the cause, decide whether a new §V invariant would catch recurrence, append to §B. This is the one non-obvious thing SDD does that plan-then-execute doesn't. Triggers on test failure, bug report, post-mortem, or explicit user ask.

    Also in 4 projects that use this

  • GerardoRdz96Skill

    finances

    Use when Gera talks about his money — logging an expense ("I spent X on Y"), checking where he stands this pay-period, closing a period, planning debt payoff, onboarding his financial picture, or asking for budgeting/finance opinions. Servy's financial brain. Triggers — "I spent", "log this expense", "where am I this period", "close the period", "how's my budget", "debt plan", "should I pay off", "finances onboard", "/finances".

    Also in 3 projects that use this

  • cpiprintSkill

    favicon

    Generate favicons from a source image

    Also in 3 projects that use this

  • madeehahassanSkill

    Go-Live

    Pre-launch checklist. Use before making any app public, sharing a link externally, or announcing a product launch. Adapts to Claude Code, claude.ai, and Cowork.

    Also in 3 projects that use this

  • JuliusBrusseeSkill

    deepen

    Optional design-improvement pass for when you have spare usage to drain. Finds the shallowest modules in the code the spec touches, researches a deeper design, and proposes refactors that shrink interfaces and hide decisions — behavior held constant, tests green before and after. Proposes §I/§V/§T edits, never silent rewrites. Triggers when the user says "deepen this", "improve the design", "this module feels shallow", "pull complexity down", "use spare budget on the codebase", or invokes /ck:deepen. Leans on the codebase-design skill's deep-module vocabulary when present.

    Also in 3 projects that use this

  • synaptiaiSkill

    gate

    Create a BDSK review_gate artifact. Defines a checkpoint that controls whether generated output may proceed toward acceptance. Use when defining quality, security, or scope gates for execution plans.

    Also in 5 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. 0 are common, 11 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 153 edited versions we read keep these.

  • 11

    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:

    Read the task and the code it touches, then trace the real flow end to end: where data comes in, where it is stored, what reads it.

    line 15
  2. Very specific:

    Read the project's AGENTS.md, CONSTRAINTS.md, DESIGN-SYSTEM.md and the story.

    line 17
  3. Distinctive:

    Search before you write. Take the first option that fully works:

    line 24
  4. Distinctive:

    Use it the way the surrounding code does.

    line 27
  5. Distinctive:

    The standard library or the platform?: Use it, unless the project has its own wrapper.

    line 31
  6. Distinctive:

    An installed dependency?: Use it. Add a new dependency only when it does real work a few lines can't, and say why.

    line 32
  7. Distinctive:

    When you do add something reusable, put it where the next person will look for it, and make the old ad-hoc copies use it.

    line 36
  8. Distinctive:

    No abstraction nobody needs: no interface with one implementation, no factory for one product, no wrapper that only passes calls through, …

    line 43
  9. Distinctive:

    Test first, from the spec, not from the code: Write the test from the story's acceptance lines (or the bug report) before the …

    line 56
  10. Very specific:

    Run the whole relevant suite, the type checker and the linter.

    line 65
  11. Distinctive:

    Commit with a message that says what someone can now do.

    line 67
  12. Distinctive:

    Never leave the codebase broken between slices.

    line 69
  13. Distinctive:

    Every place on the scope list is updated, and the tests, types and linter pass.

    line 117

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

Build

The outcome: code that looks like one careful person wrote the whole codebase. Every rule lives in one place, every helper exists once, every change is complete and proven. Agents fail the other way: they write a second version of what already exists, stop at the file they were asked about, and call it done because it compiles.

1. Read before you write

  • Read the task and the code it touches, then trace the real flow end to end: where data comes in, where it is stored, what reads it.
  • Read the project's AGENTS.md, CONSTRAINTS.md, DESIGN-SYSTEM.md and the story. They win over your habits.
  • List every place the change must reach: callers, tests, fixtures, types, config, exports, docs. That list is the scope. Features nobody asked for are not.

2. Reuse before you add

Search before you write. Take the first option that fully works:

  1. Already in this codebase? A helper, component, hook, service, type, token or pattern. Use it the way the surrounding code does. Writing a second one is the most common way agents turn code into spaghetti.
  2. Almost in the codebase? Extend the existing piece so both callers share it, instead of copying it. Two near-copies that must change together become one.
  3. The standard library or the platform? Use it, unless the project has its own wrapper.
  4. An installed dependency? Use it. Add a new dependency only when it does real work a few lines can't, and say why.
  5. Only then: new code, in the project's existing structure, layers and naming.

When you do add something reusable, put it where the next person will look for it, and make the old ad-hoc copies use it.

3. Keep it one system

  • One home per rule. A business rule, a format, a magic number or a style lives in one place and everything else refers to it.
  • No abstraction nobody needs: no interface with one implementation, no factory for one product, no wrapper that only passes calls through, no option or config for a value that never changes, no "for later" scaffolding. Abstractions come from the second real caller.
  • Consistent everywhere: the same thing has the same name, the same shape and the same error handling in every file. Follow the codebase's conventions even where you'd choose otherwise.
  • Simple, not lazy: the shortest correct solution, once you know everything it must touch. A clever one-liner that needs decoding is not simple.
  • Comments say why, in one line, only where the code can't.

4. Build in thin slices

Each slice goes through every layer it needs (data, logic, UI) and works on its own:

  1. Test first, from the spec, not from the code. Write the test from the story's acceptance lines (or the bug report) before the implementation exists, and run it: it must fail, for the reason you expect. A test written after the code tends to describe what the code does, bugs included, and passes anyway. Logic, parsers, money, security, data writes and every bug fix get one; trivial changes and pure layout don't (those are proven by looking).
  2. Make it pass with the simplest code that fits the system. Never change a test to match the code; change it only when the spec changed, and say so.
  3. Check the test can catch a bug: break the line it guards for a moment (flip a condition, return early) and see it fail. A test that still passes proves nothing.
  4. Run the whole relevant suite, the type checker and the linter. Then look at the running result if the slice has UI (ui-director, mac-app).
  5. Commit with a message that says what someone can now do.

Never leave the codebase broken between slices. If a slice grows past what you can verify in one go, split it.

5. Ground it in the docs

APIs change. Before you use a framework feature, a config key or a library call you are not sure about, read the official docs or the installed version's source, and use what they say for the version this project has. Say which source you used when it matters. Never invent an API.

6. Prove every claim

Say only what you checked, and show how you know. Agents that read a doc, guess, or skim one file and then report "done" or "this works" are the most expensive failure there is.

  • About the code: you read it in this session. Cite file:line. Never describe code, an API or a config from memory or from a README when the source is there to read.
  • About behavior: you ran it. Quote the command and the decisive line of its output (the test summary, the error, the response), or point to the screenshot you looked at.
  • About a library or platform: the official docs or the installed version's source, named.
  • Real problems only: a risk you can't show with a case, a failing check or a source is not a problem; don't add work for it. When the change is ready, say so.
  • Unknown stays unknown: "I didn't run the migration", "not checked on a real phone". A gap you name is fine; a gap you hide is a bug.
  • Before "done": re-read the diff end to end, and re-run what proves it after the last edit, not before it.

7. Design interfaces on purpose

For an API, a module boundary or a component's props: design the contract before the code. Name things for what they mean to the caller, keep inputs and outputs small, validate at the boundary, return errors the caller can act on, and keep it stable once others use it (add, don't break). Expect callers to depend on everything observable, not only what you documented.

8. Finish the change

  • Every caller: grep every use of what you changed, and update each one. A bug fix goes in the shared code, once, not in the one caller the report named.
  • Every test, fixture and type your change breaks is fixed, not skipped or deleted.
  • Code you move keeps its validation, error handling and edge cases.
  • Never cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, anything the user asked for.
  • A known limit gets a one-line comment: limit: <what>, <when to revisit>.

Restructuring or cleaning up code that already works is refactor.

Done when

  • You searched before writing, and nothing new duplicates something that existed.
  • Every place on the scope list is updated, and the tests, types and linter pass.
  • Each new test failed before the code and passes after; the full suite, types and linter pass.
  • The change was seen working (tests, and the running app for anything visible).
  • Your report cites the evidence (file:line, command output, screenshots) for every claim, and names what you did not check.
  • Each slice is its own commit, and anything you couldn't check is named in your report.

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.