hyper-docs-sync
Skill5 starsChanged 48 days agoMITView on GitHub
Use after implementation changes documented API, schemas, CLI flags, or architecture — before docs go stale. Also when the user invokes /hyperclaude:hyper-docs-sync. Syncs docs to the current code state.
In this repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cc-changelogSkill
- codex-changelogSkill
- hyper-autoSkill
- hyper-code-reviewSkill
- hyper-docs-loopSkill
- hyper-docs-reviewSkill
- hyper-implement-loopSkill
- hyper-implementSkill
- hyper-interviewSkill
- hyper-memorySkill
- hyper-plan-loopSkill
- hyper-plan-reviewSkill
- hyper-planSkill
- hyper-recapSkill
- hyper-researchSkill
- hyper-setupSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
After non-trivial implementation that changes documented API, CLI flags, data models, or architecture.
- Distinctive: line 36
Use the Bash tool. Concrete commands per scope:
- Very specific: line 45
Look for a markdown table where one column header matches /code|source|file/i (case-insensitive) and another matches …
- Distinctive: line 57
If no conforming table is found, note this in the summary and proceed with heuristic fallback.
- Distinctive: line 61
Use the extracted table (exact path or glob match against changed file paths).
- Very specific: line 63
Heuristic fallback: when no table or no table match: name similarity (e.g., changed src/auth/session.ts → look for docs/auth.md if it …
- Distinctive: line 90
Run git status and git diff --stat to summarize what changed in docs.
- Very specific: line 94
No change needed: docs/foo.md — code change didn't affect this doc's claims
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
hyper-docs-sync
Documentation sync gate. Reads recent code changes, maps them to documentation files via the project's mapping table (or heuristic fallback), and dispatches the documenter agent to update each affected doc — creating new docs as needed.
When to use
- User typed
/hyperclaude:hyper-docs-sync. - After non-trivial implementation that changes documented API, CLI flags, data models, or architecture.
When to skip
- Pure refactors with no behavioral change.
- Changes already reflected in docs.
How to invoke
Invocation argument: $ARGUMENTS
Narrow contract (same shape as hyper-code-review):
| Pattern | Meaning |
| Empty | Changes since main (git diff main...HEAD) |
Literal uncommitted | Staged + unstaged + untracked working-tree changes |
7-40 hex chars matching ^[0-9a-f]{7,40}$ | That specific commit (git show --format= --patch <sha>) |
^vs (.+)$ where the rest matches ^[A-Za-z0-9._/-]+$ | Changes since that ref (git diff <ref>...HEAD) |
| Anything else | Tell user the contract above, ask to clarify, STOP. |
Step 1 — Resolve changed files + their diffs
Use the Bash tool. Concrete commands per scope:
- Empty (
vs main):git diff --name-only main...HEADfor the file list; per-file diffs viagit diff main...HEAD -- <file>. uncommitted:git status --porcelainto enumerate staged + unstaged + untracked. For staged/unstaged:git diff HEAD -- <file>. For untracked files (no diff possible): read content directly via Read tool, treat as "new file added."- Hex SHA:
git show --format= --patch <sha>(NOT--stat— you need actual diff content). vs <ref>:git diff --name-only <ref>...HEAD+ per-filegit diff <ref>...HEAD -- <file>.
Step 2 — Read the project's CLAUDE.md and/or AGENTS.md (if either exists)
Look for a markdown table where one column header matches /code|source|file/i (case-insensitive) and another matches /doc|docs|documentation/i. Extract the mapping into a structured form.
The canonical recommended header names are Code and Docs. Example (commentarium-style):
| Code area | Docs |
|---|---|
| API surface | docs/api.md |
| Firestore schema | docs/data-model.md |
| Auth flows | docs/auth.md |If no conforming table is found, note this in the summary and proceed with heuristic fallback.
Step 3 — Map changed files to docs
Use the extracted table (exact path or glob match against changed file paths).
Heuristic fallback when no table or no table match: name similarity (e.g., changed src/auth/session.ts → look for docs/auth.md if it exists).
Confidence rule: dispatch the documenter agent ONLY for matches that meet ONE of:
- Mapping table match (any confidence — table is authoritative).
- Heuristic match where the changed file's stem appears in the doc filename (e.g.,
auth.ts→auth.mdqualifies;session.ts→auth.mddoes NOT qualify by this rule alone).
Lower-confidence heuristic candidates (no clear name overlap) are REPORTED in the summary as skipped — possible candidates: X, Y so the user can manually invoke documenter if appropriate. Avoids unsafe edits driven by guesswork.
Step 4 — Aggregate per doc
Group all changed files + their diffs that map to the same target doc. Never dispatch the documenter agent more than once per target doc; aggregate first.
Step 5 — Dispatch documenter agents in parallel
Step 4 aggregated to one dispatch per target doc, so the documenters edit disjoint files. Issue every subagent_type: hyperclaude:documenter Agent call in a SINGLE message, then wait for all of them before Step 6 — the report reads the tree once, after every edit has landed.
Single affected doc → dispatch it alone with run_in_background: false and consume the result inline.
Each prompt MUST include:
- The target doc path
- Whether the doc EXISTS or needs to be CREATED: check
[ -f "<target>" ]via Bash before dispatching. If absent, dispatch in CREATE mode (the agent writes a new file with a sensible scaffold). If present, dispatch in UPDATE mode (agent edits in place). Make this explicit in the dispatch prompt. - The aggregated diff/excerpts for changed code mapped to this doc
- The mapping rationale (table match vs heuristic match)
Step 6 — Report
Run git status and git diff --stat to summarize what changed in docs. Report per-doc:
- Updated:
docs/api.md— sections X, Y modified - Created:
docs/new-feature.md— new file scaffolded from<code path> - No change needed:
docs/foo.md— code change didn't affect this doc's claims - Skipped (low confidence):
docs/bar.md— possible heuristic match, manual review suggested
If the project has no mapping table, end the report with a suggestion: "Tip: add a Code | Docs mapping table to your CLAUDE.md so future runs are precise. Based on this run's matches, here's a starter table you can paste:" followed by the inferred table.
Output contract
This skill produces no .hyperclaude/ artifacts; the doc edits/new files ARE the artifact. The hyper-docs-review gate is the follow-up Codex critic for accuracy verification.
Distinction note
/hyperclaude:hyper-docs-sync— Claude EDITS docs to match code (this skill)/hyperclaude:hyper-docs-review— Codex CRITIQUES docs for accuracy/hyperclaude:hyper-code-review— Codex critiques code diffs/hyperclaude:hyper-plan-review— Codex critiques plans
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

