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/install_community_skill.py

View on GitHub
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Stage and install a community Agent Skill from its pinned GitHub tree URL in the catalog."""

from __future__ import annotations

import argparse
import datetime
import json
import re
import shutil
import subprocess
import sys
import tarfile
import tempfile
import tomllib
import urllib.request
from pathlib import Path

DEFAULT_CATALOG = (
    Path(__file__).resolve().parent.parent / "assets" / "community-skills.toml"
)
RE_TREE_URL = re.compile(
    r"^https://github\.com/(?P<owner>[^/]+)/(?P<repo>[^/]+)/tree/(?P<ref>[0-9a-f]{40})/(?P<path>.+?)/?$"
)
RE_NAME = re.compile(r"^name:\s*['\"]?([^'\"\n]+?)['\"]?\s*$", re.MULTILINE)
SCRIPT_SUFFIXES = {".py", ".sh", ".bash", ".js", ".mjs", ".ts", ".rb", ".pl", ".ps1"}


def load_catalog(catalog: Path) -> list[dict]:
    """Return the [[skill]] entries of the catalog."""
    with catalog.open("rb") as f:
        return tomllib.load(f).get("skill", [])


def parse_tree_url(url: str) -> dict[str, str]:
    """Split a pinned tree URL into owner, repo, ref (40-char sha), and path."""
    match = RE_TREE_URL.match(url)
    if match is None:
        raise ValueError(
            f"not a pinned tree URL (https://github.com/<owner>/<repo>/tree/<40-char sha>/<path>): {url}"
        )
    return match.groupdict()


def download_folder(parts: dict[str, str], staging: Path) -> None:
    """Download the repo tarball at the pinned commit and extract only the skill folder into staging."""
    tarball_url = f"https://codeload.github.com/{parts['owner']}/{parts['repo']}/tar.gz/{parts['ref']}"
    with tempfile.TemporaryDirectory() as tmp:
        tar_path = Path(tmp) / "repo.tar.gz"
        with (
            urllib.request.urlopen(tarball_url, timeout=120) as response,
            tar_path.open("wb") as f,
        ):
            shutil.copyfileobj(response, f)
        with tarfile.open(tar_path, "r:gz") as tar:
            members = tar.getmembers()
            if not members:
                raise ValueError("empty tarball")
            root = members[0].name.split("/", 1)[0]
            prefix = f"{root}/{parts['path'].strip('/')}/"
            picked = 0
            for member in members:
                if not member.name.startswith(prefix) or member.name == prefix.rstrip(
                    "/"
                ):
                    continue
                rel = Path(member.name[len(prefix) :])
                if rel.is_absolute() or ".." in rel.parts:
                    raise ValueError(f"unsafe path in tarball: {member.name}")
                if member.issym() or member.islnk():
                    print(f"skipped link: {rel}", file=sys.stderr)
                    continue
                target = staging / rel
                if member.isdir():
                    target.mkdir(parents=True, exist_ok=True)
                elif member.isfile():
                    target.parent.mkdir(parents=True, exist_ok=True)
                    source = tar.extractfile(member)
                    if source is None:
                        continue
                    with source, target.open("wb") as out:
                        shutil.copyfileobj(source, out)
                    picked += 1
            if picked == 0:
                raise ValueError(f"path not found at this commit: {parts['path']}")


def summarize(staging: Path) -> None:
    """Print what would be installed, with executable scripts called out for review."""
    files = sorted(p for p in staging.rglob("*") if p.is_file())
    scripts = [p for p in files if p.suffix in SCRIPT_SUFFIXES]
    total = sum(p.stat().st_size for p in files)
    print(f"staged {len(files)} files ({total / 1024:.0f} KiB) in {staging}")
    print("top level:")
    for child in sorted(staging.iterdir()):
        print(f"  {child.name}{'/' if child.is_dir() else ''}")
    print(f"scripts to review ({len(scripts)}):")
    for script in scripts:
        print(f"  {script.relative_to(staging)}")


def _main(
    project_root: Path,
    name: str | None = None,
    catalog: Path = DEFAULT_CATALOG,
    list_only: bool = False,
    install: bool = False,
    force: bool = False,
) -> int:
    """List the catalog, or stage a skill into tmp/ for review, and with ``install`` copy it into .claude/skills/.

    Returns 0 on success, 1 on any failure.
    """
    entries = load_catalog(catalog)
    if list_only:
        for entry in entries:
            parts = parse_tree_url(entry["url"])
            print(
                f"{entry['name']}: {parts['owner']}/{parts['repo']} @ {parts['ref'][:7]} / {parts['path']} ({entry.get('license', '?')})"
            )
            print(f"  when to use: {entry.get('when_to_use', '')}")
        return 0
    matches = [e for e in entries if e.get("name") == name]
    if not matches:
        print(f"ERROR: no skill named {name!r} in {catalog}", file=sys.stderr)
        return 1
    entry = matches[0]
    try:
        parts = parse_tree_url(entry["url"])
    except ValueError as e:
        print(f"ERROR: {e}", file=sys.stderr)
        return 1

    project_root = project_root.resolve()
    dest = project_root / ".claude" / "skills" / name
    if install and dest.exists() and not force:
        print(
            f"ERROR: {dest} already exists; rerun with --force to replace it",
            file=sys.stderr,
        )
        return 1
    staging = project_root / "tmp" / "community-skills" / f"{name}@{parts['ref'][:7]}"
    if staging.exists():
        shutil.rmtree(staging)
    staging.mkdir(parents=True)
    try:
        download_folder(parts, staging)
    except (OSError, ValueError, tarfile.TarError) as e:
        print(f"ERROR: download failed: {e}", file=sys.stderr)
        return 1

    skill_md = staging / "SKILL.md"
    if not skill_md.exists():
        print(f"ERROR: no SKILL.md at {parts['path']}", file=sys.stderr)
        return 1
    found = RE_NAME.search(skill_md.read_text(encoding="utf-8"))
    if found is None or found.group(1) != name:
        print(
            f"ERROR: SKILL.md name is {found.group(1) if found else None!r}, catalog says {name!r}",
            file=sys.stderr,
        )
        return 1
    summarize(staging)
    if not install:
        print("not installed: review the staged files, then rerun with --install")
        return 0

    if dest.exists():
        shutil.rmtree(dest)
    shutil.copytree(staging, dest)
    source = {
        "name": name,
        "url": entry["url"],
        "license": entry.get("license"),
        "installed_on": datetime.date.today().isoformat(),
    }
    (dest / ".source.json").write_text(
        json.dumps(source, indent=2) + "\n", encoding="utf-8"
    )
    shutil.rmtree(staging)
    print(f"installed {name} into {dest}")
    ignored = subprocess.run(
        ["git", "check-ignore", "-q", str(dest / "SKILL.md")],
        cwd=project_root,
        capture_output=True,
    )
    if ignored.returncode == 0:
        print(
            f"git: .claude/skills/{name}/ is git-ignored (default); delete its line in .gitignore to commit it"
        )
    elif ignored.returncode == 1:
        print(
            f"git: .claude/skills/{name}/ is NOT git-ignored; add its line to the community-skills block of .gitignore, or commit it on purpose"
        )
    return 0


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        prog="install_community_skill",
        description="Stage and install a community Agent Skill from its pinned GitHub tree URL in the catalog.",
    )
    parser.add_argument("--name", default=None, help="skill name in the catalog")
    parser.add_argument(
        "--list",
        dest="list_only",
        action="store_true",
        help="list the catalog and exit",
    )
    parser.add_argument(
        "--install",
        action="store_true",
        help="copy the staged skill into .claude/skills/",
    )
    parser.add_argument(
        "--force",
        action="store_true",
        help="replace an installed skill of the same name",
    )
    parser.add_argument(
        "--project_root",
        type=Path,
        default=Path("."),
        help="repository root (default: .)",
    )
    parser.add_argument(
        "--catalog",
        type=Path,
        default=DEFAULT_CATALOG,
        help="catalog TOML (default: the base skill's assets)",
    )
    args = parser.parse_args(argv)
    if not args.list_only and not args.name:
        parser.error("--name is required unless --list is given")
    return _main(
        project_root=args.project_root,
        name=args.name,
        catalog=args.catalog,
        list_only=args.list_only,
        install=args.install,
        force=args.force,
    )


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