Why encoding codebase patterns as AI instructions works better than writing docs nobody reads.
Every developer knows the documentation parado...
For further actions, you may consider blocking this person and/or reporting abuse
While I do agree with most of the content of the post. I do think skills are not meant as documentation.
The example of point 4 in the "Why it works better" section seems like a waste of tokens.
A simple line making using Inngest required is enough.
The documentation about the choice I would put in a docs/tools.md file.
The LLM does nothing with that explanation.
While I think using markdown files that are read by LLM's can be a part of the documentation.
There will still be a part of the project that is going to need human specific documentation. I'm thinking about architectural choices, onboarding, tool choices. And there are probably more reasons.
At the moment I'm working on an experiment where I'm using markdown files to describe module functionality, so that I can let a coding agent can generate the code based on staged git changes.
That way the documentation and prompts can be saved at the same time as the code changes.
I will create a post after I ended the experiment.
This is so relatable. We went through the same thing at work where nobody actually read the docs wiki, but once we started encoding the patterns directly into CLAUDE.md files the consistency went way up almost overnight. The biggest win for us was not having to repeat ourselves in code reviews anymore since Claude just follows the patterns now.
Do you version control your skills separately or just keep them in the main repo?
Keep them in the same repo! But some skills make more sense to keep as user scope, not project scope
It may be of interest to you and others that, instead focusing prompts/ skills, I'm developing the underlying framework AI builds with to defend against it doing things it shouldn't for a given task. So far it seems like a much more effective strategy than composing skills and instructions. What I've found is that AI can be very unpredictable regardless of the information you feed it, It certainly doesn't do the exact same thing twice, so I would say skills alone aren't that helpful when it comes to achieving consistent, predictable outcomes!
Great read. Documentation often becomes outdated quickly, so using AI to surface the right knowledge at the right time makes a lot of sense.
I have been doing something similar with structured Markdown docs in CLAUDE.md and a docs/ directory that Claude uses as context (with a CLAUDE.md file serving as an index to these docs). These docs are a direct mapping of our monorepo packages. Same idea, different mechanism. Going to try the skills approach after reading this.
We also combined the docs with a complementary layer: a custom ESLint plugin with rules that enforce the same patterns described in the docs. The two together work differently than either alone.
Docs tell Claude what to do. The linter catches violations regardless of whether the docs were consulted.
We use atomic design (composing UI into atoms, molecules, organisms, and templates, each built on top of the others). We have rules like no-raw-dom-elements (blocks raw html elements in favor of design system components), and template-no-hooks (templates are pure functions, no useState or useEffect allowed). The pre-commit hook runs ESLint on every staged .ts/.tsx file and blocks on any error.
Curious whether skills reduce that context pressure problem compared to full docs. That's probably the thing I'm most interested in testing.
Thank you for sharing this.
The core insight here is dead-on: documentation written for humans fails because humans are unreliable readers, but AI consumes everything you give it. Once you internalize that, encoding your conventions as machine-readable skills becomes obvious.
That's one of the things I’ve been thinking about over the last few months: do we really need documentation at all? Well, sure, at least for AI so they can answer questions. Do developers read documentation now, or do they just go straight to their favorite chatbot and ask, "How to set up RabbitMQ?" If that's the case, it makes sense to have AI generate documentation for AI.
The "guaranteed consumption" point is the killer insight here. Human devs skim docs, Claude reads everything. I hit the same realization but ended up going one layer deeper.
Instead of encoding patterns directly into skills, I structure the specifications themselves as Markdown files with YAML frontmatter — status, unique IDs, parent references — in a directory tree mirroring the feature hierarchy. Then .claude/rules/ files teach Claude how to navigate and work with that spec tree. The skills describe the structure, not the content, so when requirements change I update one spec file and the rules stay the same.
That separation solved the maintenance problem you mention toward the end. Skills that encode domain details drift when the domain changes. Skills that describe conventions rarely need updating.
I wrote about the .claude/rules/ setup in more detail here: dev.to/thlandgraf/how-i-use-claude...
I'm building a VS Code extension called SPECLAN around this approach (creator, full disclosure). But the two-layer pattern — structured specs as source of truth, plus rules that teach the agent the structure — works without the extension too.
Nice, this is exactly what I was looking for but didn't know it exists. Thanks for sharing this!
Interesting approach. Replacing traditional docs with AI-assisted workflows could really change how teams onboard and find information.
Fantastic article - this is among my favorite "AI coding" articles that I've come across until now, because it looks very practically applicable - keen to try it out!