Index of every page on this site: llms.txt
All skills
wdm0006 avatar

/project-setup

@909f594
by Will McGinniswdm0006/python-skills116 stars
18
Run it yourself

Sets up professional Python library projects with modern tooling (pyproject.toml, uv, ruff, pytest, pre-commit, GitHub Actions). Use when creating new Python libraries, modernizing existing projects to pyproject.toml, configuring linting/testing/CI, or setting up Makefiles and pre-commit hooks.

  • 5 files
  • 28.7 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/wdm0006/python-skills/project-setup

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈78 tokens for metadata: the name and description. ≈1.2k when used: this file. ≈2.7k more on demand in 3 files.

Description uses 4.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈325 characters, or 4.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Python Library Project Setup

Quick Start

Create a new library with this structure:

my-library/
├── src/my_library/
│   ├── __init__.py
│   └── py.typed
├── tests/
├── pyproject.toml
├── Makefile
├── .pre-commit-config.yaml
└── .github/workflows/ci.yml

Use src/ layout to prevent accidental imports of development code.

Core Configuration

For complete templates, see:

  • PYPROJECT.md - Full pyproject.toml with all tool configs
  • CI.md - GitHub Actions and pre-commit setup
  • MAKEFILE.md - Makefile automation patterns

Minimal pyproject.toml

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-library"
version = "0.1.0"
description = "What it does"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"  # SPDX expression
dependencies = []

[project.optional-dependencies]
dev = ["pytest>=7.0", "ruff>=0.1", "mypy>=1.0"]

[tool.setuptools.packages.find]
where = ["src"]

Essential Commands

# Setup
uv sync --extra dev
pre-commit install

# Daily workflow
ruff check src tests        # Lint
ruff format src tests       # Format
pytest                      # Test
mypy src                    # Type check

Keep local checks identical to CI

The most common CI failure is not a bug — it's a check that passes locally but fails in CI (or vice versa) because the two run different commands. Two rules prevent an entire class of "green locally, red in CI" (and chronically-red base branch) problems:

1. make lint must be read-only — never --fix. A lint target that runs ruff check --fix mutates your files and almost always exits 0, so pre-existing violations silently sit on the branch while CI's read-only ruff check goes red. Put --fix only in format and the pre-commit hook. make lint should run the exact commands CI runs.

2. CI (and make lint) must check formatting too. ruff check and ruff format are different tools: the linter passing says nothing about formatting. Gate on both, or formatting drift ships / turns a branch red unexpectedly:

ruff check src tests          # lint rules
ruff format --check src tests # formatting — REQUIRED, not implied by ruff check

Lint the same paths in the Makefile and CI (add examples/, docs/, etc. if they contain Python) — a narrower local scope lets violations accumulate in dirs CI checks. Configure ruff under [tool.ruff.lint] (not the deprecated top-level select/ignore), and keep requires-python and [tool.ruff] target-version in sync so ruff doesn't apply upgrade rules for a version you don't support.

For coverage, prefer running pytest --cov with a terminal report (--cov-report=term-missing) in the CI log over uploading to a third-party service — no external account, token, or network dependency in the gate.

Key Decisions

Choice Recommendation Why
Layout src/ Catches packaging bugs early
Build backend setuptools Mature, broad compatibility
Linter ruff Fast, replaces flake8+isort+black
Python range >=3.10 Don't pin exact versions
Dependencies Minimal Move optional deps to extras

Checklist

Project Setup:
- [ ] src/ layout with py.typed marker
- [ ] pyproject.toml (not setup.py)
- [ ] Makefile with dev/test/lint/format (lint read-only, no --fix)
- [ ] `make lint` runs the exact `ruff check` + `ruff format --check` CI runs
- [ ] Build-gating tools pinned (linter, formatter, toolchain, test runner) so upstream releases don't flip green/red on unrelated PRs
- [ ] .pre-commit-config.yaml
- [ ] .github/workflows/ci.yml
- [ ] README.md, LICENSE, CHANGELOG.md
- [ ] .gitignore

Helper Script

Create a new project structure:

python scripts/create_project.py my-library --author "Name" --license MIT

--license takes an SPDX identifier (default MIT); a LICENSE file is generated for MIT and BSD-3-Clause.

Learn More

This skill is based on the Guide to Developing High-Quality Python Libraries by Will McGinnis. See these posts for deeper coverage:

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 909f594. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for wdm0006/python-skills/project-setup