doc-drift-detector
Detect documentation drift against code changes, score staleness, validate API docs via AST parsing, and audit link integrity
Install / Use
npx skills add borghei/Claude-Skills --skill doc-drift-detectorInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of doc-drift-detector
doc-drift-detector scores 84/100 on our quality scale, 876th of 1,156 Content & Media skills we index.
Its SKILL.md is 7.3 KB long, well organised into 9 sections and no code examples: a thorough specification that gives an agent plenty to work with.
It has 817 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so doc-drift-detector is actively maintained.
- Our last check on 2026-11-06 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
doc-drift-detector compared with similar skills
All 4 of these similar skills score higher than doc-drift-detector; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| doc-drift-detector (this skill)by borghei | 84 | 817 | 57d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.7k | 9d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.9k | today | MCP Server |
| crawl4aiby unclecode | 100 | 87.5k | today | MCP Server |
Frequently asked questions
- How do I install doc-drift-detector?
- Run
npx skills add borghei/Claude-Skills --skill doc-drift-detector. The install tabs above show the steps for each supported agent. - Which AI agents does doc-drift-detector work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is doc-drift-detector safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is doc-drift-detector still maintained?
- The repository was last updated about 2 months ago, so doc-drift-detector is actively maintained.
Skill content
View source on GitHubname: doc-drift-detector description: > 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. license: MIT + Commons Clause metadata: version: 2.1.0 author: borghei category: engineering domain: documentation updated: 2026-06-17 tags: [documentation, staleness, api-docs, drift-analysis] python-tools: drift_analyzer.py, doc_staleness_scorer.py, api_doc_validator.py, link_checker.py tech-stack: python, git, markdown, documentation
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. If any is unknown or vague, ASK — do not assume:
- [ ] Which check — full drift analysis, staleness score, API doc validation, or link audit (selects
drift_analyzer.pyvsdoc_staleness_scorer.pyvsapi_doc_validator.pyvslink_checker.py) - [ ] Repo & doc/source paths — the repository and which code and docs directories to compare (the input the tools scan)
- [ ] Threshold & gate — minimum severity or staleness threshold for CI failure (sets
--min-severity/--thresholdand the exit-code gate)
Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
Tools
| Tool | Purpose | Command |
|------|---------|---------|
| drift_analyzer.py | Full drift analysis between code and docs | python scripts/drift_analyzer.py <repo> --min-severity high --json |
| doc_staleness_scorer.py | Score documentation freshness 0-100 | python scripts/doc_staleness_scorer.py <repo> --threshold 60 |
| api_doc_validator.py | Validate API docs against Python source (AST) | python scripts/api_doc_validator.py <src> <docs> --recursive |
| link_checker.py | Audit all markdown links and anchors | python scripts/link_checker.py <repo> --broken-only |
All tools: Python 3.8+ stdlib only, --json and --help, non-zero exit codes for CI, any OS.
References
Load the reference that matches the task — keep this file lean and pull detail on demand:
- references/workflows-and-tool-reference.md — quick start, the 5 core workflows (full analysis, API validation, README health, link audit, CI monitoring) with output examples, GitHub Actions + pre-commit recipes, and the complete per-tool parameter/output/exit-code reference. Read when running tools or wiring CI.
- references/scoring-categories-and-troubleshooting.md — the staleness scoring model and weights, the five drift categories, auto-fix vs manual-fix classification, detailed integration points, anti-patterns, troubleshooting table, and success criteria. Read when interpreting results or triaging drift.
- references/documentation_standards.md — README structure, API docs, changelogs, ADRs, docs-as-code standards.
- references/drift_prevention_guide.md — coupling strategies, CI gates, review checklists, and prevention patterns.
Assets
| Asset | Description | |-------|-------------| | Drift Report Template | Template for drift analysis reports | | Sample Drift Data | Sample JSON for testing and demonstration |
Scope & Limitations
Covers:
- Detection of documentation drift against git history for any git repository
- AST-based validation of Python API documentation (function signatures, class definitions, parameters, return types)
- Internal link validation including local files, markdown anchors, cross-document anchors, images, and case-sensitivity checks
- Multi-dimensional staleness scoring with configurable weights and CI/CD threshold enforcement
Does NOT cover:
- Non-Python source code API validation -- the AST-based validator only parses Python; for TypeScript, Go, Rust, or Java APIs, use language-specific doc generators and pair with the link checker
- External URL uptime monitoring --
--check-externalperforms one-shot HEAD requests but does not provide continuous monitoring; use the senior-devops skill for uptime dashboards - Automatic documentation rewriting -- tools classify issues as
[AUTO],[SEMI], or[MANUAL]but do not generate replacement text; use the code-reviewer skill for AI-assisted doc suggestions - Content quality or readability assessment -- staleness scoring measures freshness and structural completeness, not prose quality; see the standards/communication library for writing guidelines
Integration Points
| Skill | Integration | Data Flow |
|-------|-------------|-----------|
| code-reviewer | Include drift report in PR review comments | drift_analyzer.py --json output feeds into review checklists as a documentation health section |
| senior-devops | Add staleness gate to CI/CD pipelines | doc_staleness_scorer.py --threshold 50 returns exit code 1 on failure, blocking deploys |
| senior-qa | Documentation quality as part of QA acceptance | link_checker.py --json output merges into QA dashboards alongside test coverage metrics |
| senior-fullstack | Validate generated project docs post-scaffold | Run api_doc_validator.py against scaffolded docs/ directory to confirm generated API docs match source |
| senior-secops | Audit security documentation currency | drift_analyzer.py --scope security/ detects when security docs fall behind policy changes |
| senior-architect | Architecture decision record (ADR) freshness | doc_staleness_scorer.py --required-sections "Status,Context,Decision,Consequences" validates ADR completeness |
Related Skills
Agent-Reach
112.7kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Scrapling
103.9k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
crawl4ai
87.5kOfficial Crawl4AI Cloud: a hosted web scraping, extraction, and search API for AI agents. Free API key, 1,000 credits a month, no card. Fully open source: this repo is the Apache-2.0 crawler that powers it, and you can self-host it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
