pywf-oss-base

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.