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.
SKILL.md
View on GitHub---
name: pywf-oss-base
description: "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."
---
The conventions of the pywf open-source Python library template, shared by every `pywf-oss-*` skill. `<package_name>` is the import package directory: snake_case, equal to `[project].name` in `pyproject.toml`.
## References
Numbered in project-lifecycle order; each cites only earlier ones. For a question about one convention, read only the file that covers it.
<!-- BEGIN references index: generated by scripts/update_skill_index.py, do not edit by hand -->
- **Authoring the pywf-oss Skills** (`references/00-authoring-references.md`): Read before adding, renaming, or editing any pywf-oss skill, reference, script, or asset.
- **Secrets** (`references/01-secrets.md`): Read before running anything that needs a token, or when adding a secret.
- **Machine Setup** (`references/02-machine-setup.md`): Read when setting up a new machine, rotating a token, or when a tool is missing or a token is missing or rejected (HTTP 401 or 403).
- **mise** (`references/03-mise.md`): Read when unsure which mise task runs what, before running a task that changes an external service, or when adding or changing a task.
- **Python Versions** (`references/04-python-versions.md`): Read when checking or changing where a Python version number is written, or when those numbers disagree.
- **uv and Dependencies** (`references/05-uv-dependencies.md`): Read when adding or removing a dependency, or writing a version constraint.
- **ruff** (`references/06-ruff.md`): Read before finishing any change to Python code, or when ruff reports something.
- **Repository Layout** (`references/07-repo-layout.md`): Read when deciding where a new top-level file or folder goes, what a root file is for, or whether a generated file is committed.
- **Special Files in the Package** (`references/08-package-files.md`): Read when adding a public name, a path, a CLI, or anything that is not an ordinary module.
- **Code Style** (`references/09-code-style.md`): Read before writing or reviewing source code in the package.
- **Test Layout** (`references/10-test-layout.md`): Read when working out a test file's path, creating or moving test files, or running tests.
- **Writing Tests** (`references/11-test-writing.md`): Read when writing or reviewing the test functions inside a test file.
- **Coverage** (`references/12-coverage.md`): Read when coverage is below 100%, when deciding whether code may be excluded, or when editing .coveragerc.
- **Sphinx** (`references/13-sphinx.md`): Read when writing reStructuredText or a docstring cross-reference, or checking a local docs build.
- **docfly** (`references/14-docfly.md`): Read when adding, moving, or ordering a docs page, or when the API reference is missing something.
- **furo** (`references/15-furo.md`): Read when changing the look of the docs, the theme settings, or the furo version.
- **sphinx-design** (`references/16-sphinx-design.md`): Read when a docs page needs more than plain text, such as a landing page, install tabs, or an FAQ.
- **nbsphinx Notebooks** (`references/17-nbsphinx.md`): Read when creating or editing a .ipynb docs page.
- **Knowledge Channels** (`references/18-knowledge-channels.md`): Read when deciding where to write down how to use or how to maintain the library, or before writing a maintainer or contributor guide.
- **GitHub Actions** (`references/19-github-actions.md`): Read when changing .github/workflows/main.yml, or when a CI run fails or shows warnings.
- **Codecov** (`references/20-codecov.md`): Read when connecting a repo to Codecov, or when the Codecov upload fails or its numbers look wrong.
- **Read the Docs** (`references/21-readthedocs.md`): Read when setting up docs hosting, or when the hosted build fails or differs from the local one.
- **Versioning and Changelog** (`references/22-versioning-and-changelog.md`): Read when choosing a version number, or writing or reviewing release notes.
- **Release** (`references/23-release.md`): Read when publishing a new version.
- **Dependency Upgrades** (`references/24-dependency-upgrades.md`): Read when upgrading or replacing a dependency, or when asked whether a new version is worth it.
- **Following the Python Release Cycle** (`references/25-python-release-cycle.md`): Read when a new CPython is released or the oldest reaches end of life, or when asked to add or drop a supported Python version.
- **Community Skills** (`references/26-community-skills.md`): Read when installing a community skill, or adding or updating a catalog entry.
- **Skill Family Workflow** (`references/27-skill-family-workflow.md`): Read when unsure which skill fits a job, when a skill finishes and the next step is unclear, or when planning a multi-step job.
<!-- END references index -->
## Scripts and assets
Run a script with `python ${CLAUDE_SKILL_DIR}/scripts/<script_name>.py` from this skill, or `python ${CLAUDE_SKILL_DIR}/../pywf-oss-base/scripts/<script_name>.py` from an invoker.
| File | What it is | Details |
| :--- | :--- | :--- |
| `scripts/check_test_layout.py` | Test layout check | `10-test-layout.md` |
| `scripts/check_one_import_per_line.py` | One-import-per-statement check, run by `mise run lint` | `06-ruff.md` |
| `scripts/check_doc_xrefs.py` | Finds cross-references that did not become links | `13-sphinx.md` |
| `scripts/update_skill_index.py` | Regenerates the References index above, or of any base skill (`--skill_dir`) | `00-authoring-references.md` |
| `scripts/check_skill_family.py` | Checks this family, or the maintenance family with `--prefix <maintain_prefix>` | `00-authoring-references.md`, `18-knowledge-channels.md` |
| `scripts/install_community_skill.py` | Stages and installs community skills | `26-community-skills.md` |
| `assets/community-skills.toml` | The pinned community skill catalog | `26-community-skills.md` |
| `assets/raw-rst-cell.json`, `assets/notebook-page-template.ipynb` | Notebook docs page templates | `17-nbsphinx.md` |
## Which skill to use
When the job is unclear, or the question is about a convention rather than an action, stay here: read the reference that covers it, then name the invoker that fits. Which invoker does which job, and the order they run in, is in `references/27-skill-family-workflow.md`.
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: 471k | 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: 471k | 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: 471k | 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 |