Agent skill · software engineering · borghei
doc-drift-detector
Detect documentation drift against code changes, score staleness, validate API docs via AST parsing, and audit link integrity. Use when docs fall out of sync with code, preparing releases, running CI doc gates, or auditing doc accuracy.
Why this skill is useful
Adds 4 executable Python scripts for documentation drift detection and validation that automate processes not commonly found in public resources.
What it needs
Requires python installed locally. About 4k tokens when loaded. Last updated 2026-07-21. 462 stars on the source repository.
What this skill does
Documentation Drift Detector The agent detects documentation drift by mapping code directories to their docs, comparing git modification histories, extracting Python function signatures via AST, validating every markdown link and anchor, and scoring freshness on a weighted 0-100 scale. All four CLI tools use the Python standard library only. Core Capabilities Full drift analysis — map docs to code, compare git histories, detect renamed files, version drift, broken references, and structural gaps; classify each issue by category, severity, and fix type. API doc validation — AST-based extraction of Python signatures/classes compared against markdown API docs (undocumented items, phantom docs, parameter mismatches, deprecations). Staleness scoring — weighted 0-100 freshness score across five dimensions with CI threshold gates and README-focused mode. Link integrity audit — validate local files, anchors, cross-document anchors, images, case-sensitivity, and duplicate anchors; optional external URL checks. Drift classification — structural, factual, referential, temporal, semantic categories, each tagged [AUTO]/[SEMI]/[MANUAL] for fix routing. CI/CD integration — non-zero exit codes, JSON output, GitHub Actions and pre-commit recipes for ongoing monitoring. When to Use Docs have fallen out of sync with code — run full drift analysis. Preparing a release — gate on aggregate staleness score. Running CI doc gates — fail PRs on high/critical drift or broken links. Auditing API doc accuracy against Python source. Checking README health and link integrity after refactors. Clarify First Before running detection, confirm these inputs. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills borghei/doc-drift-detector