Docs Writer

This skill provides one core documentation workflow with profile-aware rules. Use this as the default docs skill, then apply a profile when the repo has framework-specific conventions.

Profile Selection

Choose one profile before planning edits:

• generic (default) for most repositories

• nextjs for Next.js docs trees and MDX conventions

• angular for Angular documentation conventions

Profile references:

• references/PROFILE-GENERIC.md

• references/PROFILE-NEXTJS.md

• references/PROFILE-ANGULAR.md

• references/TEMPLATES.md

Phase 1: Discover

Goal: understand request scope and affected documentation surface.

Checklist:

• Clarify whether task is new docs, update, review, or impact analysis.

• Inspect changed code/docs and identify user-visible behavior changes.

• Identify target audience and intent (tutorial, reference, concept, release note).

• Select the profile and list constraints from that profile.

If request is large collaborative drafting (RFC/spec/proposal), use the co-authoring mode in references/CORE-CHECKLIST.md .

Phase 2: Plan

Goal: produce an explicit edit plan before writing.

Checklist:

• Map code changes to documentation targets.

• List exact files to update/create.

• Define section-level changes for each file.

• Note cross-links, sidebars/index pages, and related docs updates.

• Define validation commands and quality gates.

Use references/CORE-CHECKLIST.md for planning prompts. Consult references/TEMPLATES.md when selecting document structure and scaffolding.

Phase 3: Write

Goal: apply focused edits with high signal and minimal drift.

Rules:

• Keep writing user-centered, direct, and task-oriented.

• Preserve repository terminology and existing information architecture.

• Use concrete examples and expected outcomes where helpful.

• Prefer updating canonical sources over duplicating content.

• For profile-specific formatting (frontmatter, MDX components, code block attributes), follow the selected profile strictly.

• Start from references/TEMPLATES.md for README/API/tutorial structure before adding project-specific details.

When creating new docs, include:

• clear title and short description

• prerequisites (if needed)

• actionable steps/examples

• edge cases or errors (where relevant)

• next steps or related links

Phase 4: Verify

Goal: ensure docs are accurate, consistent, and ready to merge.

Verification sequence:

• Technical accuracy check against code and behavior.

• Style and structure check against profile + core checklist.

• Link/reference integrity check.

• Formatting/lint/build checks using repository commands.

• Final pass for redundancy, ambiguity, and stale statements.

Before completion, report:

• files changed

• why each change was needed

• validation performed and results

Boundaries and Handoffs

• Use this skill as default for docs work.

• All profile guidance is self-contained under references/ in this skill.

• Keep framework-specific constraints inside profile documents, not the core flow.