Docs Skills

docs-imagine — Generate conversion-focused docs from a product idea

Workflow#

  1. One question maximum. If the user already provided a product name or concept in their message, extract it and proceed immediately. Otherwise ask exactly one question: "What is your product? (name + one-liner)". Never ask a second question before generating — infer everything else from the product concept and context.

    • Infer the product category, likely audience, and tone from the name/description. State what you inferred ("I'm treating this as a SaaS developer tool — generating accordingly. Correct me if I'm off.") and proceed.

  2. Compose the content plan inline (no docs-plan.md file). For the given product, decide on a page set optimised for conversion and clarity:

    • README.md / index.md — hero overview: what it is, who it is for, the core promise in one sentence, CTA
    • getting-started.md — quickstart: shortest path to first win (under 5 minutes by convention)
    • 3–5 feature pages under features/ — each a benefit-first page: headline = the outcome the user gets, body = how it works + proof, ends with a CTA
    • use-cases/ (1–3 pages) — concrete job stories: "X uses this to do Y, getting Z"
    • faq.md — 6–10 frequently asked questions with answers that eliminate objections
    • blog/ or learn/ (optional, 1 page) — one educational or comparison piece if the product category benefits from it

  3. Write _branding.json alongside the docs folder. Source the product name and a domain-appropriate accent color suggestion from the product concept — do NOT default to #6366f1. If no confident color exists for the domain, leave accentColor absent so the workspace configurator skips update_branding rather than picking a default.

  4. Generate all Markdown files into docs-output/<product-slug>/. Apply conversion copywriting throughout:

    • Benefit-first headings (outcome the user gets, not the feature name)
    • Active voice, second person
    • No filler words ("just", "simply", "easily", "obviously")
    • Every page ends with a next-step CTA pointing to the logical next page or action
    • Apply /docs-content-types, /docs-structure-templates, /docs-style-tone, /docs-branding, /docs-media, and /docs-seo conventions by reference — do not inline-duplicate their rules

  5. Preview. Print a folder tree of docs-output/<product-slug>/ and show excerpts (first 20–30 lines) from 2–3 representative pages (hero + one feature + FAQ). Ask the user to confirm or give feedback before publishing: "Does this look right? Type yes to publish, or describe what to change."

  6. Publish. Apply /docs-publish logic:

    • If gh is authenticated and the user confirmed, commit and push the generated docs to GitHub (via git/gh, or your publishing step).
    • If gh is NOT authenticated or the user is not connected to Docsbook MCP, stop cleanly: print the local path and the command /docs-publish <path> to run after gh auth login. Do not error — this is a valid stopping point (status: crawl_only).

  7. Configure the workspace. Apply /docs-setup-workspace unconditionally after a successful publish:

    • Wire branding, UI, and navigation on your publishing platform (e.g. a connected Docsbook workspace), or write them into your docs config.
    • If the MCP transport is unreachable, print the connection command and exit cleanly — do not abort the overall pipeline; the local folder and GitHub URL are already delivered.

  8. Final report. Print all three outcomes:

    • Local path: docs-output/<product-slug>/
    • GitHub URL (if published)
    • Docsbook site URL (if workspace configured)

Guardrails#

  • Ask at most ONE upfront question (the product name/topic). Infer everything else — do not ask about audience, tone, color, page count, or structure.
  • Never invent competitor names or real-world facts. If a comparison or migration section is requested and no names were given, ask once or omit the section entirely.
  • Never use #6366f1 (or any other hardcoded default) as the accent color. Leave accentColor absent when no domain-appropriate color is deterministic.
  • Do NOT hand off to /docs-strategy-plan. This skill generates content immediately — it is not a planning skill.
  • Workspace setup is MANDATORY after a successful publish — it is what makes the user see how the live site looks. Skip only if MCP transport is unreachable (print instructions instead).
  • Never silently create a GitHub repo — always show a preview and receive a confirm signal first.
  • The content must be conversion-focused from first draft — marketing-grade language, not placeholder copy.

Acceptance Criteria#

  • Single upfront question (product name/topic) — zero if already provided in the message
  • All pages generated in docs-output/<product-slug>/ with at least README, getting-started, 3 feature pages, and FAQ
  • _branding.json written (accentColor absent or domain-appropriate, never default purple)
  • Preview (folder tree + page excerpts) shown before the publish prompt
  • User confirm received before any GitHub repo creation
  • Published to GitHub when gh is authenticated and user confirms; crawl_only status with local path otherwise
  • /docs-setup-workspace executed unconditionally after publish (unless MCP transport is unreachable)
  • Final report shows all three URLs (local path / GitHub URL / Docsbook site URL)