# Ns Docs Writer

> (NS) Human-facing project docs — README, docs/ guides, runbooks, contributor markdown. Use whenever the user asks for documentation, README updates, how-to guides, or docs/ content — even if they say "explain how to use" instead of "write docs". Do NOT use for code comments, API docblocks, requirements.md, or SDD version artifacts (use PM skills).

- Skill: `nextstage-brasil/ns-docs-writer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nextstage-brasil/ns-docs-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nextstage-brasil/ns-docs-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: Apache-2.0
- Author: nextstage-brasil (https://skillmd.com/u/nextstage-brasil)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nextstage-brasil/ns-docs-writer

---


# Docs Writer

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

## Session boot

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

## Scope

| In scope | Out of scope |
| -------- | ------------ |
| `README.md` at product or repo root | Inline `//` or `/**` code comments |
| `docs/**/*.md` guides | `docs/versions/*/sdd/requirements.md`, `docs/versions/*/requirements.md` (legacy SDD) |
| Runbooks, install guides, architecture overviews for humans | Living specs in `docs/specs/` (use `ns-living-spec`) |
| Changelog entries when requested | Marketing 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