Legible Code: A personal distillation of collected wisdom

This is a set of ideas about how code should be written so it is habitable by humans and legible to AI. It is highly personal - drawn from practitioners, but filtered through my own experiences and taste. It is written as a guide for humans to read, and as a skill for AI coding agents to use.

The fastest way to understand them is to install this as a skill.

The skill: its installation, how it is useful, and how it is limited

You can install legible-code by using the skills CLI:

npx skills add jasim/legible-code

Then run it on your codebase, where likely due to LLM code generation, you no longer have a clear mental model of what is going on, and are unable to make progress.

Here is how I use this skill - when building software, I push vibe-coding aggressively, without regard to keeping a pristine codebase, nor a clear mental model. It goes on until it stops working. There will either be bugs that I can no longer fix using the LLM - because it goes in circles and tries progressively more inane things; or I’ve started stalling on building new features, because I no longer know how the puzzle would fit, since the pieces and the puzzle itself has become a strange fuzzy blob in my head.

This skill originated as a markdown file - LEGIBLE-CODE.md - that helped me push that point of breakage further away. I wrote down what good code meant to me, and then used it frequently as a review tool with coding agents. Whenever I create a plan for a large new feature, I’d ask Claude to critique it based on LEGIBLE-CODE.md. I would also do the same on large commits or files where things have turned gnarly. It is sort of like cleaning up the kitchen counter occasionally, just enough, to continue to be able to cook frantically.

I don’t make the claim that this skill will help stave off the inevitable degradation of LLM written codebases. It might - if the system you’re building is of low complexity. Regular web-apps for example will be quite fine. However, for anything that has many interlocking parts, invariants, or intricate branching — it can only help you go a bit further than otherwise.

How it helps

This skill is about making code more comprehensible — by ensuring it has a design: a coherence, a layering, a conceptual integrity. That it isn’t tangled or complected unnecessarily. That it is “simple” in Rich Hickey’s sense — unbraided, where each strand of concern runs cleanly alongside the others rather than woven through them.

When I say legibility, I mean it in a structural sense. A reader should be able to trace any event through the system as a single spine, see the shape of data at each stage, separate decisions from effects, and find a vocabulary that mirrors the domain rather than the machine. Module seams should hide design decisions, not process steps. Knowledge should live in one place, defined once, not enforced through repetition across many.

When code feels tangled, hard to understand, hard to test, or hard to change, it is usually because one of these structural conditions have broken down.

The skill walks an agent through different diagnostics covering these structural concerns — scattered narrative, invisible data flow, tangled I/O, missing domain vocabulary, wrong module seams, premature splitting or over-bundling, cognitive overload, the extract-function dead end, scattered knowledge, and re-litigated invariants — and loads the matching remedy from references/.

License

MIT — see LICENSE.