Skip to content

moonlight-lupin/agent-skills / software-development/skill-quality-review

skill-quality-review

Verified

Use when auditing or reviewing skill quality — batch checks across a library, deep per-skill grep methodology, usage stats, efficacy testing, or fix planning. Single consolidated home for the writing-for-agents review framework and the 3-surface review methodology.

scripts/add_toc.py

View on GitHub
#!/usr/bin/env python3
"""Bulk-add Contents lists to long markdown reference files.

Companion to audit_references.py in this skill. Finds markdown files over
100 lines that lack a Contents list and inserts one generated from the
file's own structure. Dry-run by default; pass --apply to write.

Heading extraction priority (all code-fence aware):
  1. '## ' headings
  2. '### ' headings when no '## ' exists
  3. '- **Label**:' bold-label bullets when no headings exist
Skips files whose generated list would exceed --max-entries (default 60):
for label-dump files a TOC nearly doubles the file and stops paying for
itself. Same vendored exemptions as audit_references.py (llms*, brands/,
vendor/, examples/, >5000-line dumps). Adds exactly one trailing newline —
bulk writers that leave the final newline off make git report the last
line as deleted and re-added.

Usage:
    python3 add_toc.py <dir>              # dry-run report
    python3 add_toc.py <dir> --apply      # write the TOCs
    python3 add_toc.py <dir> --json       # machine-readable report
    python3 add_toc.py <dir> --max-entries 80

Exit code 0 = nothing pending or all applied cleanly; 1 = pending changes
remain (dry-run) or some files were skipped for structure or encoding
reasons. A non-UTF-8 file reports not-utf8, is never rewritten, and keeps
the exit non-zero until it is converted to UTF-8.
"""
import json
import os
import re
import sys

TOC_MARK = "## Contents"
VENDORED_DIR_PARTS = {"brands", "vendor", "examples"}


def _outside_fences(lines):
    """Yield (index, line) for lines outside fenced code blocks."""
    inf = False
    for i, l in enumerate(lines):
        if l.strip().startswith("```"):
            inf = not inf
            continue
        if not inf:
            yield i, l


def clean_entry(text):
    t = re.sub(r"\*+", "", text.strip())
    return t.rstrip(":").strip()


def extract(lines):
    """Return (entries, mode) using the highest-priority structure present."""
    h2, h3, bullets = [], [], []
    for _, l in _outside_fences(lines):
        if re.match(r"^## ", l):
            h2.append(clean_entry(l[3:]))
        elif re.match(r"^### ", l):
            h3.append(clean_entry(l[4:]))
        m = re.match(r"^- \*\*(.+?)\*\*", l)
        if m:
            bullets.append(m.group(1).strip())
    if h2:
        return h2, "h2"
    if h3:
        return h3, "h3"
    if bullets:
        return bullets, "bullets"
    return [], None


def is_vendored(rel, n_lines):
    parts = set(rel.replace(os.sep, "/").split("/"))
    if os.path.basename(rel.lower()).startswith("llms"):
        return True
    if parts & VENDORED_DIR_PARTS:
        return True
    return n_lines > 5000


def add_toc(fp, rel, max_entries, apply=False):
    """Return a status. Writes ONLY when apply=True ("fixed"); a dry-run returns "would-fix".
    Reads strict UTF-8 (a non-UTF-8 file is skipped, never rewritten) and writes UTF-8 + LF via
    a temp file and os.replace, so a failed write can't truncate the original."""
    try:
        with open(fp, encoding="utf-8", newline="") as fh:
            txt = fh.read()
    except UnicodeDecodeError:
        return "not-utf8"
    lines = txt.splitlines()
    if len(lines) <= 100:
        return "short"
    head_zone = txt.splitlines()[:80]
    if TOC_MARK in txt[:400] or any(l.strip() == TOC_MARK for l in head_zone) \
            or any(re.match(r"^#{1,3}\s+(contents|table of contents)\b", l, re.I) for l in head_zone):
        return "already-toc"
    if is_vendored(rel, len(lines)):
        return "vendored"
    entries, mode = extract(lines)
    if not mode:
        return "no-structure"
    if len(entries) > max_entries:
        return "too-many-entries"
    anchor = r"^## " if mode == "h2" else (r"^### " if mode == "h3" else r"^- \*\*")
    ins = None
    for i, l in _outside_fences(lines):
        if re.match(anchor, l) and any(x.strip() for x in lines[i + 1:]):
            ins = i
            break
    if ins is None:
        return "no-insert-point"
    if not apply:
        return "would-fix"
    toc = [TOC_MARK, ""] + [f"- {e}" for e in entries] + [""]
    new = lines[:ins] + toc + lines[ins:]
    tmp = fp + ".toc-tmp"
    with open(tmp, "w", encoding="utf-8", newline="\n") as fh:
        fh.write("\n".join(new) + "\n")
    os.replace(tmp, fp)
    return "fixed"


def main():
    argv = sys.argv[1:]
    do_apply = "--apply" in argv
    as_json = "--json" in argv
    max_entries = 60
    if "--max-entries" in argv:
        idx = argv.index("--max-entries")
        max_entries = int(argv[idx + 1])
    args = [a for a in argv if not a.startswith("--")]
    if not args:
        print(__doc__)
        return 2
    root = os.path.abspath(args[0])
    if not os.path.isdir(root):
        print(f"not a directory: {root}")
        return 2
    report = {}
    changed = 0
    for dp, _, fns in os.walk(root):
        for fn in sorted(fns):
            if not fn.endswith(".md") or fn == "SKILL.md":
                continue
            fp = os.path.join(dp, fn)
            rel = os.path.relpath(fp, root)
            status = add_toc(fp, rel, max_entries, apply=do_apply)
            report[rel] = status
            if status in ("fixed", "would-fix"):
                changed += 1
    if as_json:
        print(json.dumps({"applied": do_apply, "fixed": changed,
                          "report": report}, indent=1))
    else:
        print(f"{'APPLIED' if do_apply else 'DRY-RUN'} | {'fixed' if do_apply else 'would fix'}: {changed}")
        for rel, status in report.items():
            if status not in ("short", "already-toc", "vendored"):
                print(f"  {status:<20} {rel}")
    pending = sum(1 for s in report.values() if s == "would-fix")
    skipped = sum(1 for s in report.values() if s.startswith(("too-many", "no-", "not-utf8")))
    return 1 if (pending or skipped) else 0


if __name__ == "__main__":
    sys.exit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall