Self Documenting Code

This is a coding philosophy packaged as guidance for Claude. It pushes hard on making function names do the documentation work, splitting between "semantic" functions that are pure and reusable versus "pragmatic" ones that handle messy business logic. The models section is the strongest part, arguing that optional fields are technical debt and your types should make invalid states impossible. Brand types get a shoutout for preventing ID mixups. The advice is opinionated but practical, especially the warning about semantic functions slowly morphing into pragmatic ones because someone took a shortcut. Useful if you're trying to get Claude to write code that won't make you angry in six months.

skills.sh installs: 152
GitHub stars: 6
last updated: Jun 3, 2026

View on GitHub

Install

$ npx -y skills add theswerd/aicode --skill self-documenting-code --agent claude-code

Installs into .claude/skills of the current project.

Files

Code should be self documenting

How you split logic into functions and shape the data they pass around determines how well a codebase holds up over time.

Semantic Functions

Semantic functions are the building blocks of any codebase, a good semantic function should be as minimal as possible in order to prioritize correctness in it. A semantic function should take in all required inputs to complete its goal and return all necessary outputs directly. Semantic functions can wrap other semantic functions to describe desired flows and usage; as the building blocks of the codebase, if there are complex flows used everywhere that are well defined, use a semantic function to codify them.

SKILL.md on GitHub

Sponsors

Promote your product hereReach 125k+ visitors monthly Promote your product hereReach 125k+ visitors monthly