drift-cli

Link markdown anchors to AST symbols and validate freshness with drift check.

Updated Mar 12, 2026
One-click install
npx skills add https://github.com/mpsuesser/workspace --skill drift-cli
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: drift-cli
Source: https://github.com/mpsuesser/workspace/tree/main/dotconfig/pi/agent/skills/__techs__/drift-cli
Command: npx skills add https://github.com/mpsuesser/workspace --skill drift-cli

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill prevents documentation from getting out of sync with the code it describes, avoiding stale instructions and broken developer workflows when code changes.

Core Features & Use Cases

  • Bind docs to code by linking markdown anchors to specific files or AST symbols so the repo has traceable relationships between docs and implementation.
  • Detect stale documentation using drift check to recompute AST-based signatures and flag when linked code changed after docs were last linked.
  • Refresh and manage bindings with drift link, drift unlink, and drift status to keep drift.lock accurate across edits and refactors.
  • Handle cross-repo documentation by supporting an origin field so anchors belonging to other repos are skipped to avoid false failures.

Quick Start

Use the drift-cli skill to link a markdown doc to a code file or symbol and then run drift check to ensure the doc remains fresh.

Frequently Asked Questions about drift-cli

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent documentation from becoming stale after code refactors?

You detect stale documentation by running a drift check that recomputes syntax-aware AST fingerprints for linked code. If the code changed after the doc was last linked, the check flags the mismatch, ensuring freshness validation.

How do I link markdown documentation to specific code symbols?

Yes, cross-repo documentation is supported by specifying an origin field in the YAML frontmatter. Anchors belonging to other repos are skipped during checks to avoid false failures.

Do I need YAML frontmatter to run AST freshness validation on docs?

CI linting checks for documentation drift by recomputing AST-based fingerprints and comparing them against stamped drift.lock signatures. Mismatches indicate doc-to-code drift after edits.

What is the best way to validate AGENTS.md instructions against repo code changes?

You manage bindings across refactors using drift link, drift unlink, and drift status commands. These keep the drift.lock file accurate by updating or removing AST-based bindings after code changes.