Write Guide

This is Vercel's opinionated template for writing technical guides that teach through progressive examples. It enforces a specific structure: brief intro, example setup, 2-5 steps that follow a working code to new requirement to resolution loop, and next steps. The philosophy is one guide per specific problem, not a category of problems. If your outline has more than 5 steps or covers multiple approaches, you're supposed to split it. Useful if you're maintaining documentation for Next.js or want to adopt their guide-writing conventions. The structure is prescriptive enough to keep guides focused but flexible enough for real-world tutorials.

skills.sh installs: 721
GitHub stars: 139.5K
last updated: May 16, 2026

View on GitHub

Install

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

Installs into .claude/skills of the current project.

Files

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

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

SKILL.md on GitHub