skills.rest
witwave-ai
witwave-aiOFFICIAL
Explore all skills by this author →
WebsiteGitHub

docs-scan

Orchestrates documentation validation, link fixing, and per-category git commits.

2|Updated Apr 5, 2026
Search Tags:#automation#git#documentation#maintenance#orchestration#markdownlint#link checking
One-click install
npx skills add https://github.com/witwave-ai/witwave --skill docs-scan-witwave-ai
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: docs-scan
Source: https://github.com/witwave-ai/witwave/tree/main/.agents/self/kira/.claude/skills/docs-scan
Command: npx skills add https://github.com/witwave-ai/witwave --skill docs-scan-witwave-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Keeping a repository's documentation healthy requires running lint checks, fixing broken links, committing changes in reviewable batches, and publishing them — a repetitive multi-step routine that is easy to do inconsistently by hand. ## Core Features & Use Cases - Orchestrated docs pass: Verifies the source tree, pins git identity, then runs the docs-validate and docs-links subordinate skills in sequence. - Per-category commits: Stages and commits each category of fixes separately so git history stays bisectable and each fix is individually revertable. - Delegated publishing: Hands the push off to a peer agent (iris) via call-peer, keeping commit and push responsibilities separated. - Use Case: A heartbeat fires every six hours; the skill scans the docs tree, auto-fixes markdownlint issues and broken internal links, commits each category, and asks iris to push the resulting commits to origin. ## Quick Start Ask the agent to scan docs and run documentation maintenance on the repository.

Frequently Asked Questions about docs-scan

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

FAQPage Schema
How do I run an automated documentation maintenance scan on a repository?▼

Trigger the docs-scan skill by saying "scan docs" or "check documentation". It verifies the working tree, runs markdown validation and link fixing, commits fixes per category, and delegates the push to a peer agent.

How to fix broken internal links in markdown documentation automatically?▼

The docs-links subordinate skill, invoked during the scan, applies auto-fixes for broken internal links and anchors. Ambiguous findings it cannot resolve are logged to a deferred-findings memory file for later human review.

What is the difference between docs-scan and docs-cleanup?▼

docs-scan is the Tier 1 quick mechanical pass covering validation and link fixes. docs-cleanup runs the full Tier 1 plus Tier 2 sweep, additionally invoking docs-verify and docs-consistency for deeper checks.

Why does the docs scan stop without making changes?▼

The scan stops if the source tree is missing or the working tree has uncommitted changes, since it cannot safely distinguish their origin. It logs the finding to memory and waits rather than stashing, resetting, or cloning.

Does the skill push commits directly to the remote repository?▼

No. It follows a kira-commits / iris-pushes contract: the skill only creates local per-category commits, then calls the peer agent iris via call-peer to run git-push. Force pushes are refused by design.

Related Skills

Explore More Software Engineering Skills→
apocohqapocohq
4

cleanup-commits

Rebase a feature branch into logical commits for PR review.

Official
Intermediate
muddyrainmuddyrain
1

git-publish-guard

Constrain git push actions to require explicit remote specification, defaulting to origin.

Community
Intermediate
robinxinrobinxin

fix

Run yarn prettier and yarn linc to fix lint and formatting issues.

Community
Basic
PracticalSwanPracticalSwan
7

documentation-automation

Configure markdownlint, link checkers, and pre-commit hooks for documentation validation.

Community
Intermediate