playbooks

home / skills / revokslab / shipfree / docs

docs skill

/.cursor/skills/docs

This skill helps you generate concise, reader-friendly documentation for Next.js SaaS boilerplates with a relaxed tone.

npx playbooks add skill revokslab/shipfree --skill docs

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.1 KB
---
name: docs
description: ALWAYS use this when writing docs
---

You are an expert technical documentation writer

You are not verbose

Use a relaxed and friendly tone

The title of the page should be a word or a 2-3 word phrase

The description should be one short line, should not start with "The", should avoid repeating the title of the page, should be 5-10 words long

Chunks of text should not be more than 2 sentences long

Each section is separated by a divider of 3 dashes

The section titles are short with only the first letter of the word capitalized

The section titles are in the imperative mood

The section titles should not repeat the term used in the page title, for example, if the page title is "Models", avoid using a section title like "Add new models". This might be unavoidable in some cases, but try to avoid it.

Check out the /packages/web/src/content/docs/docs/index.mdx as an example.

For JS or TS code snippets remove trailing semicolons and any trailing commas that might not be needed.

If you are making a commit prefix the commit message with docs:

Overview

This skill ensures documentation follows the project’s style and structural rules for the Next.js SaaS boilerplate. It guides content layout, titles, code formatting, and commit message conventions for consistent, readable docs.

How this skill works

It checks and enforces the documentation guidelines: short titles, concise descriptions, two-sentence text chunks, divider usage, section title style, and code snippet formatting for JS/TS. It also reminds authors to prefix commit messages with docs: when committing changes related to documentation.

When to use it

  • When creating new documentation pages for the web package
  • When editing existing docs to match project style and structure
  • When formatting code snippets in JS or TS examples
  • Before committing docs-related changes to ensure proper commit prefix
  • When reviewing PRs that include documentation updates

Best practices

  • Use a one- or two-word page title and a 5–10 word single-line description
  • Keep paragraphs to at most two sentences and separate sections with '---'
  • Write section titles in imperative mood and capitalize only the first letter
  • Avoid repeating the page title inside section titles
  • Strip trailing semicolons and unnecessary trailing commas in JS/TS snippets
  • Prefix documentation commits with 'docs:' to signal the change type

Example use cases

  • Add a new setup guide for an auth provider following the style rules
  • Refactor an existing doc to split long paragraphs into two-sentence chunks
  • Convert code examples to valid JS/TS formatting without trailing semicolons
  • Review a PR to ensure section titles and dividers match project standards
  • Prepare a compact description and title for a new feature doc

FAQ

What is the required title length?

Keep the title to one or two words or a short phrase.

How long should the description be?

Write a single-line description of 5–10 words that does not repeat the title.

How should code snippets be formatted?

Use valid JS/TS without trailing semicolons or unnecessary trailing commas.