agentleFS
zeikarzeikar/hyperclaude/skills/hyper-docs-sync/SKILL.md

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.

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
  1. Distinctive:

    After non-trivial implementation that changes documented API, CLI flags, data models, or architecture.

    line 13
  2. Distinctive:

    Use the Bash tool. Concrete commands per scope:

    line 36
  3. Very specific:

    Look for a markdown table where one column header matches /code|source|file/i (case-insensitive) and another matches …

    line 45
  4. Distinctive:

    If no conforming table is found, note this in the summary and proceed with heuristic fallback.

    line 57
  5. Distinctive:

    Use the extracted table (exact path or glob match against changed file paths).

    line 61
  6. Very specific:

    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 …

    line 63
  7. Distinctive:

    Run git status and git diff --stat to summarize what changed in docs.

    line 90
  8. Very specific:

    No change needed: docs/foo.md — code change didn't affect this doc's claims

    line 94

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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):

PatternMeaning
EmptyChanges since main (git diff main...HEAD)
Literal uncommittedStaged + 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 elseTell 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...HEAD for the file list; per-file diffs via git diff main...HEAD -- <file>.
  • uncommitted: git status --porcelain to 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-file git 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.md qualifies; session.ts → auth.md does 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.