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
npx skills add nextstage-brasil/skills --skill ns-docs-writer -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/ns-docs-writer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ns-docs-writer/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-docs-writer -a codex2Manually: put the files in place
.agents/skills/ns-docs-writer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-docs-writer -a cursor2Manually: put the files in place
.cursor/skills/ns-docs-writer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-docs-writer2Manually: put the files in place
.github/skills/ns-docs-writer/SKILL.md1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-docs-writer -a gemini-cli2Platform CLI
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-docs-writerManually: put the files in place
.devin/skills/ns-docs-writer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-docs-writer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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