skills.rest
javiruu
javiruuCOMMUNITY
Explore all skills by this author →
GitHub

oma-docs

Detect broken references in markdown documentation and propose patches for docs affected by git diffs.

Updated Mar 26, 2026
Search Tags:#documentation#markdown#drift detection#cli#verification#broken links#git diff
One-click install
npx skills add https://github.com/javiruu/viru-air --skill oma-docs-javiruu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: oma-docs
Source: https://github.com/javiruu/viru-air/tree/main/.agents/skills/oma-docs
Command: npx skills add https://github.com/javiruu/viru-air --skill oma-docs-javiruu

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires lychee.

What problem does it solve? Documentation drifts out of sync with code as projects evolve: file paths get renamed, CLI commands change, config keys disappear, and docs silently become wrong. This Skill verifies that references inside markdown docs still match the actual codebase and surfaces which docs need updating after a code change. ## Core Features & Use Cases - Drift verification (verify mode): Scans markdown docs and deterministically checks file paths, CLI commands, package.json scripts, environment variables, and config keys against the real codebase, emitting a markdown or JSON report with exit codes suitable for CI. - Diff-aware sync (sync mode): Takes a git diff range, reverse-looks-up which docs reference the changed files, and drafts interactive patch proposals that are applied only after explicit per-doc approval. - URL link checking: Delegates external URL validation to lychee running in the background, writing results to a separate drift report without blocking the core check. - Use Case: After renaming a module and deleting a config key, run verify to list every doc still referencing the old names, then run sync on the commit range to get reviewed patch proposals for each affected doc. ## Quick Start Ask the agent to check whether the documentation in the docs folder still matches the current codebase and report any broken file paths, commands, or config keys.

Frequently Asked Questions about oma-docs

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

FAQPage Schema
How do I check if my documentation is out of date with my code?▼

Run the verify mode, which scans markdown files and checks every file path, CLI command, script, env var, and config key reference against the actual codebase. It outputs a markdown or JSON drift report and exits with code 1 when broken references are found.

How to find which docs need updating after a code change?▼

Use sync mode with a git diff range such as HEAD~1..HEAD or a branch comparison. It reverse-looks-up changed files in the reference index and lists candidate docs, then drafts patch proposals that you approve or reject per doc.

Does the documentation checker validate external URLs?▼

Yes, URL checking is delegated to the external lychee tool, which runs in the background and writes results to a separate url-drift report. If lychee is not installed, URL checking is skipped with an install hint and the core reference check is unaffected.

Can I exclude example paths in tutorials from broken-link checks?▼

Yes, wrap illustrative content in oma-docs ignore-start and ignore-end comment blocks or set oma-docs skip in the frontmatter. Gitignored generated outputs are also classified as skipped rather than broken, and whole trees can be excluded via the docs.exclude config.

Will sync mode automatically modify my documentation files?▼

No, sync mode is always interactive and never auto-applies changes. Each candidate doc requires explicit confirmation (apply, skip, diff, or full proposal) before any patch is written, and the reference index is regenerated afterward.

What are the limitations of documentation drift detection?▼

The current version detects broken references only, not semantic drift such as changed function signatures in prose. Doc generation from scratch, multilingual sync, symbol-level analysis, and CI-blocking enforcement are deferred to a future version.

Related Skills

Explore More Software Engineering Skills→
AINative-StudioAINative-Studio

file-placement

Validate Markdown and shell script placement against repository directory conventions.

Official
Intermediate
baskarajatibaskarajati

Firestore Index Sync

Compare Firestore index documentation with firestore.indexes.json and generate a minimal patch to align them.

Community
Intermediate
qmuqmu
1

translate

Translate English Markdown files while preserving formatting and frontmatter semantics.

Official
Basic
swissarmyhammerswissarmyhammer
15

code-context

Provides on-demand, in-depth bike and car road-condition reports for Indian cities and intercity highways via AI-powered chat.

Official
Advanced