# Project Docs

> Guide for creating and maintaining project documentation (README, guides, API specs). Emphasizes doc/code synchronization, consistency checks, and use of the docs-excellence-architect subagent.

- Skill: `s-hiraoku/project-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add s-hiraoku/project-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/s-hiraoku/project-docs/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: s-hiraoku (https://skillmd.com/u/s-hiraoku)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/s-hiraoku/project-docs

---


# Project Docs

This skill helps you keep documentation correct, minimal, and aligned with the codebase.

## What To Document

- User-facing behavior changes
- New CLI flags, environment variables, configuration changes
- Protocol/API changes, request/response shapes
- Operational guidance (troubleshooting, limitations, safety workflows)

## Doc Update Workflow

1. Identify the code changes and their user-visible effects.
2. Locate the canonical docs (README vs guides vs references).
3. Update docs with minimal churn, matching existing style.
4. Cross-check examples against current CLI help / code.
5. Run relevant tests and include them in the update note.

## Consistency Checks

- Option names match actual CLI flags (`--help` output if available).
- Defaults are correct and stated once (avoid duplication across docs).
- Examples are runnable and do not rely on project-private paths.
- Terminology is consistent across README/guides/references.

## Subagent Invocation (docs-excellence-architect)

Use the Task tool to delegate a doc-focused review to a specialized subagent:

- subagent_type: `docs-excellence-architect`

Provide:

- The doc files to touch
- The code changes that need to be reflected
- The desired doc structure (where each piece should live)

Example prompt:

```
Review and update docs for the following changes:
- <change 1>
- <change 2>
Target files:
- README.md
- guides/*.md
- docs/*.md
Constraints:
- Minimal churn, match local style
- Ensure examples are accurate and consistent
Deliverables:
- Proposed edits (diff-style)
- A checklist of what was verified
```

## Maintenance Guidelines

- Prefer short sections with concrete examples.
- Avoid repeating the same definition in multiple files.
- When a doc becomes a reference, move it to a single canonical location and link to it.