website/src/content/posts/2026-01-21-shipping-great-skills-mcp-and-docs-with-as-little-effort-as-possible/page.mdx
TODO: importance of docs with LLMs
In 2026, an "AI native" startup is responsible for:
That's a lot of markdown. This is what I call "docs sprawl," where you have so much documentation that needs to be kept up to date that it takes more work to maintain good docs than it is to actually build your product.
I hear a lot of developers saying "I can just vibe code that," but this has 2 problems in reality:
This is probably obvious to you already.
If you're like me, you'll find your docs actually get better for humans too once you start writing them like you're writing prompts for an LLM. You naturally become more precise in your language and rely heavier on code snippets.
You already follow DRY (Don't Repeat Yourself) in your code, your docs are the same way.
Pick a source of truth of where you'll maintain the best possible docs reviewed by real humans and with a high scrutiny for issues. This will be reuused for your
Fortunately, every major framework and docs provider provides ways of reusing code snippets in different places -- including Next.js, Mintlify, Starlight, and Fumadocs. They all provide some sort of "component" concept that lets you write docs once and reuse it where you see fit.
For example, we use components heavily for:
Most modern skills are built with a "main" skill that acts as a router and a bunch of markdown files.
For example:
rivetkit-typescript/
SKILL.md # Includes overview of the code functionality and a table of content of docs reference/ # Includes rendered Markdown version of your docs
actors-quickstart-backend.md
actors-quickstart-react.md
actors-quickstart-next-js.md
actors-actions.md
actors-lifecycle.md
...etc...
We have significantly more docs than most companies, so our docs are opt-in as skills. A lot of docs files are not helpful for an agent working with RivetKit, so our docs frontmatter lets us define skill=true|false for wether or not it's auto-generated.
Skills have a main SKILL.md file that gets loaded by the agent when needed. This skill file should serve two purposes:
reference/ folder)Our main skill's structure looks like this:
reference/ folder. This is often enough for 80% of use cases, but also acts as a router to get more information about these APIs.This is heavily inspired by TODO (vercel react) and TODO (cloudflare skill).
Within the last few months, all major agents have added support for Language Server Protocols. This is the same technology that your editor uses to show you intellisense and inline docs.
This means that when an agent is reading code using your library, it's also reading your doc comments. Don't neglect them, they're very helpful in larger codebases.
One thing we hope to try soon is to link to our skills from within doc comments so agents know where to go to learn how to use an API in practice.
It's plainly obvious that the description on your skill is important for the agent to know when to integrate it. It's the only thing that the agent loads in to context in order to determine if it should load your skill.
Good skill descirptions explain what the skill is and (more importantly) what situations to trigger it.
What's less obvious is that some users may have only your MCP and not your skill file, so you need to write your MCP server's descirptions more like a skill file.
Bad
A lot of MCP servers I've seen just explain what the tool does
For example:
Searches the docs for My Cool Library.
Users will need to explicitly specify to use My Cool Library every time they want to call that tool in a new module or project.
Good
In reality, you should write descirptions more like a skill:
Searches the docs for My Cool Library. Call in situations when writing code related to A, B, or C.
This helps the agent better understand that My Cool Library does A, B, and C. When building new modules or projects, it knows to check if My Cool Library can help.
Codex has the lowest limit of 500 characters on your skill description.
We're on Astro because we do a lot of highly customized things on our website. Most of what I've described here comes out of the box with Mintlify. Don't overthink it, just start with Mintlify. They're awesome.
I've heard good things about Fumadocs too, but have not tried them. Also worth a shot.
TODO
TODO
TODO