Documentation
/Documentation
Documentation standards and code-to-docs sync conventions for Forge projects — JSDoc/TSDoc annotations, README/CHANGELOG structure, auto-generated API reference, doc-tree layout, and staleness detection. Use when writing or reviewing docs, adding JSDoc to exported functions, structuring a docs/ tree, deciding what to document vs auto-generate, or running the Forge docs commands (/nxtg-forge:docs-status, /nxtg-forge:docs-audit, /nxtg-forge:docs-update).
- Author
- nxtg-ai ↗
- Repository
- forge-plugin ↗
- Licence
- MIT
- Last repository change
- 15.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Documentation standards and code-to-docs sync conventions for Forge projects — JSDoc/TSDoc annotations, README/CHANGELOG structure, auto-generated API reference, doc-tree layout, and staleness detection. Use when writing or reviewing docs, adding JSDoc to exported functions, structuring a docs/ tree, deciding what to document vs auto-generate, or running the Forge docs commands (/nxtg-forge:docs-status, /nxtg-forge:docs-audit, /nxtg-forge:docs-update).
Original author description
Documentation standards and code-to-docs sync conventions for Forge projects — JSDoc/TSDoc annotations, README/CHANGELOG structure, auto-generated API reference, doc-tree layout, and staleness detection. Use when writing or reviewing docs, adding JSDoc to exported functions, structuring a docs/ tree, deciding what to document vs auto-generate, or running the Forge docs commands (/nxtg-forge:docs-status, /nxtg-forge:docs-audit, /nxtg-forge:docs-update).
How it works
- The Documentation Promise
- Documentation Hierarchy
- Documentation Types & Ownership
- Staleness Detection
- Documentation Quality Checklist
- Commands
- Gotchas
- Additional resources
SKILL.md preview
---
name: Documentation
description: >
Documentation standards and code-to-docs sync conventions for Forge projects — JSDoc/TSDoc
annotations, README/CHANGELOG structure, auto-generated API reference, doc-tree layout, and
staleness detection. Use when writing or reviewing docs, adding JSDoc to exported functions,
structuring a docs/ tree, deciding what to document vs auto-generate, or running the Forge
docs commands (/nxtg-forge:docs-status, /nxtg-forge:docs-audit, /nxtg-forge:docs-update).
when_to_use: >
Trigger phrases: "document this", "add JSDoc", "write the README", "generate API docs",
"is our documentation stale", "docs audit", "documentation coverage", "changelog", "ADR",
"how should I structure docs", "docs are out of date".
allowed-tools: Read, Grep, Glob, Bash(git *), Bash(find *)
---
# Documentation Management
**Purpose**: Keep documentation synchronized with code
**Primary Agent**: `release-sentinel` (opus) — docs↔code sync, staleness, changelog generation
**Supporting Agent**: `docs` (sonnet) — writes JSDoc/README/API/architecture docs
**Contributors**: all agents (each documents its own output)
---
## The Documentation Promise
> "Every feature is documented. Every change is tracked.
> No user is left wondering how something works."
The doc tree below is the **recommended layout for a consuming project** — it is aspirational,
not the structure of this plugin repo itself. Adopt the parts that fit; do not scaffold empty
directories to match it.
---
## Documentation Hierarchy
````
docs/
├── README.md # Entry point, always current
├── CHANGELOG.md # Auto-generated from commits
├── CONTRIBUTING.md # How to contribute
├──
├── getting-started/ # Onboarding
│ ├── installation.md
│ ├── quick-start.md
│ └── first-project.md
│
├── guides/ # How-to guides
│ ├── authentication.md
│ ├── deployment.md
│ └── troubleshooting.md
│
├── api/ # API reference (auto-generated)
│ ├── overview.md
│ ├── users.md
│ ├── projects.md
│ └── webhooks.md
│
├── components/ # Component docs (auto-generated)
│ ├── button.md
│ ├── input.md
│ └── card.md
│
├── cli/ # CLI reference (auto-generated)
│ └── commands.md
│
├── architecture/ # Design docs (manual)
│ ├── overview.md
│ ├── decisions/ # ADRs
│ │ ├── 001-database-choice.md
│ │ └── 002-auth-strategy.md
│ └── diagrams/
│
└── templates/ # Doc templates
├── api-endpoint.md
├── component.md
└── adr.md
````
---
## Documentation Types & Ownership
### 1. Reference Documentation (Auto-Generated)
**What**: API endpoints, component props, CLI commands, config options
**How**: Extract from code annotations (JSDoc, OpenAPI, decorators)
**When**: On every relevant code change
**Owner**: Release Sentinel (automated)
````typescript
/**
* Create a new user account
*
* @endpoint POST /api/users
* @auth Required (Bearer token)
* @rateLimit 10 requests/minute
*
* @param {string} email - User's email address
* @param {string} password - Password (min 8 chars)
* @param {string} [name] - Display name (optional)
*
* @returns {User} Created user object
* @throws {400} Invalid input
* @throws {409} Email already exists
*
* @example
* ```bash
* curl -X POST https://api.example.com/users \
* -H "Authorization: Bearer <token>" \
* -d '{"email": "user@example.com", "password": "secure123"}'
* ```
*/
export async function createUser(req: Request): Promise<User> {
// Implementation
}
````
↓ Auto-generates ↓
````markdown
## POST /api/users
Create a new user account.
### Authentication
Required. Include Bearer token in Authorization header.
### Rate Limit
10 requests per minute.
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address |
| password | string | Yes | Password (min 8 chars) |
| name | string | No | Display name |
### Response
Returns the created `User` object.
### Errors
| Code | Description |
|------|-------------|
| 400 | Invalid input |
| 409 | Email already exists |
### Example
```bash
curl -X POST https://api.example.com/users \
-H "Authorization: Bearer <token>" \
-d '{"email": "user@example.com", "password": "secure123"}'
```
````
---
### 2. Conceptual Documentation (Human + AI)
**What**: Architecture overviews, design decisions, system concepts
**How**: Human writes, AI assists with formatting and linking
**When**: After major architectural changes
**Owner**: Lead Architect creates, Release Sentinel maintains
---
### 3. Tutorial Documentation (Human + AI)
**What**: Step-by-step guides, walkthroughs, examples
**How**: Human creates outline, AI can expand and validate
**When**: New features, common workflows
**Owner**: Relevant agent creates, Release Sentinel maintains
---
### 4. Changelog (Fully Automated)
**What**: Version history, changes, migration guides
**How**: Parse conventional commits
**When**: Every release
**Owner**: Release Sentinel (automated)
---
## Staleness Detection
Documentation becomes stale when:
1. **Code changed, docs didn't**
- File hash changed since last doc update
- New exports not documented
- Function signatures changed
2. **Time-based decay**
- No updates in 90+ days for active areas
- Version mismatch (doc says v1.x, code is v2.x)
3. **Link rot**
- Internal links broken
- External links return 404
4. **Example failures**
- Code examples don't compile
- API examples return errors
---
## Documentation Quality Checklist
Every documentation file must have:
- [ ] Clear title and purpose
- [ ] Last updated date
- [ ] Version compatibility note
- [ ] Working code examples
- [ ] Links to related docs
- [ ] No broken links
- [ ] No outdated screenshots
---
## Commands
These are namespaced under `forge:` and are **user-typed only** — each carries
`disable-model-invocation: true`, so Claude never auto-invokes them; the user runs them.
| Command | Purpose | Arguments |
|---------|---------|-----------|
| `/nxtg-forge:docs-status` | Show documentation health & coverage | none |
| `/nxtg-forge:docs-audit` | Comprehensive quality audit (coverage, inventory, links) | none |
| `/nxtg-forge:docs-update` | Find and update stale docs | `--file <path>`, `--dry-run`, `--jsdoc`, or none = all |
There is **no** `docs-generate` command in this plugin. To create a doc from a template, invoke
the `docs` agent or use `/nxtg-forge:docs-update --jsdoc` for source annotations.
---
## Gotchas
- **`/docs-generate` does not exist.** Earlier revisions of this skill listed it; the plugin ships
only `docs-status`, `docs-audit`, `docs-update`. Do not tell a user to run it.
- **Commands are namespaced `/nxtg-forge:docs-*`, not bare `/docs-*`.** Claude Code namespaces plugin
commands by the plugin `name` (`nxtg-forge`). A bare name, or the old `forge` namespace, does not resolve.
- **These commands do not auto-trigger.** All three have `disable-model-invocation: true`. Saying
"check the docs" does not fire them — the user must type the slash command, or you run the
underlying analysis yourself with Grep/Glob/Bash.
- **`docs-update` argument surface is inconsistent between frontmatter and body.** Its
`argument-hint` advertises `[file-path] [--all]`, but the command body actually parses
`--file <path>`, `--dry-run`, and `--jsdoc` (bare invocation = update all). Follow the body's
flags, not the hint.
- **Staleness detection is git-window-based, not semantic.** `docs-update` compares
`git diff --name-only HEAD~20 -- src/` against docs changes — a doc edited by hand without a
matching source commit inside that window can read as "fresh" even if wrong. It flags *drift*,
not *correctness*.
- **Two agents own docs, split by intent.** `release-sentinel` (opus) handles sync/staleness/
changelog around releases; `docs` (sonnet) authors new prose. Route "keep docs current for the
release" to release-sentinel and "write the API guide" to docs.
- **Auto-generation only works if the source is annotated.** The JSDoc→markdown pipeline below
produces nothing from undocumented exports. `docs-status` counts documented vs undocumented
exports precisely so you know the input coverage before generating.
---
## Additional resources
- `docs/architecture/decisions/` — ADRs (Architecture Decision Records), manually authored
- Command sources: `commands/docs-status.md`, `commands/docs-audit.md`, `commands/docs-update.md`
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · nxtg-ai/forge-plugin | 90 | MIT |
| software-combined/SC_AI | 100 | Apache-2.0 |
| DaveSkender/Stock.Indicators | 100 | Apache-2.0 |
| mcouthon/agents | 100 | MIT |
| YLfjuk/deltafold | 100 | MIT |
| comet-ml/opik | 100 | Apache-2.0 |
| runwield/runwield | 100 | MIT |
| anthropics/knowledge-work-plugins | 100 | Apache-2.0 |
| luocfprime/labtasker | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 4f5a4ffad177 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100jsdoc
JSDoc - documentation generator for JavaScript with type annotations. USE WHEN: user mentions "JSDoc", "JavaScript documentation", asks about "documenting JavaScript", "type hints", "jsdoc comments", "API documentation generation" DO NOT USE FOR: TypeScript - use `jsdoc-tsdoc`… - 100packages-documentation
Write, update, and format documentation for @data-client public APIs - API reference (Docusaurus/MDX), README files, JSDoc/TSDoc docstrings, usage examples, migration guides, deprecation notices, changelog entries. Use when changing exported APIs (docs must update in the same… - 100jsdoc-tsdoc
JSDoc and TSDoc documentation standards. Covers syntax, tags, TypeScript integration, documentation generation, and API documentation best practices. USE WHEN: user mentions "TSDoc", "TypeScript documentation", "API documentation", asks about "documenting TypeScript", "@param",… - 90Domain Knowledge
NXTG-Forge product domain knowledge — the mission, core concepts (project spec, agent orchestration, state, Clean Architecture, drift/gap analysis, MCP), the real `forge` CLI surface, and the 3-repo workspace layout. Use when onboarding to what NXTG-Forge IS and why, when a… - 90Core NXTG-Forge
Ground truth for the NXTG-Forge platform — the real forge CLI subcommands, the /nxtg-forge:* slash commands, the .forge/state.json + events.jsonl model, both MCP servers (Rust orchestrator + Node governance), the agent roster, and the security hooks. Use when working inside or… - 100docs-writer
Write and update developer documentation (READMEs, docstrings and code comments, ADRs, CHANGELOG entries in Keep a Changelog format, and API usage docs) based on the actual code, with commands and examples that run. Use when the user asks to document a project, module, function…