legible-code

My subjective take on habitable code, for both humans and AI. Distilled from personal experience and the collected wisdom of practitioners I trust. Packaged as an Agent Skill that lets coding agents provide narrative commentary and structural design improvements for AI-generated code.

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 — un-braided, where each strand of concern runs cleanly alongside the others rather than woven through them.

The premise is that legibility is not a surface property fixed by formatting or naming, but a structural one. 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 test, or hard to change, it is usually because one of these structural conditions has broken down — not because of local mess.

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

When to use

• Reviewing a PR for structural quality, not just correctness
• Planning a refactor and deciding where to split or merge code
• Designing a new module’s seams and vocabulary
• The user describes code as “tangled,” “hard to follow,” “hard to test,” or “hard to change”

This skill does not trigger for greenfield “write me a function” tasks, bug fixes with a clear local cause, formatting/lint, or pure performance work.

Install

Using the skills CLI:

npx skills add jasim/legible-code

Or for a specific agent:

npx skills add jasim/legible-code --agent claude-code

Structure

legible-code/
├── SKILL.md               # Frontmatter + the diagnostics
└── references/
    ├── F1-narrative-clarity.md
    ├── F2-data-flow-pipelines.md
    ├── F3-functional-core-interpreter.md
    ├── F4-parse-dont-validate.md
    ├── F5-growing-a-language.md
    ├── F6-deep-modules.md
    ├── F7-cohesion-semantic-integrity.md
    ├── F8-cognitive-load.md
    ├── F9-type-centric-modularization.md
    ├── F10-single-point-of-knowledge.md
    ├── F11-lifted-invariants.md
    └── sources.md

The agent reads SKILL.md first, identifies which diagnostics fire, and loads only the matching reference files. Lower-numbered diagnostics are foundations; higher-numbered ones emerge from them. When several fire, address the foundation first. F10 (Scattered Knowledge) is cross-cutting.

License

MIT — see LICENSE.