Skip to main content
skill CX Codex

ns-docs-writer — skill for Claude Code, Codex, Cursor

ns-docs-writer — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that produces human-facing project docs: README files, docs/ guides, runbooks, and contributor markdown.

Apache-2.0 151 installs updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nextstage-brasil/skills --skill ns-docs-writer -a claude-code
Open on GitHub

What ns-docs-writer does

The skill runs across six platforms: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. Installation on most platforms goes through npx skills add nextstage-brasil/skills --skill ns-docs-writer with a platform flag; the resulting SKILL.md lands in the agent folder for that platform.

Before drafting anything, the skill scans existing docs/, README, and AGENTS.md to link rather than duplicate. It infers folder structure from AGENTS.md or architecture-rules.md — it does not assume a monorepo packages/ layout. Drafts follow references/style-guide.md from the repository. Default audience is developer unless confirmed otherwise.

Version 1.4 depends on ns-harness; without it, session boot fails and the skill will not run. Code comments, /** */ docblocks, requirements.md, and SDD version artifacts fall outside its scope — those belong to PM skills.

What it helps with

  • Update a stale README after structural changes to a repo
  • Write a runbook or install guide for operators
  • Create an onboarding guide for new contributors
  • Consolidate scattered notes into a structured docs/ folder
  • Document agent architecture in docs/specs/agent-architecture.md

Example prompts for the agent

  • Write a README for the repository root reflecting the latest structural changes
  • Create a runbook in docs/ for deploying the service to staging
  • Add an onboarding guide for contributors to the existing README

How to install ns-docs-writer

1Skills CLI (Vercel)

npx skills add nextstage-brasil/skills --skill ns-docs-writer -a claude-code

2Manually: put the files in place

~/.claude/skills/ns-docs-writer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ns-docs-writer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ns-docs-writer

How do I install ns-docs-writer in Claude Code?

Run npx skills add nextstage-brasil/skills --skill ns-docs-writer -a claude-code; the skill file appears at ~/.claude/skills/ns-docs-writer/SKILL.md.

What does ns-docs-writer do?

It writes human-facing project documentation — README files, docs/ guides, runbooks, and contributor markdown. Code comments, API docblocks, and SDD artifacts are out of scope.

Why does ns-docs-writer require ns-harness?

ns-docs-writer lists ns-harness as a dependency; session boot references ns-harness/references/session-boot.md, so without that skill the session will not initialise.

Source text

SKILL.md · Apache-2.0
---
name: ns-docs-writer
description: "(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)."
license: Apache-2.0
metadata:
  author: nextstage-brasil
  version: "1.4"
depends:
  - ns-harness
---

# 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

© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills

Similar skills

All skills for Writing and docs →

From the same set20

The whole set →
ns-frontend-design ns-frontend-design — a skill for Claude Code, Codex, Cursor and other agents that builds production UI with deliberate typography, hierarchy and motion. Activates on pages, components, dashboards, forms and analytics views. CX Codex +1 153installs ns-autonomous ns-autonomous — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI that takes a local plan or pasted text and runs it autonomously inside an isolated worktree. CX Codex +1 152installs ns-e2e-tests The ns-e2e-tests skill structures Cypress end-to-end work across devices and keeps tests in a separate project. Use it when adding or refactoring specs. CX Codex +1 151installs ns-backend-tests ns-backend-tests — a skill for writing and running PHPUnit unit and integration tests directly in your IDE. Runs only in Docker containers, helping you quickly test a new Laravel project or rewrite existing tests. CX Codex +1 151installs ns-coder ns-coder handles focused code changes such as fixes, small refactors, scripts, and migrations. Use it for ad-hoc work outside a multi-stage SDD handoff. CX Codex +1 151installs ns-reviewer ns-reviewer grades code changes against SOLID principles, clean code patterns, performance, security, and testability. Approves only at score 10; score 9 triggers rejection. CX Codex +1 140installs ns-living-spec ns-living-spec maintains domain specifications in docs/specs/ after version releases or approved reviews. Turns diffs and release artifacts into functional truth. CX Codex +1 140installs ns-proto-visual-guide The ns-proto-visual-guide Claude Code skill documents the required appearance of cards, forms, shells, and overlays. It activates for normative visual guides and visual QA checklists. CX Codex +1 106installs

Project sponsors

Companies that keep this analytics open