notque/vexjoy-agent / skills/meta/docs-sync-checker
docs-sync-checker
VerifiedDetect documentation drift against filesystem state.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.6 KB |
| references/documentation-structure.md | markdown | 2.9 KB |
| references/integration-guide.md | markdown | 2.8 KB |
| references/sync-rules.md | markdown | 2.0 KB |
| scripts/generate_report.pyexecutable | script | 10.4 KB |
| scripts/parse_docs.pyexecutable | script | 10.6 KB |
| scripts/scan_tools.pyexecutable | script | 14.1 KB |
| scripts/validate.pyexecutable | script | 8.1 KB |
scripts/parse_docs.py
View on GitHub#!/usr/bin/env python3
"""
Documentation parser script for docs-sync-checker skill.
Reads the primary catalog for each tool type and compares it with the
scan_tools.py results:
skill -> docs/skills.md (generated by scripts/generate-skills-doc.py)
agent -> docs/routing-map.md (generated by scripts/generate-routing-map.py)
command -> docs/REFERENCE.md ("Slash Commands" tables, hand-written)
A missing primary doc, or one that parses to 0 entries for its type, is an
error (exit 2), never an empty documented set: an absent target once made
every agent and command look undocumented, and a renamed section heading or
changed first-cell format would do the same.
Exit codes: 0 no issues, 1 issues found, 2 error (including a missing target).
"""
__version__ = "2.0.0"
import argparse
import json
import re
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, Iterator, List, Optional
# Primary doc per tool type. Every path must exist; validate.py and
# scripts/tests/test_docs_sync_checker.py fail when one does not.
PRIMARY_DOCS: Dict[str, str] = {
"skill": "docs/skills.md",
"agent": "docs/routing-map.md",
"command": "docs/REFERENCE.md",
}
# Generated catalogs are fixed by rerunning their generator, never by hand.
GENERATORS: Dict[str, str] = {
"skill": "python3 scripts/generate-skills-doc.py",
"agent": "python3 scripts/generate-routing-map.py",
}
# Section that holds each type's table, or None for the whole file.
_SECTIONS: Dict[str, Optional[str]] = {
"skill": None,
"agent": "## AGENTS",
"command": "## Slash Commands",
}
# First-cell shape of a documented entry per type.
_NAME_CELL = {
"skill": re.compile(r"^`([a-z0-9][a-z0-9-]*)`$"),
"agent": re.compile(r"^([a-z0-9][a-z0-9-]*)$"),
"command": re.compile(r"^`/([a-z0-9][a-z0-9/-]*)`$"),
}
_SEPARATOR = re.compile(r"^\|[\s:|-]+\|$")
class EmptyCatalogError(ValueError):
"""A primary doc exists but yields 0 entries for its type."""
class DocumentationParser:
"""Parse the primary catalogs to extract documented tool names."""
def __init__(self, repo_root: Path, debug: bool = False):
self.repo_root = Path(repo_root).resolve()
self.debug = debug
def log(self, message: str) -> None:
"""Log debug message."""
if self.debug:
print(f"[DEBUG] {message}", file=sys.stderr)
def missing_targets(self) -> List[str]:
"""Primary doc paths that do not exist under the repo root."""
return [rel for rel in PRIMARY_DOCS.values() if not (self.repo_root / rel).is_file()]
@staticmethod
def _section(content: str, heading: Optional[str]) -> str:
"""Return the text under a heading up to the next heading of the same level."""
if heading is None:
return content
level = heading.split(" ", 1)[0] + " "
lines = content.split("\n")
out: List[str] = []
inside = False
for line in lines:
if line.startswith(heading):
inside = True
continue
if inside and line.startswith(level):
break
if inside:
out.append(line)
return "\n".join(out)
@staticmethod
def _data_first_cells(content: str) -> Iterator[str]:
"""Yield the first cell of every table data row (header and separator rows skipped)."""
lines = [line.strip() for line in content.split("\n")]
for i, line in enumerate(lines):
if not line.startswith("|") or _SEPARATOR.match(line):
continue
if i + 1 < len(lines) and _SEPARATOR.match(lines[i + 1]):
continue # header row
cells = line.strip("|").split("|")
if cells:
yield cells[0].strip()
def parse_primary(self, tool_type: str) -> List[Dict[str, str]]:
"""Return the entries documented for one tool type in its primary doc."""
rel = PRIMARY_DOCS[tool_type]
path = self.repo_root / rel
if not path.is_file():
raise FileNotFoundError(f"primary doc for {tool_type}s not found: {rel}")
content = self._section(path.read_text(encoding="utf-8"), _SECTIONS[tool_type])
pattern = _NAME_CELL[tool_type]
entries = []
for cell in self._data_first_cells(content):
match = pattern.match(cell)
if match:
entries.append({"name": match.group(1), "source": rel})
self.log(f"Found {len(entries)} {tool_type} entries in {rel}")
if not entries:
section = _SECTIONS[tool_type] or "the whole file"
raise EmptyCatalogError(
f"Entry count is zero for a type: 0 {tool_type} entries in {rel} (section {section}); "
"update _SECTIONS or _NAME_CELL in parse_docs.py to match the doc"
)
return entries
def parse_root_readme(self) -> List[Dict[str, str]]:
"""Collect `/command` and agent-name mentions in README.md (informational, not compared)."""
readme_path = self.repo_root / "README.md"
if not readme_path.exists():
return []
content = readme_path.read_text(encoding="utf-8")
tools = [
{"type": "agent", "name": m.group(1), "source": "README.md"}
for m in re.finditer(r"`([a-z0-9\-]+(?:engineer|agent))`", content)
]
tools += [
{"type": "command", "name": m.group(1), "source": "README.md"}
for m in re.finditer(r"`/([a-z0-9/\-]+)`", content)
]
return tools
@staticmethod
def _expected(scanned: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
"""Scanned tools the primary doc must list: generated catalogs omit promoted and private ones."""
return [t for t in scanned if not t.get("promoted_to") and not t.get("private")]
@staticmethod
def _fix(tool_type: str, name: str, description: str, missing: bool) -> str:
doc = PRIMARY_DOCS[tool_type]
if tool_type in GENERATORS:
return f"Regenerate {doc}: `{GENERATORS[tool_type]}`. Never hand-edit a generated catalog."
if missing:
return f"Add to a Slash Commands table in {doc}: | `/{name}` | {description} |"
return f"Remove the `/{name}` row from {doc}."
def detect_issues(
self, scan_results: Dict[str, Any], documented: Dict[str, List[Dict[str, str]]]
) -> Dict[str, Any]:
"""Compare scanned tools with each type's primary doc."""
issues: Dict[str, List[Dict[str, Any]]] = {"missing_entries": [], "stale_entries": [], "incomplete_entries": []}
for tool_type, doc in PRIMARY_DOCS.items():
scanned = scan_results.get(f"{tool_type}s", [])
# Anything on disk, promoted or private included, is not stale.
on_disk = {t["name"] for t in scanned}
expected = {t["name"]: t for t in self._expected(scanned)}
listed = {e["name"] for e in documented.get(doc, [])}
for name in sorted(set(expected) - listed):
info = expected[name]
description = info.get("description", "")
issues["missing_entries"].append(
{
"tool_type": tool_type,
"tool_name": name,
"tool_path": info.get("path", ""),
"missing_from": [doc],
"severity": "high",
"yaml_description": description,
"suggested_fix": self._fix(tool_type, name, description, missing=True),
}
)
for name in sorted(listed - on_disk):
issues["stale_entries"].append(
{
"tool_type": tool_type,
"tool_name": name,
"documented_in": [doc],
"severity": "medium",
"suggested_fix": self._fix(tool_type, name, "", missing=False),
}
)
return issues
def main():
"""Main entry point."""
parser = argparse.ArgumentParser(
description="Parse documentation files and detect sync issues",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument("--repo-root", type=Path, required=True, help="Repository root directory")
parser.add_argument("--scan-results", type=Path, help="Path to scan results JSON from scan_tools.py")
parser.add_argument("--output", type=Path, help="Output JSON file (default: stdout)")
parser.add_argument("--debug", action="store_true", help="Enable debug logging")
args = parser.parse_args()
try:
parser_obj = DocumentationParser(args.repo_root, debug=args.debug)
missing = parser_obj.missing_targets()
if missing:
raise FileNotFoundError(f"primary doc(s) not found: {', '.join(missing)}")
documented = {doc: parser_obj.parse_primary(tool_type) for tool_type, doc in PRIMARY_DOCS.items()}
documented["README.md"] = parser_obj.parse_root_readme()
results = {
"documented": documented,
"parse_timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
"files_parsed": len(documented),
}
if args.scan_results:
with open(args.scan_results, "r", encoding="utf-8") as f:
scan_results = json.load(f)
issues = parser_obj.detect_issues(scan_results, documented)
results["issues"] = issues
results["summary"] = {
"missing_entries": len(issues["missing_entries"]),
"stale_entries": len(issues["stale_entries"]),
"total_issues": len(issues["missing_entries"]) + len(issues["stale_entries"]),
}
output_json = json.dumps(results, indent=2, ensure_ascii=False)
if args.output:
args.output.parent.mkdir(parents=True, exist_ok=True)
with open(args.output, "w", encoding="utf-8") as f:
f.write(output_json)
print(f"Parse results written to: {args.output}", file=sys.stderr)
else:
print(output_json)
if results.get("summary", {}).get("total_issues", 0) > 0:
print(f"\nWarning: {results['summary']['total_issues']} sync issues found", file=sys.stderr)
sys.exit(1)
sys.exit(0)
except Exception as e:
print(
json.dumps({"status": "error", "error_type": type(e).__name__, "message": str(e)}, indent=2),
file=sys.stderr,
)
sys.exit(2)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |