---
author: nathan-flurry
published: "2026-01-22"
category: technical
keywords: ["mcp","skills","agents","docs","markdown"]
title: "Shipping great skills, MCP, and docs with as little effort as possible"
description: "TODO: avoid docs sprawl"
unpublished: true
---

TODO: importance of docs with LLMs

## Docs sprawl

In 2026, an "AI native" startup is responsible for:

- Documentation
- MCP server (bare minimum for docs)
- Skill files
- llms.txt (though not widely adopted)
- Inline doc comments (for LSPs)

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.

## Tip 1: Do not try to vibe code your way out of docs sprawl

I hear a lot of developers saying "I can just vibe code that," but this has 2 problems in reality:

1. **Writing is easy, reviewing is hard**: The reality is that LLMs, no matter how smart, make a ton of mistakes. Just like humans. There's a lot of code where "does it work -> ship it" mentality works, but documentation is not one of those cases. Unfortunately, it's vital that humans review the output is correct -- especially since there's not much you can do to deterministically build a feedback loop of if documentation is correct. It's very subjective.
2. **The more you write, the harder it is to udpate**: As you make changes to your product, you need to update your docs accordingly. Event with LLMs, it takes a _lot time_ to read all of the docs for a company and review if it works. Every small change in your code will require oodles of tokens just to make sure your docs are up to date.

## Tip 2: Write docs for LLMs, not humans

This is probably obvious to you already.

- **Be precise**: Assume a machine is reading your docs and will execute your every request precisely as you stated.
- **Be brief**: The most important scarcity in LLMs is tokens. Write less, you probably don't need that bloat. Humans reading your docs will probably thank you for not writing walls of text regardless.
- **Use more code examples**: Agents understand code better than plain English. Much like a well written skill file, write lots of code snippets with comments for agents to understand instead of plain english. Plain English is vague and verbose.

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.

## Tip 3: DRY docs & components

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:

- Getting started guides that share common steps
- Next steps sections where there's a common set of next steps
- NPM install instructions that requires all package providers

## Tip 4: Ship your docs with your skill

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.

## Tip 5: A good SKILL.md is a router & a cheatsheet

Skills have a main `SKILL.md` file that gets loaded by the agent when needed. This skill file should serve two purposes:

- **Quick reference**: Provide short code snippets for the agent to unsterstand the basics of how to use your library
- **Router**: Provide information on where to look next for more information (in this case, the `reference/` folder)

Our main skill's structure looks like this:

- **MCP Server**: Recommend installing our MCP server & encourage docs search
- **First steps**: The first steps an agent should follow when building a workflow for the first time. This tells the agent how to start a new project.
- **Minimal project**: Provide code snippets for the agent to build a bare minimum project. This makes it really easy for the agent to not have to piece together a lot of other context to get started.
- **Quick Reference**: Provide code snippets for how to use the most common library features with links to more docs. This acts as a router for the basic features.
- **Reference Map**: Auto-generated list of all files in the `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).

## Tip 5: Agents have LSPs now, use your doc comments

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.

## Tip 6: You might want to make your MCP descirptions more like your skill descirption

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.

## Tip 7: Your skill descirption limit is 500 characters

Codex has the lowest limit of 500 characters on your skill description.

## Tip 8: Just use Mintlify

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.

## Tip 9: Type check your docs

TODO

## Tip 10: Tell your agent to get help

TODO

## Tip 11: Replace your CTA with your add skill

- You have so much more control over the user's integration flow than you can with any GUI since you have the context of your codebase

## Tip 12: Allow your skill to cite sources with links to docs

TODO

## Tip 13: Make your skill description precise, opt to ship more separate skills

- could not get claude to trigger our descriptoin
- it's becuaase we listed what rivet is good at so it was super broad, we needed it to be much more scoped
- opt to ship multiple individual skills
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use?utm_source=chatgpt.com#best-practices-for-tool-definitions

## Tip 14: Include full code snippets

- Don't provide small code snippets
- Provide full snippets with imports and surring bloat
- Annoying to type, but prevents common errors with LLMs

## Resources

- Twitter video
- Anthropic skills
- Vercel skills.sh
- Vercel skills cli

