moonlight-lupin/agent-skills / software-development/skill-quality-review
skill-quality-review
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 33.1 KB |
| references/batch-checks.md | markdown | 23.4 KB |
| references/claude-plugin-review.md | markdown | 10.8 KB |
| references/domain-passive-voice.md | markdown | 1.8 KB |
| references/efficacy-ab-test.md | markdown | 6.3 KB |
| references/fix-phase-pitfalls.md | markdown | 3.3 KB |
| references/hermes-library-review.md | markdown | 3.3 KB |
| references/independent-skills.md | markdown | 2.1 KB |
| references/recurring-failure-patterns.md | markdown | 15.0 KB |
| references/skill-review-methodology.md | markdown | 38.9 KB |
| references/writing-for-agents-framework.md | markdown | 12.2 KB |
| scripts/add_toc.py | script | 5.8 KB |
| scripts/check_calls.py | script | 26.2 KB |
| scripts/check_references.py | script | 6.3 KB |
| templates/efficacy-rubric-template.md | markdown | 1.1 KB |
| tests/acceptance.md | markdown | 1.5 KB |
| tests/test_harness_acceptance.py | script | 4.7 KB |
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())Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |