write-api-reference

Name: write-api-reference
Author: vercel

141kstars31kforks

How to install write-api-reference?

vercel/next.js/write-api-reference

$npx -y skills add vercel/next.js --skill write-api-reference

Installs into the current project.

Summary

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 keyword

Files · 1

View on GitHub

SKILL.md

1	# Writing API Reference Pages
2
3	## Goal
4
5	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.
6
7	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.
8
9	## Structure
10
11	Identify which category the API belongs to, then follow the corresponding template.
12
13	### Categories
14
15	1. Function (`cookies`, `fetch`, `generateStaticParams`): signature, params/returns, methods table, examples
16	2. Component (`Link`, `Image`, `Script`): props summary table, individual prop docs, examples
17	3. File convention (`page`, `layout`, `route`): definition, code showing the convention, props, behavior, examples
18	4. Directive (`use client`, `use cache`): definition, usage, serialization/boundary rules, reference
19	5. Config option (`basePath`, `images`, etc.): definition, config code, behavioral sections
20
21	### Template
22
23	````markdown
24	---
25	title: {API name}
26	description: {API Reference for the {API name} {function\|component\|file convention\|directive\|config option}.}
27	---
28
29	{One sentence defining what it does and where it's used.}
30
31	```tsx filename="path/to/file.tsx" switcher
32	// Minimal working usage
33	```
34
35	```jsx filename="path/to/file.js" switcher
36	// Same example in JS
37	```
38
39	## Reference
40
41	{For functions: methods/params table, return type.}
42	{For components: props summary table, then `#### propName` subsections.}
43	{For file conventions: `### Props` with `#### propName` subsections.}
44	{For directives: usage rules and serialization constraints.}
45	{For config: options table or individual option docs.}
46
47	### {Subsection name}
48
49	{Description + code example + table of values where applicable.}
50
51	## Good to know
52
53	- {Default behavior or implicit effects.}
54	- {Caveats, limitations, or version-specific notes.}
55	- {Edge cases the developer should be aware of.}
56
57	## Examples
58
59	### {Example name}
60
61	{Brief context, 1-2 sentences.}
62
63	```tsx filename="path/to/file.tsx" switcher
64	// Complete working example
65	```
66
67	```jsx filename="path/to/file.js" switcher
68	// Same example in JS
69	```
70
71	## Version History
72
73	\| Version \| Changes \|
74	\| -------- \| --------------- \|
75	\| `vX.Y.Z` \| {What changed.} \|
76	````
77
78	Category-specific notes:
79
80	- 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.
81	- 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.
82	- 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.
83	- Directives: No `## Reference` section. Use `## Usage` instead, showing correct placement. Document serialization constraints and boundary rules.
84	- Config options: Show the `next.config.ts` snippet. Use subsections for each behavioral aspect.
85
86	## Rules
87
88	1. Lead with what it does. First sentence defines the API. No preamble.
89	2. Show working code immediately. A minimal usage example appears right after the opening sentence, before `## Reference`.
90	3. Use `switcher` for tsx/jsx pairs. Always include both. Always include `filename="path/to/file.ext"`.
91	4. Use `highlight={n}` for key lines. Highlight the line that demonstrates the API being documented.
92	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.
93	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:".
94	7. Examples section uses `### Example Name` subsections. Each example solves one specific use case.
95	8. Version History table at the end. Include when the API has changed across versions. Omit for new APIs.
96	9. No em dashes. Use periods,

People who liked this also viewed

6 picks

Type

write-api-reference

141kstars31kforks

View on GitHub

How to install write-api-reference?

vercel/next.js/write-api-reference

$npx -y skills add vercel/next.js --skill write-api-reference

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Writing API Reference Pages
2
3	## Goal
4
5	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.
6
7	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.
8
9	## Structure
10
11	Identify which category the API belongs to, then follow the corresponding template.
12
13	### Categories
14
15	1. Function (`cookies`, `fetch`, `generateStaticParams`): signature, params/returns, methods table, examples
16	2. Component (`Link`, `Image`, `Script`): props summary table, individual prop docs, examples
17	3. File convention (`page`, `layout`, `route`): definition, code showing the convention, props, behavior, examples
18	4. Directive (`use client`, `use cache`): definition, usage, serialization/boundary rules, reference
19	5. Config option (`basePath`, `images`, etc.): definition, config code, behavioral sections
20
21	### Template
22
23	````markdown
24	---
25	title: {API name}
26	description: {API Reference for the {API name} {function\|component\|file convention\|directive\|config option}.}
27	---
28
29	{One sentence defining what it does and where it's used.}
30
31	```tsx filename="path/to/file.tsx" switcher
32	// Minimal working usage
33	```
34
35	```jsx filename="path/to/file.js" switcher
36	// Same example in JS
37	```
38
39	## Reference
40
41	{For functions: methods/params table, return type.}
42	{For components: props summary table, then `#### propName` subsections.}
43	{For file conventions: `### Props` with `#### propName` subsections.}
44	{For directives: usage rules and serialization constraints.}
45	{For config: options table or individual option docs.}
46
47	### {Subsection name}
48
49	{Description + code example + table of values where applicable.}
50
51	## Good to know
52
53	- {Default behavior or implicit effects.}
54	- {Caveats, limitations, or version-specific notes.}
55	- {Edge cases the developer should be aware of.}
56
57	## Examples
58
59	### {Example name}
60
61	{Brief context, 1-2 sentences.}
62
63	```tsx filename="path/to/file.tsx" switcher
64	// Complete working example
65	```
66
67	```jsx filename="path/to/file.js" switcher
68	// Same example in JS
69	```
70
71	## Version History
72
73	\| Version \| Changes \|
74	\| -------- \| --------------- \|
75	\| `vX.Y.Z` \| {What changed.} \|
76	````
77
78	Category-specific notes:
79
80	- 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.
81	- 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.
82	- 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.
83	- Directives: No `## Reference` section. Use `## Usage` instead, showing correct placement. Document serialization constraints and boundary rules.
84	- Config options: Show the `next.config.ts` snippet. Use subsections for each behavioral aspect.
85
86	## Rules
87
88	1. Lead with what it does. First sentence defines the API. No preamble.
89	2. Show working code immediately. A minimal usage example appears right after the opening sentence, before `## Reference`.
90	3. Use `switcher` for tsx/jsx pairs. Always include both. Always include `filename="path/to/file.ext"`.
91	4. Use `highlight={n}` for key lines. Highlight the line that demonstrates the API being documented.
92	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.
93	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:".
94	7. Examples section uses `### Example Name` subsections. Each example solves one specific use case.
95	8. Version History table at the end. Include when the API has changed across versions. Omit for new APIs.
96	9. No em dashes. Use periods,

People who liked this also viewed

6 picks

Type