Skip to content
Skills Library
Documents & office · Writing

write-guide

/write-guide

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.

Repository
next.js ↗
Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author 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.

How it works

  1. Goal
  2. Structure
  3. Rules
  4. References
Original SKILL.md headings · 111 lines, 768 words
SKILL.md preview
---
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
metadata:
  internal: true
---

# 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." |

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. When the guide covers a renamed or differentiated concept, include one synonym (Pages-era term, REST/web term, or industry-standard label) in the frontmatter `description` and once in the introduction. Fold into prose. No separate "Synonyms" or "Also known as" section.

| Don't                                            | Do                                                                                                            |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| "Learn how to use Route Handlers"                | "Build API endpoints (formerly API Routes) with Route Handlers"                                               |
| "Learn how to mutate data with Server Functions" | "Submit forms and update data with Server Functions, the App Router approach to form posts and API mutations" |

## 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.

Versions

RepositoryScoreLicence
This page · vercel/next.js100MIT
runpod/runpod-plugins-official100Apache-2.0

Database snapshot: 13.11.2026 · package version c95e56d15092 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100write-api-reference
    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…
  • 100markdown-writer
    Generates well-structured technical documentation in Markdown. Use when a user asks to write docs, create a README, document an API, write a how-to guide, generate technical documentation, create a changelog, write a project wiki, or produce any structured Markdown content.…
  • 100tech-writer-researcher
    Write and research technical documentation. Cover information architecture, style guides, API documentation, user research, content strategy, and documentation operations. Triggers on "write technical documentation", "create API docs", "developer tutorial", "information…
  • 100s4h-writing-technical
    Writes and audits technical documentation, API docs, user guides, and specifications for completeness, sequence, precision, and audience calibration. Use when documentation is confusing, assumes too much knowledge, or leaves gaps a user can't bridge. Triggers: 'technical…
  • 100troubleshooting-guide-creator
    Create troubleshooting guide creator operations. Auto-activating skill for Technical Documentation. Triggers on: troubleshooting guide creator, troubleshooting guide creator Part of the Technical Documentation skill category. Use when working with troubleshooting guide creator…
  • 100dev-guide-generator
    Generates complete technical tutorials from prerequisites and environment setup to core steps, troubleshooting, and a final cheatsheet. Trigger on requests to write a tutorial, create a setup guide, organize steps for beginners, or keywords like step-by-step, quickstart, or how-to guide.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.