MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-base
pywf-oss-base
FlaggedShared conventions, references, and scripts of the pywf-oss skills for pywf open-source Python libraries: setup, layout, code style, tests, user docs and the agent skills that hold API and maintenance knowledge, CI and hosting, release, dependencies, and secrets. Load it before ad-hoc work on modules, tests, or docs in such a repo, for a question about these conventions, or when unsure which pywf-oss skill fits a job.
scripts/update_skill_index.py
View on GitHub#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Regenerate the references index in a skill's SKILL.md from each reference's H1 and the "Read when" part of its description."""
from __future__ import annotations
import argparse
import re
import sys
from pathlib import Path
BEGIN = "<!-- BEGIN references index: generated by scripts/update_skill_index.py, do not edit by hand -->"
END = "<!-- END references index -->"
RE_FRONTMATTER = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
RE_DESCRIPTION = re.compile(r'^description:\s*"(.*)"\s*$', re.MULTILINE)
RE_H1 = re.compile(r"^# (.+)$", re.MULTILINE)
RE_TRIGGER = re.compile(r"\bRead (?:when|before)\b.*$")
def read_entry(path: Path) -> tuple[str, str]:
"""Return (H1 title, trigger) of one reference file; raise ValueError if either is missing.
The trigger is the part of the description from "Read when" or "Read before" to the end.
"""
text = path.read_text(encoding="utf-8")
frontmatter = RE_FRONTMATTER.match(text)
if frontmatter is None:
raise ValueError(f"{path}: no YAML frontmatter at the top")
description = RE_DESCRIPTION.search(frontmatter.group(1))
if description is None:
raise ValueError(f'{path}: frontmatter has no double-quoted description: "..."')
trigger = RE_TRIGGER.search(description.group(1).strip())
if trigger is None:
raise ValueError(
f'{path}: description has no "Read when ..." or "Read before ..." part'
)
title = RE_H1.search(text[frontmatter.end() :])
if title is None:
raise ValueError(f"{path}: no H1 title after the frontmatter")
return title.group(1).strip(), trigger.group(0)
def render_index(skill_dir: Path) -> str:
"""Render the index block for every references/*.md, in file name order."""
lines = [BEGIN, ""]
for path in sorted((skill_dir / "references").glob("*.md")):
title, trigger = read_entry(path)
rel = path.relative_to(skill_dir).as_posix()
lines.append(f"- **{title}** (`{rel}`): {trigger}")
lines.extend(["", END])
return "\n".join(lines)
def _main(skill_dir: Path, check: bool = False) -> int:
"""Replace the block between the BEGIN and END markers in SKILL.md with a fresh index.
With ``check``, write nothing and return 1 if the index is out of date.
Returns 0 on success, 1 on a stale index (check mode) or invalid input.
"""
skill_md = skill_dir / "SKILL.md"
if not skill_md.exists():
print(f"ERROR: {skill_md} not found", file=sys.stderr)
return 1
text = skill_md.read_text(encoding="utf-8")
start = text.find(BEGIN)
stop = text.find(END)
if start == -1 or stop == -1 or stop < start:
print(f"ERROR: {skill_md} needs the markers:\n{BEGIN}\n{END}", file=sys.stderr)
return 1
try:
block = render_index(skill_dir)
except ValueError as e:
print(f"ERROR: {e}", file=sys.stderr)
return 1
new_text = text[:start] + block + text[stop + len(END) :]
if check:
if new_text != text:
print(f"{skill_md}: references index is out of date")
return 1
print(f"{skill_md}: references index is up to date")
return 0
if new_text != text:
skill_md.write_text(new_text, encoding="utf-8")
print(f"updated {skill_md}")
else:
print(f"{skill_md}: already up to date")
return 0
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(
prog="update_skill_index",
description="Regenerate the references index in SKILL.md from each reference's H1 and the Read when part of its description.",
)
parser.add_argument(
"--skill_dir",
type=Path,
default=Path(__file__).resolve().parent.parent,
help="skill folder holding SKILL.md and references/ (default: this script's skill)",
)
parser.add_argument(
"--check",
action="store_true",
help="only report whether the index is up to date",
)
args = parser.parse_args(argv)
return _main(skill_dir=args.skill_dir, check=args.check)
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: 468k | 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: 468k | 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: 468k | 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 |