Docs — project documentation
Generate and improve documentation as a landing-page README plus detailed pages in docs/. Everything that changes an
existing file is shown first and written only after an explicit yes.
Output rendering. Report and summary templates in code blocks below show structure only. Render them as Markdown —
headings, tables, bold labels, bullet lists — never wrapped in a code block (it shows as a monospace wall); keep paths
and commands in inline code. The closing Blocked on me: / Changed: / Found: lines become three bullets with bold labels.
Next step (mandatory). End the answer with a Next: line that names the step in a few words, then put the exact
command on its own, on the following line(s), inside a fenced code block with no language tag — the app shows a
copy button on a code block. Never tag it ```bash: a /keystone:* command is not a shell command, and the bash tag
adds a Run button that would fail. When nothing runs now, write Next: nothing now — waiting for <event> and put the
later command in that fenced block. Never end on a caveat or an open-ended question. A path in that command must open
from the session's working directory, because the next session (after /clear) starts there: a file inside it →
its path relative to it; a file you wrote in another repository or folder (after cd) → its absolute path.
Choice at the end (menu). When the stage leaves more than one sensible next step, end with one AskUserQuestion
menu instead of a single command, as AI Factory does: 2–4 options, the recommended one first with (Recommended),
and Stop here last. Print the report and the summary first, then ask. On a pick, carry it out: an option that
continues in this session runs now — for another Keystone skill, read ${CLAUDE_SKILL_DIR}/../<skill>/SKILL.md and
follow it with the chosen arguments; an option that needs a clean session (/clear first), an irreversible external
step (push, deploy, production) or a human action outside the chat is not run — it becomes the Next: command. With
one sensible next step, or when AskUserQuestion is unavailable (claude -p, CI), skip the menu. The Next: line
always closes the answer.
Status colors. In the chat (not in files other tools parse) mark statuses so they scan at a glance: ✅ ok / done · ⚠️ not proven / warn / partial · ❌ missing / wrong / fail · ⏸️ BLOCKED · 🔄 in progress · ⏳ pending; verdicts and gates 🟢 PASS / pass · 🟡 PASS-UNPROVEN / warn / not proven · 🔴 FAIL / fail · ⚪ n/a; severity and risk 🔴 critical / High · 🟠 high · 🟡 medium / Medium · 🟢 low / Low. The marker goes before the word; the word stays.
File links. Every file you write or point the user to lives inside the session's working directory
(the folder Claude Code runs in — in a worktree, the worktree, never the main checkout), and its link is relative to
that directory: [intent.md](wordpress-plugin/x/docs/keystone/<task>/intent.md), not relative to a nested repo or a
subproject. Check the link before showing it: the app opens links only from the working directory. A file outside
it (Claude's memory under ~/.claude, another repository, a temp folder) is never a link — the app cannot open
it and shows "file not found", and a path in code becomes such a link too: give its absolute path as plain
text, without backticks. Link only a file you checked exists.
Core Principles
- README is a landing page, not a manual. ~80-120 lines. First impression, install, quick example, links to details.
- Details go to
docs/. Each file is self-contained — one topic, one page. A user should be able to read a single doc file and get the full picture on that topic. - No duplication. If information lives in
docs/, README links to it — does not repeat it. Exception: the installation command can appear in both (users expect it in README). - Navigation. Every doc file has a header line with prev/next links following the Documentation table order:
[← Previous Page](prev.md) · [Back to README](../README.md) · [Next Page →](next.md). First page has no prev link; last page has no next link. Every page ends with a "See Also" section linking to 2-3 related pages. - Cross-links use relative paths. From README:
docs/workflow.md. Between doc pages:workflow.md. - Scannable. Use tables, bullet lists, and code blocks. Avoid long paragraphs. Users scan, they don't read.
Step 0 — Project context
Read, in this order, what exists: CLAUDE.md and .claude/CLAUDE.md; docs/architecture.md; .claude/rules/**/*.md;
AGENTS.md. MUST/MUST NOT lines there are project rules — also for the docs you write (language of
the existing README wins; no invented features).
Explore the code: package.json, composer.json, requirements.txt, go.mod, Cargo.toml, the src/ layout,
existing docs, comments, API endpoints, CLI commands. Detect real facts; never invent them.
Glob the project root for *.md (not node_modules/, .git/, .claude/, docs/keystone/): CHANGELOG.md,
CONTRIBUTING.md, ARCHITECTURE.md, DEPLOYMENT.md, SECURITY.md, API.md, SETUP.md, DEVELOPMENT.md,
TESTING.md… Record each file, its size and a one-line summary — used in Step 2.
Step 1 — Mode
update <files|topics>→ Step 5 (targeted update). The argument is a list of changed files or topics.--web→ also build an HTML site from the pages (Step 6).- Otherwise determine the state:
State A: No README.md → full generation (README + docs/)
State B: README.md exists, no docs/ → analyze README, propose a split into docs/
State C: README.md + docs/ exist → audit and improve (with --web: ask "HTML only / audit and improve first / audit only")
Step 2 — Scattered markdown files
If Step 0 found root-level .md files, propose consolidating them into docs/:
| Root file | Target | Move or merge |
|---|---|---|
CONTRIBUTING.md |
docs/contributing.md |
Move |
ARCHITECTURE.md |
docs/architecture.md |
Move |
DEPLOYMENT.md |
docs/deployment.md |
Move |
SETUP.md |
docs/getting-started.md |
Merge (append) |
DEVELOPMENT.md |
docs/getting-started.md or docs/contributing.md |
Merge |
API.md, TESTING.md, SECURITY.md |
docs/api.md, docs/testing.md, docs/security.md |
Move |
Stay in root: README.md, CHANGELOG.md, LICENSE*, CODE_OF_CONDUCT.md. Show the list (file, lines, summary, suggested
action) and ask: apply all / pick which / skip. Never force-move files. When applying: create the target with the
navigation header and "See Also", do not delete the originals, add the page to README's Documentation table, fix
links that pointed at the old file, remember the list for Step 4.
Step 3 — Generate or improve
State A. Pick topics: getting-started.md always; architecture.md (clear modules/layers), api.md (endpoints),
configuration.md (env vars, config), deployment.md (Dockerfile/CI), contributing.md, security.md, testing.md,
cli.md when they apply. Show the list and ask: generate all / pick / add topics. Then write README
(title, tagline blockquote, 2-3 sentence description, Quick Start with real commands detected from the package manager,
3-6 Key Features, one real Example, Documentation table, License — no long descriptions, no API reference, no config
details) and the approved pages (header, content, ## See Also). Content per page: getting-started = prerequisites,
steps, first run, expected output, next steps; architecture = overview, directory structure, patterns, data flow;
api = base URL, auth, endpoints by resource, examples, errors; configuration = every variable with default.
State B. README over ~150 lines with no docs/: keep title, tagline, features, quick install, example, links; move
sections longer than ~30 lines on a single topic. Show the split plan and ask before writing; then verify no content was
lost — every old section exists somewhere.
State C. Audit: README length (<150 lines), missing topics, stale references to files/APIs that no longer exist,
navigation and "See Also", broken internal links, consistent format, standards gaps (table in
${CLAUDE_SKILL_DIR}/references/CHECKLIST.md, "Standards Compliance Check"). Present findings as ✅/⚠️/❌ with proposed
fixes and ask before applying.
Step 4 — Review (mandatory after any content change)
Read every generated/modified file and run both checklists in ${CLAUDE_SKILL_DIR}/references/CHECKLIST.md
(Technical, Readability — "New User Eyes"). Fix what fails before presenting the result; show a compact table with
✅/❌/⚠️. Skip only for "HTML only".
Moved files. After the review confirms the content is in docs/, ask whether to delete the originals: all / pick /
keep. Do NOT auto-delete. Before any deletion verify the target contains everything, then show git status so the
user can restore with git checkout.
Pointers. If AGENTS.md or CLAUDE.md exists and has a documentation list/table, synchronize it with the final set
of pages (README first, then docs in Documentation-table order, descriptions under 10 words), after showing the diff. If
neither has such a list, do nothing. This skill does not generate AGENTS.md.
Step 5 — update <files|topics>
Used after a code change (by /keystone:implement when Settings say docs — yes, or by hand).
- Map the argument to pages: grep
docs/and README for the changed file names, symbols, commands, env vars and flags; pages that describe a topic named in the argument. - Read only those pages and the changed source. Fix what became wrong or missing: commands, options, env vars, paths, examples. Add a short section where a new feature has no home; create a new page only if no page fits, and then add it to the Documentation table and navigation.
- Leave everything else untouched — no restructuring, no consolidation, no README rewrite beyond the affected lines.
- Show the diff and ask for a yes before writing (when called from implement: the human already approved the plan, but docs edits are still shown as a diff first).
- Run the Technical checklist on the touched pages only. Report
docs: updated <pages> | nothing to update.
Step 6 — HTML (--web)
mkdir -p docs-html; for README and every docs/*.md produce a page (README.md → index.html, .md links →
.html, a nav bar); no template file is shipped — keep the markup plain and self-contained. Add docs-html/ to
.gitignore (shown first). Print the tree and open docs-html/index.html.
Rules
- Always ask before changing existing documentation — show the plan or diff first.
- Never delete content without moving it somewhere else.
- Detect real project info — don't invent features; read the manifests.
- Use the project's language — a Russian README gets Russian docs.
- Preserve existing badges and logos.
- Ownership:
README.md,docs/*and the documentation pointers inAGENTS.md/CLAUDE.mdonly. Never touchdocs/keystone/, rules, or code.
Report
Blocked on me: what needs the user's yes · Changed: files written · Found: problems left (broken links, stale
sections). Write none for an empty line. Suggest /clear or /compact if the context is heavy.