Skip to content

MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-base

pywf-oss-base

Flagged

Shared 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.

FileKindSize
SKILL.mdskill md6.5 KB
assets/community-skills.tomlconfig2.4 KB
assets/notebook-page-template.ipynbother1.1 KB
assets/raw-rst-cell.jsonconfig255 B
references/00-authoring-references.mdmarkdown6.3 KB
references/01-secrets.mdmarkdown3.0 KB
references/02-machine-setup.mdmarkdown3.2 KB
references/03-mise.mdmarkdown2.1 KB
references/04-python-versions.mdmarkdown1.8 KB
references/05-uv-dependencies.mdmarkdown2.0 KB
references/06-ruff.mdmarkdown1.9 KB
references/07-repo-layout.mdmarkdown2.3 KB
references/08-package-files.mdmarkdown3.9 KB
references/09-code-style.mdmarkdown5.6 KB
references/10-test-layout.mdmarkdown4.1 KB
references/11-test-writing.mdmarkdown2.1 KB
references/12-coverage.mdmarkdown1.1 KB
references/13-sphinx.mdmarkdown5.6 KB
references/14-docfly.mdmarkdown2.2 KB
references/15-furo.mdmarkdown1.4 KB
references/16-sphinx-design.mdmarkdown5.8 KB
references/17-nbsphinx.mdmarkdown5.0 KB
references/18-knowledge-channels.mdmarkdown3.8 KB
references/19-github-actions.mdmarkdown3.7 KB
references/20-codecov.mdmarkdown1.3 KB
references/21-readthedocs.mdmarkdown1.7 KB
references/22-versioning-and-changelog.mdmarkdown3.0 KB
references/23-release.mdmarkdown1.3 KB
references/24-dependency-upgrades.mdmarkdown3.2 KB
references/25-python-release-cycle.mdmarkdown1.4 KB
references/26-community-skills.mdmarkdown5.0 KB
references/27-skill-family-workflow.mdmarkdown6.5 KB
scripts/check_doc_xrefs.pyscript3.4 KB
scripts/check_one_import_per_line.pyscript4.2 KB
scripts/check_skill_family.pyscript6.5 KB
scripts/check_test_layout.pyscript6.2 KB
scripts/install_community_skill.pyscript8.6 KB
scripts/update_skill_index.pyscript4.1 KB

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())
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: 468kUpdated 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: 468kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 468kUpdated 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