write-guide

Name: write-guide
Author: vercel

141kstars31kforks

How to install write-guide?

vercel/next.js/write-guide

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

Installs into the current project.

Summary

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 co

Files · 1

View on GitHub

SKILL.md

1	# Writing Guides
2
3	## Goal
4
5	Produce a technical guide that teaches a real-world use case through progressive examples. Concepts are introduced only when the reader needs them.
6
7	Each guide solves one specific problem. Not a category of problems. If the outline has 5+ steps or covers multiple approaches, split it.
8
9	## Structure
10
11	Every guide follows this arc: introduction, example setup, 2-5 progressive steps, next steps.
12
13	Each step follows this loop: working code → new requirement → friction → explanation → resolution → observable proof.
14
15	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).
16
17	Headings should tell a story on their own. If readers only saw the headings, they'd understand the guide's takeaway.
18
19	### Template
20
21	````markdown
22	---
23	title: {Action-oriented, e.g., "Building X" or "How to Y"}
24	description: {One sentence}
25	nav_title: {Short title for navigation}
26	---
27
28	{What the reader will accomplish and why it matters. The friction and how this approach resolves it. 2 paragraphs max.}
29
30	## Example
31
32	As an example, we'll build {what we're building}.
33
34	We'll start with {step 1}, then {step 2}, and {step 3}.
35
36	{Source code link.}
37
38	### Step 1: {Action-oriented title}
39
40	{Brief context, 1-2 sentences.}
41
42	```tsx filename="path/to/file.tsx"
43	// Minimal working code
44	```
45
46	{Explain what happens.}
47
48	{Introduce friction: warning, limitation, or constraint.}
49
50	{Resolution: explain the choice, apply the fix.}
51
52	{Verify the fix with observable proof.}
53
54	### Step 2: {Action-oriented title}
55
56	{Same pattern: context → code → explain → friction → resolution → proof.}
57
58	### Step 3: {Action-oriented title}
59
60	{Same pattern.}
61
62	## Next steps
63
64	You now know how to {summary}.
65
66	Next, learn how to:
67
68	- [Related guide 1]()
69	- [Related guide 2]()
70	````
71
72	### Workflow
73
74	1. Research: Check available skills for relevant features. Read existing docs for context and linking opportunities.
75	2. Plan: Outline sections. Verify scope (one problem, 2-4 steps). Each step needs a friction point and resolution.
76	3. Write: Follow the template above. Apply the rules below.
77	4. Review: Re-read the rules, verify, then present.
78
79	## Rules
80
81	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.
82	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."
83	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."
84	4. One friction point per step. If a step has multiple friction points, split it.
85	5. Minimal code blocks. Only the code needed for the current step. Collapse unchanged functions with `function Header() {}`.
86	6. No em dashes. Use periods, commas, or parentheses instead.
87	7. Mechanical, observable language. Describe what happens, not how it feels.
88	8. No selling, justifying, or comparing. No "the best way," no historical context, no framework comparisons.
89
90	\| Don't \| Do \|
91	\| ---------------------------------------------------- \| -------------------------------------------------------- \|
92	\| "creates friction in the pipeline" \| "blocks the response" \|
93	\| "needs dynamic information" \| "depends on request-time data" \|
94	\| "requires dynamic processing" \| "output can't be known ahead of time" \|
95	\| "The component blocks the response — causing delays" \| "The component blocks the response. This causes delays." \|
96
97	9. Bridge new framework terms with legacy or generic vocabulary in `description` and intro. Guides win or lose SERPs on the colloquial query (e.g. "next js form submission", "next js api endpoint", "next js error page"), not on the framework's preferred noun. Wh

People who liked this also viewed

6 picks

Type

write-guide

141kstars31kforks

View on GitHub

How to install write-guide?

vercel/next.js/write-guide

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Writing Guides
2
3	## Goal
4
5	Produce a technical guide that teaches a real-world use case through progressive examples. Concepts are introduced only when the reader needs them.
6
7	Each guide solves one specific problem. Not a category of problems. If the outline has 5+ steps or covers multiple approaches, split it.
8
9	## Structure
10
11	Every guide follows this arc: introduction, example setup, 2-5 progressive steps, next steps.
12
13	Each step follows this loop: working code → new requirement → friction → explanation → resolution → observable proof.
14
15	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).
16
17	Headings should tell a story on their own. If readers only saw the headings, they'd understand the guide's takeaway.
18
19	### Template
20
21	````markdown
22	---
23	title: {Action-oriented, e.g., "Building X" or "How to Y"}
24	description: {One sentence}
25	nav_title: {Short title for navigation}
26	---
27
28	{What the reader will accomplish and why it matters. The friction and how this approach resolves it. 2 paragraphs max.}
29
30	## Example
31
32	As an example, we'll build {what we're building}.
33
34	We'll start with {step 1}, then {step 2}, and {step 3}.
35
36	{Source code link.}
37
38	### Step 1: {Action-oriented title}
39
40	{Brief context, 1-2 sentences.}
41
42	```tsx filename="path/to/file.tsx"
43	// Minimal working code
44	```
45
46	{Explain what happens.}
47
48	{Introduce friction: warning, limitation, or constraint.}
49
50	{Resolution: explain the choice, apply the fix.}
51
52	{Verify the fix with observable proof.}
53
54	### Step 2: {Action-oriented title}
55
56	{Same pattern: context → code → explain → friction → resolution → proof.}
57
58	### Step 3: {Action-oriented title}
59
60	{Same pattern.}
61
62	## Next steps
63
64	You now know how to {summary}.
65
66	Next, learn how to:
67
68	- [Related guide 1]()
69	- [Related guide 2]()
70	````
71
72	### Workflow
73
74	1. Research: Check available skills for relevant features. Read existing docs for context and linking opportunities.
75	2. Plan: Outline sections. Verify scope (one problem, 2-4 steps). Each step needs a friction point and resolution.
76	3. Write: Follow the template above. Apply the rules below.
77	4. Review: Re-read the rules, verify, then present.
78
79	## Rules
80
81	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.
82	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."
83	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."
84	4. One friction point per step. If a step has multiple friction points, split it.
85	5. Minimal code blocks. Only the code needed for the current step. Collapse unchanged functions with `function Header() {}`.
86	6. No em dashes. Use periods, commas, or parentheses instead.
87	7. Mechanical, observable language. Describe what happens, not how it feels.
88	8. No selling, justifying, or comparing. No "the best way," no historical context, no framework comparisons.
89
90	\| Don't \| Do \|
91	\| ---------------------------------------------------- \| -------------------------------------------------------- \|
92	\| "creates friction in the pipeline" \| "blocks the response" \|
93	\| "needs dynamic information" \| "depends on request-time data" \|
94	\| "requires dynamic processing" \| "output can't be known ahead of time" \|
95	\| "The component blocks the response — causing delays" \| "The component blocks the response. This causes delays." \|
96
97	9. Bridge new framework terms with legacy or generic vocabulary in `description` and intro. Guides win or lose SERPs on the colloquial query (e.g. "next js form submission", "next js api endpoint", "next js error page"), not on the framework's preferred noun. Wh

People who liked this also viewed

6 picks

Type