draft-openspec-docs

Drafts OpenSpec documentation pages section by section using an in-page scratch plan.

3|1|Updated Apr 29, 2026
One-click install
npx skills add https://github.com/firstsun-dev/skills --skill draft-openspec-docs-firstsun-dev
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: draft-openspec-docs
Source: https://github.com/firstsun-dev/skills/tree/main/plugins/spec-driven-development/skills/draft-openspec-docs
Command: npx skills add https://github.com/firstsun-dev/skills --skill draft-openspec-docs-firstsun-dev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Rewriting or creating a documentation page from scratch often produces unstructured drafts with no user review checkpoints. This Skill keeps the plan, decisions, and drafting steps inside the page itself so the user approves the structure before any prose is written. ## Core Features & Use Cases - In-page scratch planning: Builds a scratch section with purpose, structure, notes, and a numbered draft plan directly inside the target page, then deletes it before publishing. - Step-by-step drafting: Drafts exactly one approved step at a time (e.g., D1, D2), verifies facts against source files, and marks each step done in the plan. - Consolidation and cleanup: Updates the README goal line, message map, sync config, and cross-links, then runs the docs sync validation script. - Use Case: A maintainer needs to rewrite an OpenSpec docs page from scratch. The Skill proposes a purpose and section structure in the page, iterates with the maintainer, then drafts each section on request and cleans up the scratch block. ## Quick Start Ask the agent to draft the target OpenSpec docs page from scratch using the scratch-plan workflow, then approve the plan and call each draft step by ID.

Frequently Asked Questions about draft-openspec-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I draft an OpenSpec docs page from scratch?▼

Invoke the skill with the target page, and it strips the page to its title and goal line, then adds a scratch section with purpose and structure. After you approve the plan, call each draft step by ID and the skill writes that section into the page.

How does the scratch-plan workflow keep the user in the loop?▼

The plan lives inside the page itself, so you can edit it directly between turns and those edits are treated as decisions. The skill reshapes the plan as many times as needed and only drafts after you call a specific step ID.

What other skills does draft-openspec-docs depend on?▼

It requires loading write-openspec-docs as the style authority and no-ai-slop before drafting anything. The retrievability and glance tests from write-openspec-docs are also run during cleanup.

What happens during the consolidation and cleanup phase?▼

The skill updates everything pointing at the page: the README goal line, message map, sync config, and cross-links found by grepping the tree. It then runs node website/scripts/sync-docs.mjs to validate, deletes the scratch block, and flips the message-map row to Answered.

When should I not use the draft-openspec-docs workflow?▼

It is designed for from-scratch rewrites or new pages shaped with the user in the loop. Small targeted edits to an existing page do not need the full scratch-plan, step-by-step drafting cycle.