skills.rest
vesviet
vesvietCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

write-documentation

Draft and update technical documentation following Diataxis structure and docs-as-code pipelines.

Updated Feb 10, 2026
Search Tags:#documentation#openapi#technical writing#readme#runbooks#diataxis#docs-as-code
One-click install
npx skills add https://github.com/vesviet/agent-skills --skill write-documentation-vesviet
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-documentation
Source: https://github.com/vesviet/agent-skills/tree/main/core/skills/documentation/write-documentation
Command: npx skills add https://github.com/vesviet/agent-skills --skill write-documentation-vesviet

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Keeping READMEs, runbooks, and API docs accurate and consistent is hard when docs drift from the source of truth, mix audience types, or go stale after releases. This Skill enforces a structured, verifiable documentation workflow so every page serves a clear audience and stays aligned with the actual system. ## Core Features & Use Cases - Diataxis-structured authoring: Every document is classified as a Tutorial, How-to, Reference, or Explanation, with one quadrant per file and semantic YAML frontmatter for AI/RAG retrieval. - Docs-as-code quality gates: Documentation passes markdownlint, Vale prose checks, broken-link validation, secret scanning, and frontmatter schema validation before merge, with deploy previews on Cloudflare Pages or Netlify. - Spec-driven reference docs: API references are auto-generated from OpenAPI/AsyncAPI specs using Redocly, Scalar, or Mintlify instead of hand-typed endpoint lists. - Use Case: After shipping a new API version, use this Skill to update the service README, regenerate reference docs from the OpenAPI spec, refresh /llms.txt, and emit a documentation handoff contract for the docs pipeline. ## Quick Start Use the write-documentation skill to update the README and runbook for this service based on the current code and OpenAPI spec.

Frequently Asked Questions about write-documentation

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

FAQPage Schema
How do I write technical documentation that stays in sync with code?▼

Treat the code and OpenAPI/AsyncAPI specs as the single source of truth and link to them instead of duplicating content. Auto-generate API reference docs with Redocly, Scalar, or Mintlify, and re-validate docs on every release so stale guidance becomes a release-blocking issue.

What is the Diataxis framework for documentation?▼

Diataxis splits documentation into four quadrants: Tutorials (learning-oriented), How-to guides (problem-oriented), Reference (information-oriented), and Explanation (understanding-oriented). Each file must belong to exactly one quadrant, so architectural philosophy is never mixed into step-by-step beginner guides.

Should API reference docs be hand-written or auto-generated?▼

API reference docs should be auto-generated from OpenAPI, AsyncAPI, or protobuf specs using tools like Redocly, Scalar, or Mintlify. Hand-typed endpoint definitions drift from the spec and are rejected under this workflow.

What CI checks should documentation pull requests pass?▼

Documentation PRs should pass markdownlint, Vale prose style checks, a broken-link checker, frontmatter schema validation, and a secret scan before merge. Deploy previews on Cloudflare Pages or Netlify give reviewers a rendered view for sign-off.

How do I make documentation readable for AI agents and LLMs?▼

Maintain /llms.txt and /llms-full.txt at the repository root and regenerate them on every doc change. Use consistent Markdown headings, unambiguous terminology, and YAML frontmatter with title, description, category, and last_verified_version so RAG retrieval works without hallucination.

When should I use write-documentation instead of write-article?▼

Use write-documentation for READMEs, runbooks, API docs, and setup guides under the Technical Writer role. Long-form articles, blogs, guides, and SEO posts route to the Content Writer role with the write-article skill instead.

Related Skills

Explore More Content & Communication Skills→
nguyenpv1980-wqnguyenpv1980-wq
2

architecture-designer

Design software architecture from inspected codebase components and dependencies.

Community
Advanced
yo-stevenyo-steven

contributing

Standardize NeMo-RL pull request titles, signed commits, and CI triggering.

Community
Basic
machenjiemachenjie
4

change-documentation-gate

Identify required documentation updates and blocking gaps for code changes.

Community
Advanced
ConradmakerConradmaker

writing-content

Draft and structure audience-facing content for social posts, blogs, and articles.

Community
Intermediate