| name | documentation-writing |
| description | Creates and maintains project documentation in .claude/skills/project-knowledge/:
interview, initial Project Knowledge, audit, edit, consistency, and feature finalization.
Use when: "заполни документацию проекта", "опиши проект", "создай Project Knowledge",
"проведи интервью по проекту", "проверь документацию", "обнови документацию",
"аудит документации", "plan a new project", "fill project documentation",
"check docs", "audit documentation", "update docs"
For reading docs or explaining concepts, read project-knowledge skill directly.
|
Documentation Management
Create and maintain .claude/skills/project-knowledge/ from the evidence source the user named.
Outside Feature Finalization Mode, follow
create-project-knowledge.md when the user starts or
continues initial documentation and either its interview is still in progress or Project Knowledge
is missing, still a template, or only partially filled. Apply
project-knowledge-structures.md for content ownership
and structure. After writing, run the manual sync and continue at Documentation Review.
When the user explicitly asks to reorganize existing Project Knowledge, apply
project-knowledge-structures.md. Ordinary updates
preserve the filled structure already in use.
Manual Project Documentation Sync
Project documentation source of truth is Claude-side: CLAUDE.md and .claude/**.
Codex-side AGENTS.md and .codex/** are generated runtime files.
No scheduled job performs this conversion. The agent that changes the Claude source runs the
matching command immediately and reviews the generated result before finishing the task.
After changing a project CLAUDE.md or any project-local .claude/** file, immediately run:
~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply
If sync reports a conflict, stop and report it. Commit generated project .codex/** / AGENTS.md
changes with their Claude sources, except .codex/.sync/**, which is host-local runtime state.
When an approved deletion or rename produces orphaned managed outputs, verify that every reported
path corresponds to that approved source change, then remove those generated leftovers with:
~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply --prune --confirm-delete
If the orphan list contains anything else, stop and report it instead of pruning unrelated output.
Nested Agent Workspaces
Some projects keep an agent workspace under a subdirectory (for example
nested-workspace/.claude/**) while the repository root exposes selected skills or
agents through symlinks in root .claude/**. In that case, sync both levels:
~/.claude/scripts/sync-to-codex.sh --project "$PWD/nested-workspace" --apply
~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply
Verify root .codex/agents / .codex/skills include every root-exposed agent or skill. A
generated file existing only inside the nested workspace is not enough when the root runtime
must invoke it. Treat .codex/.sync/** as host-local evidence: do not commit or synchronize it.
Documentation Principles
The reader should understand the project's purpose, structure, decisions, and operation without
reconstructing them from code. Record durable project-specific facts: purpose and business logic;
architecture, components, and their relationships; lasting agreements, decisions, and why those
decisions were made; security rules and configuration names; deployment, operations, monitoring,
recovery, where key code lives, and operational details an agent cannot infer from configuration
alone.
Do not list functions, classes, local control flow, or implementation details that can be read from
code. Treat an important non-obvious rule that applies only to a particular code path as code-owned:
keep it out of Project Knowledge, and change a nearby code comment only when the user also requested
source changes.
Keep generic framework, Git, Linux, SSH, Docker, journalctl, and systemctl explanations out of
Project Knowledge. For operations, preserve facts such as host, user, non-default port, SSH alias,
service or container name, log location, monitoring URL, environment-variable names, and emergency
recovery behavior. Store an exact command only when the procedure is non-standard and cannot be
recovered from project configuration.
Use source links instead of code snippets or pseudocode. Each fact has one owner file; update the
existing section and cross-reference it elsewhere instead of appending a duplicate. patterns.md
contains project-specific conventions, not general implementation advice.
Plans, user specs, tech specs, handoffs, and other work/ artifacts are evidence, not owners of
current project state. Keep changing inventories in their authoritative registry, configuration,
or runtime source; Project Knowledge records the durable rule, not current counts or members. If a
Project Knowledge claim depends on a completed work artifact, correct that boundary instead of
expanding the artifact.
File size alone is not a finding. Report a size-related issue only when evidence demonstrates
duplication, stale content, implementation-level detail, or a structure that prevents useful
selective loading.
Phase 1: Select the Evidence Source
Use the narrowest mode that matches the user's request:
- One current change: inspect the changed lines, the files they affect, and related callers or
contracts needed to understand the durable result.
- Named commit or range: inspect exactly that commit or range plus the related files needed to
interpret it.
- Recent history: when the user asks for the last N commits, inspect those N commits and their
resulting current code.
- Full update or audit: inspect current code, all Project Knowledge, and
CLAUDE.md.
- Specific documentation edit, consistency check, or status: inspect the named section and the
documentation it can contradict.
- Feature finalization: use this mode only when the user explicitly asks to finish a feature
(including
/done) and provides or identifies work/{feature}/.
Do not search for user-spec.md or require it outside feature-finalization mode. A normal
"update documentation" request does not archive work or create a finalization commit.
Phase 2: Establish Durable Facts
- Read the selected evidence and current target documentation before editing.
- Trace names, versions, service boundaries, data model, environment variables, deployment
triggers, and operational facts to current sources. For full audits, also check placeholders,
duplication, stale links, generic tutorial content, inconsistent terminology, and facts that no
longer match the code.
- If Project Knowledge has no writable owner in the selected non-creation mode, report that no
documentation target exists. Feature finalization keeps its explicit missing-documentation
behavior below rather than starting an initial project interview from feature evidence.
Phase 3: Update or Report
- For an edit/update request, integrate facts into existing sections and update any directly
contradicting references.
- For an audit, consistency check, or status request, report evidence-backed issues without
changing files unless the user also asked for fixes. Status classifications are filled, partial,
template, or missing; size alone does not determine status.
- After changing a project
CLAUDE.md or project-local .claude/**, run the manual sync described
above. For a nested workspace, sync the nested source first and the repository root second.
Documentation Review
- Run no more than two review waves. After documentation edits, run wave 1 with a fresh
documentation-reviewer with no model override. Give it the complete touched documents, the
selected evidence boundary, related code and contracts, and the user's request. It returns its
JSON result directly. Include reviewers required by other active skills in these same waves
instead of starting a separate wave sequence.
- Review findings are diagnoses, not a work queue. Check the evidence and exact correction; apply
only an authorized local correction to agreed normal documentation. If the scenario is rare or
unagreed, or the correction adds behavior, state, entities, contracts, dependencies,
architecture, or material complexity, reject it with a short reason or ask the user before
editing.
user_decision_required: false does not replace this check. Surface unrelated
pre-existing defects without changing them.
- If an accepted correction changes the reviewed documentation, run wave 2 with a fresh reviewer.
Stop after a clean wave or when no authorized correction changes the documentation.
- After wave 2, do not launch another reviewer automatically. Make only remaining local corrections
inside the requested documentation change, run the applicable direct checks and manual sync, and
show the user any remaining findings or required decisions.
Feature Finalization Mode
- Read
user-spec.md, decisions.md when present, the implementation, and the relevant Git
history. Compare the implemented result with the agreed spec.
- If the feature is evidently incomplete, explain the concrete gap and ask whether to continue
finalization.
- Update only affected Project Knowledge through Phases 2-3 and Documentation Review. If Project
Knowledge is missing, report that the documentation update was skipped and continue archival
and finalization.
- Remove active Project Knowledge and backlog links that treat
work/{feature}/ as a current
source; do not add current operational inventory to completed artifacts.
- Move
work/{feature}/ to work/completed/{feature}/ after documentation review.
- Commit the Project Knowledge changes and archive move with a concise documentation commit, then
report the updated files and completed-feature path.
This is the only mode that reads feature artifacts by default, archives a feature, or creates the
finalization commit.
Agent Entry Point
Keep CLAUDE.md minimal: project name, one-line description, reference to the Project Knowledge
skill, backlog path, and default branch. Detailed project information belongs in Project Knowledge.
Template: ~/.claude/skills/project-initialization/assets/new-project/CLAUDE.md.
Self-Verification
