Unverified Commit fb0686d8 authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

Docs skills: guide and api-reference (#90992)

Writing skills for guides and API reference for more consistent
formatting.

- `write-guide` - this skill helps create guides with progressive
disclosure and a consistent format (intro, summary, step-by-step
instructions, next steps). Works best when you give agents a demo.
- `write-api-reference`  - this skill looks at the API type (component,
function, file, etc) and helps draft references following a consistent
format. Works best when you give agents context. e.g. source code, PR
descriptions, RFCs. Also explores repo context (e.g. e2e tests)


Note:

- While skills help you write a first draft, they’re 80%. Humans still
need to check for accuracy, test APIs, and take it to 110%.
- If no technical writing guidance is provided, skills work best when
you give it references of past work.

Closes:

- https://linear.app/vercel/issue/DOC-6245/create-guide-skill
- https://linear.app/vercel/issue/DOC-6246/create-api-reference-skill

---------
Co-authored-by: 's avatarvercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
parent 156307e3
---
name: write-api-reference
description: |
Produces API reference documentation for Next.js APIs: functions, components, file conventions, directives, and config options.
**Auto-activation:** User asks to write, create, or draft an API reference page. Also triggers on paths like `docs/01-app/03-api-reference/`, or keywords like "API reference", "props", "parameters", "returns", "signature".
**Input sources:** Next.js source code, existing API reference pages, or user-provided specifications.
**Output type:** A markdown (.mdx) API reference page with YAML frontmatter, usage example, reference section, behavior notes, and examples.
agent: Plan
context: fork
---
# Writing API Reference Pages
## Goal
Produce an API reference page that documents a single API surface (function, component, file convention, directive, or config option). The page should be concise, scannable, and example-driven.
Each page documents **one API**. If the API has sub-methods (like `cookies.set()`), document them on the same page. If two APIs are independent, they get separate pages.
## Structure
Identify which category the API belongs to, then follow the corresponding template.
### Categories
1. **Function** (`cookies`, `fetch`, `generateStaticParams`): signature, params/returns, methods table, examples
2. **Component** (`Link`, `Image`, `Script`): props summary table, individual prop docs, examples
3. **File convention** (`page`, `layout`, `route`): definition, code showing the convention, props, behavior, examples
4. **Directive** (`use client`, `use cache`): definition, usage, serialization/boundary rules, reference
5. **Config option** (`basePath`, `images`, etc.): definition, config code, behavioral sections
### Template
````markdown
---
title: {API name}
description: {API Reference for the {API name} {function|component|file convention|directive|config option}.}
---
{One sentence defining what it does and where it's used.}
```tsx filename="path/to/file.tsx" switcher
// Minimal working usage
```
```jsx filename="path/to/file.js" switcher
// Same example in JS
```
## Reference
{For functions: methods/params table, return type.}
{For components: props summary table, then `#### propName` subsections.}
{For file conventions: `### Props` with `#### propName` subsections.}
{For directives: usage rules and serialization constraints.}
{For config: options table or individual option docs.}
### {Subsection name}
{Description + code example + table of values where applicable.}
## Good to know
- {Default behavior or implicit effects.}
- {Caveats, limitations, or version-specific notes.}
- {Edge cases the developer should be aware of.}
## Examples
### {Example name}
{Brief context, 1-2 sentences.}
```tsx filename="path/to/file.tsx" switcher
// Complete working example
```
```jsx filename="path/to/file.js" switcher
// Same example in JS
```
## Version History
| Version | Changes |
| -------- | --------------- |
| `vX.Y.Z` | {What changed.} |
````
**Category-specific notes:**
- **Functions**: Lead with the function signature and `await` if async. Document methods in a table if the return value has methods (like `cookies`). Document options in a separate table if applicable.
- **Components**: Start with a props summary table (`| Prop | Example | Type | Required |`). Then document each prop under `#### propName` with description, code example, and value table where useful.
- **File conventions**: Show the default export signature with TypeScript types. Document each prop (`params`, `searchParams`, etc.) under `#### propName` with a route/URL/value example table.
- **Directives**: No `## Reference` section. Use `## Usage` instead, showing correct placement. Document serialization constraints and boundary rules.
- **Config options**: Show the `next.config.ts` snippet. Use subsections for each behavioral aspect.
## Rules
1. **Lead with what it does.** First sentence defines the API. No preamble.
2. **Show working code immediately.** A minimal usage example appears right after the opening sentence, before `## Reference`.
3. **Use `switcher` for tsx/jsx pairs.** Always include both. Always include `filename="path/to/file.ext"`.
4. **Use `highlight={n}` for key lines.** Highlight the line that demonstrates the API being documented.
5. **Tables for simple APIs, subsections for complex ones.** If a prop/param needs only a type and one-line description, use a table row. If it needs a code example or multiple values, use a `####` subsection.
6. **Behavior section uses `> **Good to know**:`or`## Good to know`.** Use the blockquote format for brief notes (1-3 bullets). Use the heading format for longer sections. Not "Note:" or "Warning:".
7. **Examples section uses `### Example Name` subsections.** Each example solves one specific use case.
8. **Version History table at the end.** Include when the API has changed across versions. Omit for new APIs.
9. **No em dashes.** Use periods, commas, or parentheses instead.
10. **Mechanical, observable language.** Describe what happens, not how it feels. "Returns an object" not "gives you an object".
11. **Link to related docs with relative paths.** Use `/docs/app/...` format.
12. **No selling or justifying.** No "powerful", "easily", "simply". State what the API does.
| Don't | Do |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| "This powerful function lets you easily manage cookies" | "`cookies` is an async function that reads HTTP request cookies in Server Components" |
| "You can conveniently access..." | "Returns an object containing..." |
| "The best way to handle navigation" | "`<Link>` extends the HTML `<a>` element to provide prefetching and client-side navigation" |
## Workflow
1. **Ask for reference material.** Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc.
2. **Identify the API category** (function, component, file convention, directive, config).
3. **Research the implementation.** Read the source code to understand params, return types, edge cases, and defaults.
4. **Check e2e tests.** Search `test/` for tests exercising the API to find real usage patterns, edge cases, and expected behavior.
5. **Check existing related docs** for linking opportunities and to avoid duplication.
6. **Write using the appropriate category template.** Follow the rules above.
7. **Review against the rules.** Verify: one sentence opener, immediate code example, correct `switcher`/`filename` usage, tables vs subsections, "Good to know" format, no em dashes, mechanical language.
## References
Read these pages in `docs/01-app/03-api-reference/` before writing. They demonstrate the patterns above.
- `04-functions/cookies.mdx` - Function with methods table, options table, and behavior notes
- `03-file-conventions/page.mdx` - File convention with props subsections and route/URL/value tables
- `02-components/link.mdx` - Component with props summary table and detailed per-prop docs
- `01-directives/use-client.mdx` - Directive with usage section and serialization rules
- `04-functions/fetch.mdx` - Function with troubleshooting section and version history
---
name: write-guide
description: |
Generates technical guides that teach real-world use cases through progressive examples.
**Auto-activation:** User asks to write, create, or draft a guide or tutorial. Also use when converting feature documentation, API references, or skill knowledge into step-by-step learning content.
**Input sources:** Feature skills, API documentation, existing code examples, or user-provided specifications.
**Output type:** A markdown guide with YAML frontmatter, introduction, 2-4 progressive steps, and next steps section.
agent: Plan
context: fork
---
# Writing Guides
## Goal
Produce a technical guide that teaches a real-world use case through progressive examples. Concepts are introduced only when the reader needs them.
Each guide solves **one specific problem**. Not a category of problems. If the outline has 5+ steps or covers multiple approaches, split it.
## Structure
Every guide follows this arc: introduction, example setup, 2-5 progressive steps, next steps.
Each step follows this loop: working code → new requirement → friction → explanation → resolution → observable proof.
Sections: introduction (no heading, 2 paragraphs max), `## Example` (what we're building + source link), `### Step N` (action-oriented titles, 2-4 steps), `## Next steps` (summary + related links).
Headings should tell a story on their own. If readers only saw the headings, they'd understand the guide's takeaway.
### Template
````markdown
---
title: {Action-oriented, e.g., "Building X" or "How to Y"}
description: {One sentence}
nav_title: {Short title for navigation}
---
{What the reader will accomplish and why it matters. The friction and how this approach resolves it. 2 paragraphs max.}
## Example
As an example, we'll build {what we're building}.
We'll start with {step 1}, then {step 2}, and {step 3}.
{Source code link.}
### Step 1: {Action-oriented title}
{Brief context, 1-2 sentences.}
```tsx filename="path/to/file.tsx"
// Minimal working code
```
{Explain what happens.}
{Introduce friction: warning, limitation, or constraint.}
{Resolution: explain the choice, apply the fix.}
{Verify the fix with observable proof.}
### Step 2: {Action-oriented title}
{Same pattern: context → code → explain → friction → resolution → proof.}
### Step 3: {Action-oriented title}
{Same pattern.}
## Next steps
You now know how to {summary}.
Next, learn how to:
- [Related guide 1]()
- [Related guide 2]()
````
### Workflow
1. **Research**: Check available skills for relevant features. Read existing docs for context and linking opportunities.
2. **Plan**: Outline sections. Verify scope (one problem, 2-4 steps). Each step needs a friction point and resolution.
3. **Write**: Follow the template above. Apply the rules below.
4. **Review**: Re-read the rules, verify, then present.
## Rules
1. **Progressive disclosure.** Start with the smallest working example. Introduce complexity only when the example breaks. Name concepts at the moment of resolution, after the reader has felt the problem. Full loop: working → new requirement → something breaks → explain why → name the fix → apply → verify with proof → move on.
2. **Show problems visually.** Console errors, terminal output, build warnings, slow-loading pages. "If we refresh the page, we can see the component blocks the response."
3. **Verify resolutions with observable proof.** Before/after comparisons, browser reloads, terminal output. "If we refresh the page again, we can see it loads instantly."
4. **One friction point per step.** If a step has multiple friction points, split it.
5. **Minimal code blocks.** Only the code needed for the current step. Collapse unchanged functions with `function Header() {}`.
6. **No em dashes.** Use periods, commas, or parentheses instead.
7. **Mechanical, observable language.** Describe what happens, not how it feels.
8. **No selling, justifying, or comparing.** No "the best way," no historical context, no framework comparisons.
| Don't | Do |
| ---------------------------------------------------- | -------------------------------------------------------- |
| "creates friction in the pipeline" | "blocks the response" |
| "needs dynamic information" | "depends on request-time data" |
| "requires dynamic processing" | "output can't be known ahead of time" |
| "The component blocks the response — causing delays" | "The component blocks the response. This causes delays." |
## References
Read these guides in `docs/01-app/02-guides/` before writing. They demonstrate the patterns above.
- `public-static-pages.mdx` — intro → example → 3 progressive steps → next steps. Concepts named at point of resolution. Problems shown with build output.
- `forms.mdx` — progressive feature building without explicit "Step" labels. Each section adds one capability.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment