mcpField
N
ns-docs-writer

ns-docs-writer

github.com/nextstage-brasilDocuments0127 installsUpdated 5d ago
Repository

About ns-docs-writer

ns-docs-writer is a skill for writing and maintaining project documentation in docs/ and README files. It guides discovery, audience selection, outlining, drafting, and linking while keeping its scope distinct from code comments and living specifications.

Key features

  1. 01README and docs authoring
  2. 02Documentation discovery and scope checks
  3. 03Audience selection and outline planning
  4. 04Style-guided drafting
  5. 05Relative links to canonical guidance

Use cases

  1. 01Documenting a newly delivered feature
  2. 02Updating a README after structural changes
  3. 03Preparing contributor onboarding guides
  4. 04Consolidating notes into docs/

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nextstage-brasil/skills --skill ns-docs-writer

After installing, type/ns-docs-writerin Claude Code to confirm it loaded.

Bundled filesevals/evals.jsonreferences/style-guide.md

Details

From the project README

Docs Writer

Author clear, maintainable project documentation under docs/ and README files.

Session boot

See ../../ns-harness/references/session-boot.md.

Scope

In scopeOut of scope
README.md at product or repo rootInline // or /** code comments
docs/**/*.md guidesdocs/versions/*/sdd/requirements.md, docs/versions/*/requirements.md (legacy SDD)
Runbooks, install guides, architecture overviews for humansLiving specs in docs/specs/ (use ns-living-spec)
Changelog entries when requestedMarketing copy outside repo

When to use

  • New feature needs user or developer documentation
  • README is stale after structural changes
  • Onboarding guide for contributors
  • Consolidating scattered notes into docs/

Workflow

  1. Discover — list existing docs/, README, and AGENTS.md links; avoid duplicating harness/brownfield artifacts (link instead).
  2. Audience — confirm developer vs operator vs end-user (default: developer).
  3. Outline — short TOC before drafting long guides.
  4. Draft — follow references/style-guide.md.
  5. Link — prefer relative links; point to canonical rules in .nextstage-harness/rules/ when relevant.

Layout (stack-agnostic)

Do not assume monorepo packages/ layout. Infer from:

  • AGENTS.md layout table
  • architecture-rules.md
  • Existing docs/ structure

Create subfolders only when they match project convention.

Integration

When called from ns-spec-driven, document delivered behavior — do not invent requirements.

Agent why (reference architecture, agent vs code, trade-offs, topology, HITL, change signal) lives in docs/specs/agent-architecture.md. Link it. Do not copy the interview or rewrite the decision record in README. docs/specs/agent.md is behavior (ns-living-spec), not this ADR.

Forbidden

  • Copying full bodies of brownfield-map.md or system-reverse-spec.md into new docs (link them)
  • English violations when project mandates English docs
  • Auto-generating docs for code that does not exist yet
  • Same version with both docs/versions/*/sdd/requirements.md and legacy docs/versions/*/requirements.md — link canonical sdd/ path only; never create or maintain dual trees

Comments

Markdown supported