Clickable prototype in 48h

Developer workflow

syncdocs

For any repository: documentation kept in step with the code. Versions, dependencies, commands, project structure and feature claims in README.md, CLAUDE.md, AGENTS.md and docs/ re-read from the code before they are written, the prose left alone, unverifiable claims flagged.

Repository
timerise-ai/syncdocs
Released
October 25, 2026
Install the skill
npx skills add timerise-ai/syncdocs
Current release
v0.1.2
Reference docs
4
Non-negotiables
7
License
MIT

The problem

What problem does syncdocs solve?

Documentation goes stale one fact at a time. A dependency is upgraded and the README still names the old major. A script is renamed and the setup steps still call it. A folder moves and CLAUDE.md still points the next agent at the old path, so the agent works from a map of a project that no longer exists.

Asking an agent to "update the docs" makes it worse. It rewrites prose nobody asked it to touch, fills gaps with plausible guesses and quietly changes the tone of the whole file.

This skill gives the agent the documentation pass we run on our own repositories: every version, command, path and feature claim is re-read from the manifest, lockfile, scripts or files before it is written, one fact gets one value across every doc, the human-written prose and section order stay as they are, and anything the code cannot confirm goes to you in the report instead of into an edit.

The tool

What does the skill do?

This skill adds no module to your app: your agent runs it as a tool. What syncdocs does:

  • 1. Documentation kept in step with the code
  • 2. Versions
  • 3. Dependencies
  • 4. Commands, project structure and feature claims in README.md
  • 5. CLAUDE.md, AGENTS.md and docs/ each re-read from the manifest
  • 6. Lockfile, scripts and files before it is written
  • 7. Human prose
  • 8. Tone and section order left alone
  • 9. Unverifiable claims flagged rather than guessed
  • 10. A report of changed
  • 11. Verified and flagged

Provenance

Where do the rules come from?

This skill was written by the engineer who maintains it, from the documentation passes they run on their own repositories. What it carries holds by construction: every value written is one read in the same session from a manifest, lockfile, script or file; a doc keeps its own precision, so a major stays a major; one fact has one value across every doc; no doc is created and the changelog is never edited; and the report separates what changed, what was verified and what needs a decision. `references/provenance.md` has the record.

The engineering ledger for the person editing this skill. It separates what the audit of the earlier implementation changed and how the skill now holds it, what was kept deliberately and why it is safe, and what was designed in the skill and has never run. Read it before simplifying anything; add an entry for anything you change.

The ledger separates what the audit changed, what was kept on purpose, and what has not run in production yet.

  1. Fixed

    • A tool list only one agent reads The frontmatter carried allowed-tools: Bash, Read, Grep, Glob, Edit. It held the rule against creating missing docs only in Claude Code, by leaving Write out; another agent ignored the field and the rule with it. Now: the frontmatter has name and description only, and "Never create a doc that does not exist" is a hard rule in SKILL.md, read by every agent.
    • An unconditional commit The process ended "then commit only the doc files", whatever the user had asked. A user who wanted to review the diff got a commit instead, and an unattended run left an empty working tree to inspect. Now: the last hard rule commits only when the user has not asked to review first, and /syncdocs check makes no edit at all (reporting.md, Check mode and the user's limits).
    • Version precision left open "package.json is the source of truth for versions" did not say whether a doc's version is the declared range or the resolved one, so the same doc could be synced to ^16.2.0, 16 or 16.2.12. Now: critical fact 1 and the precision table in ground-truth.md, which keep the doc's own precision.
    • No ground truth for a repository without a manifest The ecosystem table ended at "the manifest the repo actually uses", which a markdown-only repository does not have. Now: critical fact 6 and The project's own version in ground-truth.md: the newest changelog section checked against the newest tag, with a disagreement reported to bumpv rather than resolved.
    • Two answers for a command with no script Found by the 0.1.0 agent evals. Commands in ground-truth.md said an undefined command with no same-purpose script is flagged and kept; Edit in place in syncing.md and critical fact 2 said it is removed. One agent kept npm test and flagged it, another removed it, and a third swapped npm run lint for npm run build and wrote a new sentence saying no lint or test scripts exist. Now: both references and critical fact 2 say the same thing: the command is stale, it takes the name of a script of the same purpose or is removed from its sentence, nothing stands in for it, and each swap or removal is its own line under Changed. Hard rule 2 names sentences and commands among what is never added, and quick start step 4 says the three-list report, one line per fact, is the final message. The 0.1.1 evals then showed one agent grouping several facts per Changed line, read from the permission to group routine items; reporting.md now limits grouping to Verified accurate and gives Changed the shape file: old to new (source).
Read the full record in provenance.md ›

Non-negotiables

What are the 7 rules the module never breaks?

Every module built from this skill holds these, whoever builds it. The same list is in the skill's README and SKILL.md, so the agent reads it before it writes a line.

  1. Ground truth comes from the code, never from the docs or from memory.

    A doc's own value is the claim under test, so it cannot also be the evidence; every value written is one read in the session.

  2. Only facts change.

    Prose, tone and section order are the author's judgement, which the code cannot check; a targeted edit keeps the diff reviewable line by line, and no sentence or command is added to fill a gap.

  3. No doc is created.

    A missing file is a decision about what the project documents, so it is offered in the report and not written.

  4. CHANGELOG.md is never touched.

    bumpv writes it from the commits; two writers would contradict each other, and the docs: commit is the sync's own record.

  5. An unverifiable claim is flagged, never silently kept or deleted.

    The code cannot tell a removed feature from one that was never built, so the report names the claim and where it looked.

  6. Nothing stale means no edit and no commit.

    A cosmetic change made to justify a commit is a change nobody asked for.

  7. Only doc files are committed, only when the user has not asked to review, with no AI attribution.

    The message is fixed so a sync is recognisable in any history, and git log -1 --format=%B verifies it.

Fit

When should you use it, and when not?

Use it for

  • After a change to versions, dependencies, scripts, structure or features, when the docs may no longer match; before a release; or when asked to check whether the docs are accurate.
  • The user's words override the default: "do not commit", "I want to review the diff" or "just tell me" mean no commit, or no edit, exactly as asked. A repository named but not present is cloned from its public URL into a scratch directory; that clone and the package registry are not external services in an eval's sense. Leave a working directory that is not the target as it was, apart from a report file if asked.

Not for

  • Writing the changelog or bumping a versionInsteadbumpv
  • Committing with the house conventionsInsteadcommit
  • Checking the code against the docs as the specInsteadcode-audit
  • Writing a README, CLAUDE.md or guide that does not exist yetInsteada documentation skill
  • Hardening a skill from its agent evalsInsteadskill-eval-loop

Install

How do I install it?

One command. The skills.sh CLI installs the skill into every skills-compatible agent it finds.

$ npx skills add timerise-ai/syncdocs

Claude Code

Invoke with /syncdocs

Codex CLI

Invoke with $syncdocs

Gemini CLI

Invoke with /skills

Name the agents instead with -a, for example npx skills add timerise-ai/syncdocs -a claude-code -a codex. Or clone the repository into your agent's skills folder. Nothing in it is agent-specific.

What is inside the repository (11 entries)
  • SKILL.mdEntry point: the sync pipeline, the seam, critical facts, hard rules, invocation, quick start and reference directory
  • references/ground-truth.mdWhere each fact comes from per ecosystem: manifests, lockfiles, declared range or resolved version, the project's own version, commands, structure, features
  • references/syncing.mdDiscovering the docs, classifying every claim, editing in place, what each file syncs and leaves, consistency across files
  • references/reporting.mdThe changed, verified and flagged report, check mode and the user's limits, the commit with no attribution
  • references/provenance.mdThe engineering ledger: what the audit of the earlier implementation fixed, what was kept deliberately, and what was added here and never exercised
  • README.mdThis file
  • CHANGELOG.mdOne section per release, newest first
  • CLAUDE.mdThe editing conventions, for an agent editing this repository
  • LICENSEMIT
  • evals/The prompts a user types after installing (prompts.md) and one file per agent eval: the skill installed into an empty Next.js app, one prompt, no help, then type-checked, built and tested
  • .github/workflows/agent-eval.ymlThe caller of the index's reusable eval workflow, run on every published release and on a maintainer's dispatch

Recent releases

  1. v0.1.2October 25, 2026

    Fix release, from scoring the prompt-1 agent eval runs against 0.1.1.

  2. v0.1.1October 25, 2026

    Fix release, from scoring the prompt-1 agent eval runs against 0.1.0.

  3. v0.1.0October 25, 2026

    First release: the documentation sync restructured to the Timerise skill standard, with its ground truth, editing rules and report split into references.

SKILL.md ›README.md ›CHANGELOG.md ›

After installing

What do I tell my agent?

Say what you need in your own words; the skill supplies the how. These are starting points, and the ones we tested say how it went.

  1. Our docs are out of date. Save these three files at their paths first, then bring the docs in line with the code. Leave it uncommitted, I want to review the diff. README.md: # Acme Acme is our booking front end. It is built on Next.js 14 and React 18, and we keep it deliberately small. ## Getting started ```bash yarn install yarn dev ``` Run `npm run lint` before you push, and `npm test` for the unit tests. ## Structure - `src/app/`: the routes - `src/components/`: shared components ## Features - A dark mode toggle in the header - Server-rendered pages CLAUDE.md: # CLAUDE.md Next.js 14 app. Before finishing a task, run `npm run lint` and `npm run typecheck`. Routes live in `src/app/`. CHANGELOG.md: # Changelog ## [0.1.0] - 2026-01-10 - First version on Next.js 14.

    Gemini CLIBuilt, checks passCodex CLIBuilt, checks passClaude CodeBuilt, checks pass

  2. Clone https://github.com/timerise-ai/site-pin-gate into a scratch folder and check whether its README.md and CLAUDE.md still agree with its files and its changelog. Do not change that repository; write what you find to docs-check.md here.

Tested

How does it do in each agent?

We install the skill into an empty Next.js app, give the agent one of the prompts above and no further help, then type-check, build and run the tests it left behind. Nothing is fixed by hand before the checks, and a failing run is published like a passing one. The procedure and every result are public, and the first prompt runs again before each release.

  • Gemini CLI0.65.0

    gemini-3.8-flash

    Built, checks pass
    Our docs are out of date. Save these three files at their paths first, then bring the docs in line with the code. Leave it uncommitted, I want to review the diff. README.md: # Acme Acme is our booking front end. It is built on Next.js 14 and React 18, and we keep it deliberately small. ## Getting started ```bash yarn install yarn dev ``` Run `npm run lint` before you push, and `npm test` for the unit tests. ## Structure - `src/app/`: the routes - `src/components/`: shared components ## Features - A dark mode toggle in the header - Server-rendered pages CLAUDE.md: # CLAUDE.md Next.js 14 app. Before finishing a task, run `npm run lint` and `npm run typecheck`. Routes live in `src/app/`. CHANGELOG.md: # Changelog ## [0.1.0] - 2026-01-10 - First version on Next.js 14.
    Typecheck: passBuild: passTests: not run
    Time
    3 min
    Changed
    3 files, +27 lines
    Skill
    v0.1.2
    Run
    Oct 25, 2026

    Result file ›Agent log ›

    What we saw

    Rubric 8/8, scored from the JSON summary. Round 3 of the eval loop, a dispatch re-run of 0.1.2. Eleven one-fact Changed lines with sources, CHANGELOG.md untouched, nothing committed, and dark mode flagged for the person to decide.

  • Codex CLIcodex-cli 0.164.0

    gpt-6.1-sol

    Built, checks pass
    Our docs are out of date. Save these three files at their paths first, then bring the docs in line with the code. Leave it uncommitted, I want to review the diff. README.md: # Acme Acme is our booking front end. It is built on Next.js 14 and React 18, and we keep it deliberately small. ## Getting started ```bash yarn install yarn dev ``` Run `npm run lint` before you push, and `npm test` for the unit tests. ## Structure - `src/app/`: the routes - `src/components/`: shared components ## Features - A dark mode toggle in the header - Server-rendered pages CLAUDE.md: # CLAUDE.md Next.js 14 app. Before finishing a task, run `npm run lint` and `npm run typecheck`. Routes live in `src/app/`. CHANGELOG.md: # Changelog ## [0.1.0] - 2026-01-10 - First version on Next.js 14.
    Typecheck: passBuild: passTests: not run
    Time
    1 min
    Changed
    3 files, +27 lines
    Skill
    v0.1.2
    Run
    Oct 25, 2026

    Result file ›Agent log ›

    What we saw

    Rubric 8/8, scored from the transcript's final diff. Round 3 of the eval loop, a dispatch re-run of 0.1.2. The README is byte-identical to the 0.1.1 run's (blob eacecdc), and CLAUDE.md reads "Next.js 16 app. Before finishing a task, run npm run typecheck. Routes live in app/." The report has one fact per line with a source, CHANGELOG.md is untouched, and dark mode is flagged.

  • Claude Code2.1.310

    claude-opus-5-5

    Built, checks pass
    Our docs are out of date. Save these three files at their paths first, then bring the docs in line with the code. Leave it uncommitted, I want to review the diff. README.md: # Acme Acme is our booking front end. It is built on Next.js 14 and React 18, and we keep it deliberately small. ## Getting started ```bash yarn install yarn dev ``` Run `npm run lint` before you push, and `npm test` for the unit tests. ## Structure - `src/app/`: the routes - `src/components/`: shared components ## Features - A dark mode toggle in the header - Server-rendered pages CLAUDE.md: # CLAUDE.md Next.js 14 app. Before finishing a task, run `npm run lint` and `npm run typecheck`. Routes live in `src/app/`. CHANGELOG.md: # Changelog ## [0.1.0] - 2026-01-10 - First version on Next.js 14.
    Typecheck: passBuild: passTests: not run
    Time
    1 min
    Changed
    3 files, +27 lines
    Skill
    v0.1.2
    Run
    Oct 25, 2026

    Result file ›Agent log ›

    What we saw

    Rubric 8/8, scored from the JSON summary. Round 3 of the eval loop, a dispatch re-run of 0.1.2. Eleven one-fact Changed lines with sources, every removal included, CHANGELOG.md as supplied, nothing staged, the tsconfig.json build rewrite reverted, and dark mode flagged with where it looked.

Generated from the skill's own files at commit 6fa457c. Every rule above links to where the repository says it. All skills