Skip to content

notque/vexjoy-agent / skills/meta/docs-sync-checker

docs-sync-checker

Verified

Detect documentation drift against filesystem state.

FileKindSize
SKILL.mdskill md11.6 KB
references/documentation-structure.mdmarkdown2.9 KB
references/integration-guide.mdmarkdown2.8 KB
references/sync-rules.mdmarkdown2.0 KB
scripts/generate_report.pyexecutablescript10.4 KB
scripts/parse_docs.pyexecutablescript10.6 KB
scripts/scan_tools.pyexecutablescript14.1 KB
scripts/validate.pyexecutablescript8.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()
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: 469kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexUnverifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall