From python-package
This skill should be used when the user is writing a CONTRIBUTING.md, setting up developer onboarding, creating a Makefile or justfile, adding issue templates, adding PR templates, writing a README, creating a CODE_OF_CONDUCT.md, setting up CODEOWNERS, adding .editorconfig, configuring devcontainers, labeling good first issues, or building project community and governance. Covers one-command dev setup, task automation, contributor funnel, and community health files.
npx claudepluginhub oborchers/fractional-cto --plugin python-packageThis skill uses the workspace's default tool permissions.
The single biggest factor in whether someone contributes to a project is how fast they can get a working development environment. If clone-to-passing-tests takes more than 60 seconds, every additional minute costs potential contributors. FastAPI, Pydantic, and httpx all converge on the same pattern: one prerequisite (uv), one command (`uv sync --group dev`), and every common task wrapped in a M...
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
The single biggest factor in whether someone contributes to a project is how fast they can get a working development environment. If clone-to-passing-tests takes more than 60 seconds, every additional minute costs potential contributors. FastAPI, Pydantic, and httpx all converge on the same pattern: one prerequisite (uv), one command (uv sync --group dev), and every common task wrapped in a Makefile target. Invest in developer experience early -- every minute spent here pays back tenfold in contributor time saved.
Target clone-to-running-tests in under 60 seconds. The modern standard uses uv with a committed lock file.
git clone https://github.com/org/my-package
cd my-package
uv sync --group dev # Creates venv, installs package + all dev deps
uv run pytest # Tests pass on first try
What makes this possible:
uv.lock to the repo for deterministic installs across machines[dependency-groups] in pyproject.toml) with a dev group| Step | Legacy (2020) | Modern (2026) |
|---|---|---|
| Install Python | pyenv install 3.x | uv handles it |
| Create virtualenv | python -m venv .venv | uv sync creates it |
| Activate | source .venv/bin/activate | Not needed (uv run) |
| Install deps | pip install -r requirements-dev.txt | uv sync --group dev |
| Install package | pip install -e . | Included in uv sync |
| Run tests | pytest | uv run pytest |
| Total commands | 5-6 | 2 (clone + sync) |
Wrap every common operation in a Makefile target. Contributors type make test instead of remembering uv run pytest --cov --cov-report=term-missing -x -v. Use make help as the default target to make commands discoverable.
Required targets:
| Target | Purpose |
|---|---|
make dev | Install all dev dependencies + pre-commit hooks |
make test | Run tests with coverage |
make test-fast | Run tests without coverage (-x -q) |
make lint | Run Ruff check + mypy |
make format | Run Ruff format + fix |
make docs | Serve docs locally with live reload |
make build | Build sdist + wheel |
make clean | Remove build artifacts and caches |
make help | Show available targets (default goal) |
Every CI step must map to a Makefile target. make lint locally runs the same checks as the lint CI job. If contributors cannot reproduce CI locally, they will push-and-pray.
Use justfile instead of Makefile only for team projects where contributors can install just. For open source libraries, Makefile is the safe default because it is pre-installed on macOS and Linux.
Include a CONTRIBUTING.md in the repository root. GitHub surfaces it automatically when users open issues and PRs. Structure it as a funnel from easiest to hardest contributions, following FastAPI's exemplary pattern.
Required sections (in order):
Rules for the contributing guide:
Place YAML form templates in .github/ISSUE_TEMPLATE/. Use structured forms instead of freeform markdown. Provide separate templates for bug reports and feature requests.
Bug report template must collect:
Feature request template must collect:
Disable blank issues in .github/ISSUE_TEMPLATE/config.yml with blank_issues_enabled: false. Redirect questions to GitHub Discussions via contact_links. Redirect security reports to the security advisory page.
Place at .github/pull_request_template.md. Keep it short -- five to seven checklist items is the sweet spot. Templates with 20 checkboxes get ignored.
Required checklist items: tests added/updated, documentation updated, changelog entry added, CI passes, self-reviewed the diff. Include a type-of-change section (bug fix, feature, breaking change, docs, refactoring).
Adopt the Contributor Covenant v2.1. Place it at CODE_OF_CONDUCT.md in the repository root. Designate specific enforcement contacts (not just "the project team"). Its absence signals that the project has not thought about community safety.
Place at .github/CODEOWNERS. Map file patterns to responsible reviewers. This automatically requests reviews from the right people and, with branch protection, requires their approval before merging.
* @org/maintainers
/docs/ @org/docs-team
pyproject.toml @org/maintainers
Ship an .editorconfig to enforce consistent whitespace regardless of individual editor settings. Set 4-space indent for Python, 2-space for YAML/JSON/TOML, tab for Makefile, and disable trailing whitespace trimming for Markdown.
See the security-supply-chain skill for the full SECURITY.md template, reporting channels, and response timeline.
The README is the front page of the project. Most potential users decide within 30 seconds whether to keep reading.
Required sections (in order):
pip install my-package| Include in README | Keep out of README |
|---|---|
| Badges (4 max) | Full API reference |
| One-sentence pitch | Changelog |
| Feature list (5-8 items) | Detailed contributing instructions |
| Installation command | Every configuration option |
| Minimal quick-start example | CI matrix badges |
| Link to full docs | Animated GIFs (unless CLI tool) |
Label issues as good first issue to signal approachable entry points. Effective good-first-issues are well-scoped (one file change), documented (pointers to relevant code), and non-blocking (not on the critical path).
| Good "Good First Issue" | Bad "Good First Issue" |
|---|---|
"Add type annotation to parse_config() in src/config.py" | "Refactor the plugin system" |
"Add test for empty input to Client.fetch()" | "Fix the CI pipeline" |
"Fix typo in API reference for validate()" | "Improve performance" |
Structure the contribution path as a deliberate funnel: star/use the package, report a bug, fix a typo, add a test, implement a feature, review PRs, become a regular contributor. Each step should be explicitly documented and encouraged in CONTRIBUTING.md.
When reviewing a project for developer experience and community health:
uv sync --group dev && uv run pytestuv.lock is committed to the repository for deterministic installshelp, dev, test, lint, format, docs, build, and clean targets.github/ISSUE_TEMPLATE/ contains bug report and feature request YAML form templates.github/ISSUE_TEMPLATE/config.yml disables blank issues and redirects questions to Discussions.github/pull_request_template.md exists with 5-7 checklist items.editorconfig is present with correct settings for Python, YAML, Makefile, and Markdowngood first issue labels exist on well-scoped, documented issues