Index of every page on this site: llms.txt
All skills
Run it yourself

Use when auditing or fixing drift between project documentation and the actual codebase. Detects stale architecture diagrams, wrong file paths, outdated test counts, and undocumented structural changes. Pass 'fix' to apply repairs; default is report-only. Keywords: doc drift, stale docs, sync docs, documentation audit, update docs, architecture docs outdated. Triggers on "audit doc drift" or "sync documentation".

Use this Skill: https://skilld.dev/gh/acedergren/agentic-tools/doc-sync

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈107 tokens for metadata: the name and description. ≈782 when used: this file.

Description uses 5.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈427 characters, or 5.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Documentation Sync Audit

When to Use

Load this skill when the user request matches the frontmatter description for Documentation Sync Audit.

Audit project docs against codebase reality. Report drift or fix it.

NEVER

  • Never update a doc based on what the code should look like — only sync to what it actually is now.
  • Never fix docs for a section you didn't audit — partial fixes create false confidence.
  • Never mark a roadmap item complete based on code presence alone — check git log for the deliberate completion commit.
  • Never skip auditing CLAUDE.md / agent instructions — stale agent instructions cause cascading errors in future sessions.

Drift Classification: What Actually Goes Stale

Most doc-code drift falls into four categories with different detection approaches:

Drift Type Detection Signal False Positive Risk
Structural drift Directory tree, plugin/middleware chain order Low — filesystem is ground truth
Path rot File paths in docs that no longer exist Low — use check-doc-paths.js
Count drift Test counts, permission counts, route counts Medium — recount from actual files
Roadmap lag Completed work not reflected in docs High — confirm git log intent

Decision: Audit vs Fix

  • $ARGUMENTS = empty or audit → report only, no edits
  • $ARGUMENTS = fix → report then apply targeted edits, commit

When fixing: edit the minimum to correct drift. Don't rewrite prose, restructure sections, or add new content — this is sync, not authoring.

What to Audit

Architecture docs — plugin/middleware chain order, route module list, monorepo package list, directory structure tree.

Security docs — security plugins listed vs what's registered, permission counts, any security-related commits since last doc update (git log --oneline --since="$(git log -1 --format=%ai docs/SECURITY.md)" -- src/).

Test docs — actual test file count vs documented count, pass/fail counts (run suite to get current numbers).

Roadmap/changelog — git log for completed work not reflected in any phase. Flag commits with feat: or fix: prefixes that postdate the last roadmap update.

CLAUDE.md / agent instructions — naming conventions match actual patterns, documented file paths exist, anti-patterns section is current.

Scripts

bash scripts/list-doc-targets.sh
node scripts/check-doc-paths.js README.md docs/ARCHITECTURE.md

Report Format

| Doc | Section | Issue | Severity |
|-----|---------|-------|----------|

Severity: Critical (broken paths, missing security docs), Warning (stale counts, missing routes), Info (minor wording drift, outdated roadmap phases).

Commit (fix mode only)

docs: sync documentation with codebase [doc-sync]

Arguments

$ARGUMENTS: Optional user-provided target, path, environment, symptom, or constraint. When empty, infer the narrowest safe scope from the current repository context and ask only if multiple high-impact choices remain.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning7mo5 checks · Risk SAFE
  • Gen Agent Trust Hub8mo

    The doc-sync skill is a utility for auditing and maintaining project documentation. It identifies inconsistencies between documentation and the codebase using local scripts to verify file paths. The skill is safe to use as it relies on standard file operations and local scripts for its auditing tasks.

  • Socket8mo

    No alerts

  • Snyk8mo

    Risk: LOW · No issues

  • Runlayer8mo

    2/3 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 641a79b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 6 months ago

README badge

README badge for acedergren/agentic-tools/doc-sync