Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Add a docs skill (#5175)

nate nowack9c35c017cd89
diff --git a/.agents/skills/docs/SKILL.md b/.agents/skills/docs/SKILL.md
new file mode 100644
index 000000000..d6cfa15b8
--- /dev/null
+++ b/.agents/skills/docs/SKILL.md
@@ -0,0 +1,83 @@
+---
+name: docs
+description: Write or revise a page under docs/ for gofastmcp.com. Use when adding a feature's documentation, fixing a docs issue, reworking a page, or auditing pages for accessibility and consistency. Covers the page shape, the voice, the checks that run in CI, and how a merged page reaches the live site.
+---
+
+# FastMCP docs
+
+The docs are a Mintlify site built from `docs/`. A page exists only when `docs/docs.json` lists it, and a feature exists only when a page documents it. `docs/python-sdk/**` is generated from docstrings by a bot; edit the docstring, not the page.
+
+## Procedure
+
+1. Find the owning page before creating one. `rg -l "<feature>" docs --glob '!docs/python-sdk/**' --glob '!docs/v2/**' --glob '!docs/v3/**'`. Extend it when the feature belongs to that page's subject; add a page when it has its own.
+2. Read two neighboring pages in the same `docs.json` group and match their section order and heading depth.
+3. Write the page with the template below. Explain why the feature exists before showing how, and keep the first code block small enough to read without scrolling.
+4. Make every code block runnable: imports present, names defined, one idea per block. Pull intermediate values into named variables instead of nesting calls.
+5. Run the checks in **Verify** and fix what they report.
+6. When the change is ready to ship, open a PR against `main`. Merged is not live: the site serves `published-docs`. A stable release from `main` opens a `Publish FastMCP v<version> docs` PR against `published-docs` that a maintainer merges; for a docs-only change between releases, follow "Publishing docs by hand" in `.agents/skills/release/SKILL.md`. Either way, the `Deploy docs` run's verdict is what says the site changed.
+
+## Template
+
+````mdx
+---
+title: Feature Name
+sidebarTitle: Feature
+description: One sentence a search result can show.
+icon: some-fontawesome-icon
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="<version that introduces the feature>" />
+
+One paragraph on the problem this solves and when to reach for it.
+
+## Basic usage
+
+Explain what the example does, then show it.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Demo")
+
+
+def greet(name: str) -> str:
+ return f"Hello, {name}!"
+```
+
+## Configuration
+
+One subsection per option that changes behavior, each with a sentence on the default and an example of the override.
+
+## How it works
+
+Only when the mechanism affects what the reader should do. Put a one-sentence text description before any diagram.
+````
+
+## Voice
+
+Second person, present tense, plain assertions. Say what the feature does and what the reader should do; leave out marketing adjectives and reassurance. The first sentence of each section carries its point. Prose holds the important information; code comments hold none of it. Wrap bare `{}` in backticks, since Mintlify reads them as JSX.
+
+## Accessibility
+
+Every `<img>` and `![]()` gets alt text that says what the picture shows. Decorative media gets `aria-hidden="true"`. Headings step one level at a time. Link text names the destination. Tables have a header row. Code fences carry a language. Diagrams get a text description. Custom CSS keeps text at 4.5:1 contrast and animations behind `prefers-reduced-motion`.
+
+## Verify
+
+```bash
+(cd docs && npx --yes mint@latest broken-links)
+uv run pytest tests/docs -n 0
+```
+
+The first catches dead links and MDX parse errors and names the file and line. The second parses every Python block in `docs/` and resolves every `fastmcp` import. A block that must not run takes `test="skip"` on its fence.
+
+For a visual change, run `npx --yes mint@latest dev` in `docs/` and look at the page at 1280px and 390px, light and dark.
+
+## Gotchas
+
+- `VersionBadge` marks when a feature arrived. Leave old badges alone; they are history, not staleness.
+- `docs/v2/` and `docs/v3/` are frozen snapshots of earlier majors. Maintenance releases add changelog entries there and nothing else.
+- The version picker label lives in `docs/docs.json` under `navigation.versions[0].version` and is bumped by hand.
+- `mcp_types` is the real name of the protocol types package in 4.x.
diff --git a/.claude/skills/docs b/.claude/skills/docs
new file mode 120000
index 000000000..a0b6746b3
--- /dev/null
+++ b/.claude/skills/docs
@@ -0,0 +1 @@
+../../.agents/skills/docs
\ No newline at end of file