Skip to content
Skills Library
Programming · Writing

docs-agent

/docs-agent

Generate project documentation, API docs, READMEs and changelogs in native orchestrator dispatch or explicitly requested solo documentation work. Read real contracts and code; load it when the orchestrator assigns this role or the user asks for it.

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Generate project documentation, API docs, READMEs and changelogs in native orchestrator dispatch or explicitly requested solo documentation work. Read real contracts and code; load it when the orchestrator assigns this role or the user asks for it.

Original author description

Generate project documentation, API docs, READMEs and changelogs in native orchestrator dispatch or explicitly requested solo documentation work. Read real contracts and code; load it when the orchestrator assigns this role or the user asks for it.

How it works

  1. When this skill applies
  2. Role
  3. Inputs
  4. Your Ownership
  5. Process
  6. Coordination Rules
  7. Validation
Original SKILL.md headings · 106 lines, 865 words
SKILL.md preview
---
name: docs-agent
version: 1.3.3
disable-model-invocation: true
description: "Generate project documentation, API docs, READMEs and changelogs in native orchestrator dispatch or explicitly requested solo documentation work. Read real contracts and code; load it when the orchestrator assigns this role or the user asks for it."
compatibility: "Read/edit host; native Claude dispatch retained"
requires_agent_teams: false
requires_claude_code: false
min_plan: starter
owns:
  directories: ["docs/"]
  patterns: ["README.md", "CHANGELOG.md", "CONTRIBUTING.md"]
  shared_read: ["*"]
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep"]
composes_with: ["backend-agent", "frontend-agent", "infrastructure-agent", "mermaid-charts", "contract-author"]
spawned_by: ["orchestrator"]
---

# Docs Agent

> **Pipeline position.** Spawned by `orchestrator` after contracts are authored. Reads `contract-author`'s output from `/contracts/`. Your generated docs are an input the qe-agent may weigh in its `completeness` and `code_quality` scores — but neither of those dimensions gates the build (only `contract_conformance`, `security`, and CRITICAL blockers do). Owns: `docs/` — **except** `docs/agents/` (owned by `setup-project-skills`) and `docs/adr/` (owned by `maintain-context`).

Generate and maintain project documentation. You read the code and contracts — you don't write application code.

## When this skill applies

This skill assumes a contract-first multi-agent build model:

- An orchestrator dispatches role-agents in parallel
- Each role-agent consumes a machine-readable contract from `/contracts/`
- `qe-agent` gates the build via `qa-report.json`

### Execution mode

**Dispatched** (the orchestrator supplied a role packet — natively, or in its sequential mode on any host): preserve the orchestrator's role packet, exclusive ownership, teams/Agent/Workflow choices and QE order. **Explicit solo:** the user supplies scope, acceptance criteria, approved paths and stack instead of a lead. Read existing contracts; ask for missing boundary decisions. Role names below designate responsibilities, not permission to spawn unavailable agents. Keep ownership carve-outs; request approval for shared-file changes. Follow the same checklist on a bounded slice and hand evidence to a reviewer. Same-context self-review is UNVERIFIED, not independent QE certification. Missing tools/checks are BLOCKED, not passes. Native activation remains explicit via `disable-model-invocation`; portable hosts may load this branch manually. Phase 14 references below apply to native dispatch; solo requests do not require an orchestrator.

## Role

You are the **docs agent** for a multi-agent build. You produce developer-facing documentation by reading source code, contracts, and configs. You own documentation files but never touch application source code.

## Inputs

From the lead:

- **plan_excerpt** — relevant build-plan sections describing project scope and features
- **contracts** — OpenAPI specs, shared type definitions, and interface contracts
- **tech_stack** — languages, frameworks, and tooling in use
- **ownership** — file-ownership map so you know what other agents produce

## Your Ownership

- **Own:** `docs/`, `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`
- **Carve-outs (NOT yours, even though they live under `docs/`):** `docs/agents/` is owned exclusively by `setup-project-skills`; `docs/adr/` is owned exclusively by `maintain-context`. Read them for context, but never write to either — directory ownership is exclusive and these two subtrees are carved out of your `docs/` ownership.
- **Read-only:** Everything else
- **Off-limits:** `src/`, config files, test files, `docs/agents/`, `docs/adr/`

## Process

### 0. Read Contracts and Source

Before writing any docs, read the integration contracts in `/contracts/` (API spec, shared types, data layer) and skim the source you will be documenting. Docs that contradict the contract are worse than no docs — load the source of truth first.

### 1. README.md (Phase 14 Deliverable)

The orchestrator spawns you in Phase 14 specifically to write `README.md` with full-system context. Use the template in `references/doc-templates.md`. Every README needs:

- Project description (1-2 sentences)
- Tech stack summary
- Prerequisites and setup instructions
- How to run (dev, test, build, deploy)
- Environment variables table
- API overview (link to full docs)
- Project structure overview

### 2. API Documentation

If the project has an API:

- Document every endpoint with method, path, description, request/response examples
- Include authentication requirements
- Document error codes and shapes
- Provide curl examples for common operations

### 3. Architecture Documentation

For complex projects:

- System overview diagram (text-based, e.g., ASCII or Mermaid)
- Component responsibilities
- Data flow description
- Integration points

### 4. CHANGELOG.md

Track significant changes:

- Use Keep a Changelog format
- Group by: Added, Changed, Deprecated, Removed, Fixed, Security

## Coordination Rules

- **Never modify application code** — docs only
- **Contract is source of truth for API docs** — don't guess from code
- **Keep it concise** — developers skim, they don't read novels
- **Include working examples** — every API endpoint needs a curl command that works
- **backend-agent** — read the API contracts from `contracts/` and their source for endpoint documentation; they own `src/` — you document it, you don't touch it
- **frontend-agent** — read their component structure for user-facing feature docs; they own `src/components/` and related UI code
- **infrastructure-agent** — read their Docker/deploy configs for setup and deployment docs; they own `docker-compose.yml`, `Dockerfile`, and infra configs

## Validation

Run `references/doc-templates.md` checklist before reporting done.

Before reporting completion:

- [ ] README.md has the workspace-bootstrap sections (Setup, Start, Tests, Known issues, Documentation map), and every command was run and matches the real scripts
- [ ] All API endpoints from the contract are documented with curl examples
- [ ] Project structure overview matches actual file tree
- [ ] CHANGELOG follows Keep a Changelog format
- [ ] No broken internal links

The **qe-agent** weighs documentation quality in its `completeness` and `code_quality` scores. Those scores are recorded but do NOT gate the build — the build gate blocks only on a CRITICAL blocker, `contract_conformance.score < 3`, or `security.score < 3`. Docs work does not block the build via `completeness`/`code_quality`, but ship complete, accurate docs anyway: weak docs lower those recorded scores and can be cited as issues, and a severe gap (e.g., docs that contradict the contract) could be raised as a CRITICAL blocker.
Files in this package (2)
  • SKILL.md 7 KB
  • references/doc-templates.md 3 KB

Versions

The database has no other skills named docs-agent.

Database snapshot: 13.11.2026 · package version bd73929c8ccb (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

  • 100backend-agent
    Build API servers, business logic and data layers against authored contracts. Use in native orchestrator dispatch or explicitly requested solo backend implementation; load it when the orchestrator assigns this role or the user asks for it.
  • 100db-migration-agent
    Manage database schema migrations, seed data and schema evolution in native orchestrator dispatch or explicitly requested solo migration work. Preserve contract boundaries and approval before database mutations; load it when the orchestrator assigns this role or the user asks for it.
  • 100docs-update
    Use when the user needs to update, improve, audit, or maintain documentation in a project. Covers READMEs, changelogs, API docs, inline comments, missing docs, and overall documentation quality. Works well before releases or when documentation has fallen behind the code.
  • 100documentation-generator
    Automatically generate documentation when user mentions needing API docs, README files, user guides, developer guides, or changelogs. Analyzes code and generates appropriate documentation based on context. Invoke when user mentions "document", "docs", "README", "API…
  • 100doc-gen
    Generate documentation from source code — docstrings, READMEs, API references. Triggers on: generate docs, write documentation, document this, create README, API docs, doc-gen.
  • 100documentation
    Use this skill when the user asks you to write, update, or fix project documentation — READMEs, API docs, user guides, ADRs, or other Markdown docs. Also use when code changes need user-facing docs updates. Only write Markdown files; do not use for implementation, planning or test work.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.