@robhowley/py-pit-skills 3.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Howley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# py-pit
+
+![version](https://img.shields.io/github/v/tag/robhowley/py-pit-skills)
+
+Opinionated Python backend workflows for Claude Code.
+
+`py-pit` encodes common backend development workflows as Claude/Pi skills for the modern Python API stack: FastAPI services, uv environments, SQLAlchemy models, Alembic migrations, configuration management, and CLI tooling.
+
+## Install
+
+### Claude Code
+
+Add the plugin marketplace, then install py-pit:
+
+```
+/plugin marketplace add robhowley/py-pit-skills
+/plugin install py-pit@py-pit-skills
+```
+
+### pi
+
+```bash
+pi install https://github.com/robhowley/py-pit-skills
+```  
+
+## Skills
+
+| Skill                | Activates when LLM detects                                                              |
+|----------------------|--------------------------------------------------------------------------------------------|
+| `fastapi-init`       | new FastAPI service, scaffold an API, new microservice                                     |
+| `uv`                 | dependency management, lockfiles, env setup, migration from pip/poetry                     |
+| `click-cli`          | designing or generating a new Click CLI                                                    |
+| `click-cli-linter`   | auditing or improving an existing Click CLI                                                |
+| `pydantic-schemas`   | request/response schema design, Pydantic v2 models, schema patterns                        |
+| `code-quality`       | linting setup, Ruff, pre-commit, code health tooling                                       |
+| `dockerize-service`  | local dev Docker Compose setup, containerizing a project                                   |
+| `settings-config`    | environment variable management, pydantic-settings, replacing os.getenv                    |
+| `sqlalchemy-models`  | ORM model design, SQLAlchemy 2.x patterns, relationships, migration-ready schema           |
+| `alembic-migrations` | adding Alembic, generating migrations, reviewing autogenerate diffs, safe schema evolution |
+| `fastapi-errors`     | FastAPI error handling, exception hierarchy, consistent API error responses                 |
+| `pytest-service`     | writing tests for a FastAPI service, SQLAlchemy test fixtures, DI overrides, test setup    |
+

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@robhowley/py-pit-skills",
+  "version": "3.1.1",
+  "description": "Opinionated Python backend workflows as agent skills for FastAPI, uv, SQLAlchemy, Alembic, Click, and pytest",
+  "keywords": ["pi-package"],
+  "author": "robhowley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/robhowley/py-pit-skills"
+  },
+  "files": [
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "skills": ["./skills"]
+  }
+}

package/skills/alembic-migrations/SKILL.md

@@ -0,0 +1,391 @@
+---
+name: alembic-migrations
+description: Production-safe Alembic migration workflows for SQLAlchemy
+  2.x projects. Use this skill when adding Alembic, generating
+  migrations, reviewing autogenerate diffs, fixing broken migrations, or
+  establishing a safe schema evolution workflow in a Python backend.
+disable-model-invocation: false
+---
+
+# Skill: alembic-migrations
+
+## Core position
+
+This skill establishes **safe, disciplined database migration
+workflows** using **Alembic** in SQLAlchemy 2.x projects.
+
+Autogenerate output is treated as **a draft**, never final truth.
+All migrations must be **reviewable, deterministic, and safe for
+production.**
+
+The skill prevents common failures such as:
+
+- empty autogenerate revisions
+- rename → drop/create data loss
+- broken env.py metadata wiring
+- migration history divergence
+- unsafe schema changes
+
+------------------------------------------------------------------------
+
+# Py-pit enforcement rules
+
+These rules are **always applied** when generating or reviewing
+migrations.
+
+## 1. Model import guarantee
+
+Alembic only detects models that are **imported at runtime**.
+
+A canonical module must import every ORM model so metadata is complete.
+
+Do not assume `app/`. Use the project's existing `Base` definition --
+typically at `{pkg_name}/models/base.py` (see sqlalchemy-models skill).
+
+Example:
+
+```python
+# {pkg_name}/models/base.py
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+# {pkg_name}/models/__init__.py
+from {pkg_name}.models.user import User
+from {pkg_name}.models.order import Order
+```
+
+Alembic must reference:
+
+```python
+from {pkg_name}.models.base import Base
+
+target_metadata = Base.metadata
+```
+
+This prevents **empty migrations**, the most common Alembic failure.
+
+------------------------------------------------------------------------
+
+## 2. Rename correction rule
+
+Alembic **cannot detect column renames**.
+
+If autogenerate emits:
+
+```
+drop_column
+add_column
+```
+
+for the same table in one revision, treat it as a **rename**.
+
+Replace with:
+
+```python
+op.alter_column("table", "old_name", new_column_name="new_name")
+```
+
+This prevents silent data loss.
+
+------------------------------------------------------------------------
+
+## 3. Applied migration immutability
+
+Never edit a migration that has already been applied.
+
+Correct pattern:
+
+```
+revision A (applied)
+revision B (fix)
+```
+
+Never:
+
+```
+edit revision A
+```
+
+Editing applied migrations breaks migration graphs across environments.
+
+------------------------------------------------------------------------
+
+## 4. Migration round-trip rule
+
+Every migration must succeed on a **fresh database** using:
+
+```
+upgrade head
+downgrade base
+upgrade head
+```
+
+This guarantees migrations are:
+
+- replayable
+- CI safe
+- environment independent
+
+------------------------------------------------------------------------
+
+# Trigger
+
+Use this skill when the user wants to:
+
+- add Alembic to a Python project
+- initialize migrations
+- generate migration revisions
+- review autogenerate diffs
+- fix broken migrations
+- establish safe schema evolution workflows
+
+------------------------------------------------------------------------
+
+# Migration workflow
+
+Correct workflow:
+
+```
+edit models
+↓
+generate revision
+↓
+review migration
+↓
+fix migration
+↓
+run upgrade
+```
+
+Never:
+
+```
+generate → immediately run
+```
+
+Autogenerate output **must be reviewed before execution**.
+
+------------------------------------------------------------------------
+
+# Step 0 --- Inspect existing project
+
+Before generating anything:
+
+1. Check whether `alembic/`, `alembic.ini`, and `alembic/env.py` already
+   exist. If they do, **modify the existing configuration** rather than
+   reinitializing. Never run `alembic init` if `alembic/` already exists.
+2. Identify where `Base` is defined. If the project used the
+   sqlalchemy-models skill, it will be at `{pkg_name}/models/base.py`.
+3. Identify which module imports all models (typically
+   `{pkg_name}/models/__init__.py`). This is the module env.py must import.
+4. Note the existing package root. For fastapi-init projects it is
+   `{pkg_name}/{pkg_name}/` -- never assume `app/`.
+5. Only create new files if the relevant structure is absent.
+
+------------------------------------------------------------------------
+
+# Step 1 --- Initialize Alembic
+
+If no `alembic/` directory exists, initialize:
+
+```
+alembic init alembic
+```
+
+Project layout after initialization:
+
+```text
+project/
+  alembic/
+    env.py
+    versions/
+  alembic.ini
+```
+
+------------------------------------------------------------------------
+
+# Step 2 --- Configure database connection
+
+Leave `sqlalchemy.url` in `alembic.ini` blank or as a placeholder.
+Provide the URL at runtime via the application's settings system.
+
+Example in `env.py`:
+
+```python
+from {pkg_name}.core.config import settings
+
+DATABASE_URL = settings.database_url
+```
+
+This pattern defers to the settings-config skill and avoids embedding
+credentials in version-controlled files.
+
+------------------------------------------------------------------------
+
+# Step 3 --- Configure env.py for SQLAlchemy 2.x
+
+Provide a minimal complete `env.py`. Replace `{pkg_name}` with the
+actual package name found in Step 0.
+
+```python
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from {pkg_name}.core.config import settings
+from {pkg_name}.models.base import Base
+import {pkg_name}.models  # noqa: F401 — ensures all models are imported
+
+config = context.config
+config.set_main_option("sqlalchemy.url", settings.database_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()
+```
+
+**Naming conventions**: Projects should configure SQLAlchemy
+`naming_convention` on `MetaData`. This is typically defined where
+`Base` is created (see sqlalchemy-models skill) -- not here.
+
+**Async note**: Alembic migrations run synchronously even in async
+applications.
+
+------------------------------------------------------------------------
+
+# Step 4 --- Generate migrations
+
+Create a migration revision:
+
+```
+alembic revision --autogenerate -m "add users table"
+```
+
+Migration files appear in:
+
+```
+alembic/versions/
+```
+
+------------------------------------------------------------------------
+
+# Step 5 --- Review migration output
+
+Review the migration carefully before running it.
+
+Check for:
+
+- rename mis-detections
+- destructive column drops
+- type conversion safety
+- nullable constraint changes
+- missing indexes or constraints
+
+Autogenerate is **a starting point, not a final migration.**
+
+------------------------------------------------------------------------
+
+# Step 6 --- Apply migration
+
+Apply migrations:
+
+```
+alembic upgrade head
+```
+
+Inspect state:
+
+```
+alembic current
+```
+
+View revision history:
+
+```
+alembic history
+```
+
+------------------------------------------------------------------------
+
+# Migration safety heuristics
+
+Carefully review migrations involving:
+
+- column drops
+- table drops
+- type changes
+- nullability changes
+- constraint removal
+- index removal
+
+These operations require deliberate review.
+
+------------------------------------------------------------------------
+
+# Anti-patterns
+
+Avoid:
+
+- Blind autogenerate upgrades
+- Empty migrations caused by missing model imports
+- Hardcoded database URLs
+- Editing already-applied migrations
+
+------------------------------------------------------------------------
+
+# Adjacent skills
+
+This skill typically follows:
+
+- `sqlalchemy-models` — establishes `Base`, model package structure, and
+  the import module that env.py must reference
+- `settings-config` — establishes the `settings` object and
+  `database_url` that env.py uses for the connection string
+
+------------------------------------------------------------------------
+
+# Outcome
+
+After applying this skill the project will have:
+
+- correctly wired Alembic configuration
+- reliable SQLAlchemy metadata discovery
+- disciplined migration workflows
+- safer schema evolution
+- deterministic revision history

package/skills/click-cli/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: click-cli
+description: Design, generate, and improve Python CLIs using the Click library. Focus on idiomatic architecture, command groups, modular layouts, CLI UX conventions, and avoiding common Click anti-patterns.
+disable-model-invocation: false
+---
+
+# click-cli
+
+Use this skill when designing or implementing Python command-line interfaces with **Click**.
+
+This skill should add value **above baseline Click knowledge** by enforcing:
+- good CLI architecture
+- clear command hierarchy
+- consistent argument and option design
+- idiomatic Click usage
+- avoidance of common Click anti-patterns
+
+Apply this skill when the user:
+- asks to create or design a Click CLI
+- wants a Python CLI built with Click
+- needs help structuring commands or subcommands
+- wants idiomatic Click code rather than generic CLI code
+- asks for help improving a Click-based command-line tool
+
+Do not apply when:
+- the task is unrelated to Python CLIs
+- the user explicitly wants another CLI framework
+- the question is purely about general application design rather than CLI behavior
+
+# Invocation heuristics
+
+Prefer this skill when the user:
+- mentions `click`
+- asks for command groups, subcommands, options, or arguments
+- wants a CLI architecture recommendation
+- is starting a new Python CLI project
+- wants help fixing non-idiomatic Click code
+
+Do not prefer this skill when:
+- the user explicitly wants `argparse`, `typer`, `cement`, or another framework
+- the task is general Python coding with no CLI component
+
+# Mission
+
+Produce **production-quality Click CLIs** that are:
+1. idiomatic
+2. modular
+3. easy to extend
+4. clear to use from the command line
+5. consistent in help text and option design
+
+Do not merely explain Click syntax unless the user explicitly asks for explanation.
+
+# Core Click mental model
+
+Click is best used to build CLIs around:
+- a root command
+- optional command groups
+- small, composable subcommands
+- explicit arguments and options
+- predictable help output
+
+Prefer clear command hierarchy over monolithic single-file command handlers.
+
+# The 5 Click invariants
+
+Always follow these rules.
+
+## 1. Model the CLI before writing code
+
+Define:
+- root command
+- subcommands
+- arguments
+- options
+- shared context if needed
+
+Do not jump straight into decorators without first clarifying the command structure in the answer.
+
+## 2. Use Click-native constructs
+
+Prefer:
+- `@click.group()`
+- `@click.command()`
+- `@click.option()`
+- `@click.argument()`
+- `@click.pass_context()` when context is needed
+
+Avoid mixing in patterns from other CLI frameworks unless explicitly requested.
+
+## 3. Prefer `click.echo()` for user-facing output
+
+Correct:
+
+    click.echo("Done")
+
+Avoid defaulting to:
+
+    print("Done")
+
+unless the user explicitly wants raw Python output behavior.
+
+## 4. Prefer modular command layouts for multi-command CLIs
+
+For anything beyond a very small CLI, prefer structure like:
+
+    project/
+      cli.py
+      commands/
+        init.py
+        run.py
+        status.py
+
+Avoid placing every command in one large file when the CLI clearly has multiple concerns.
+
+## 5. Design the CLI UX deliberately
+
+Ensure:
+- option names are consistent
+- help text is useful
+- positional arguments are used sparingly and intentionally
+- subcommands are discoverable
+- command names are short and predictable
+
+# Standard operating procedure
+
+## Step 1 — Design the CLI shape
+
+Identify:
+- root command name
+- subcommands
+- argument vs option boundaries
+- shared/global options
+- whether grouping is needed
+
+Return a compact command tree when useful, for example:
+
+    dataset
+      ingest
+      validate
+      publish
+
+## Step 2 — Recommend file layout
+
+If the CLI is trivial, a single file may be acceptable.
+
+If the CLI has multiple commands or domains, prefer modular layout.
+
+## Step 3 — Generate idiomatic Click code
+
+Use:
+- typed options where appropriate
+- clear help strings
+- small command handlers
+- `click.echo()` for output
+- context objects only when they provide real value
+
+## Step 4 — Validate the design
+
+Before finishing, verify:
+- the hierarchy is logical
+- the code matches the designed command structure
+- option names are consistent
+- help text is present where needed
+- the solution uses Click idioms rather than generic CLI habits
+
+# Output contract
+
+When generating or designing a Click CLI, prefer this structure in your answer:
+
+1. CLI Architecture
+2. Recommended File Layout
+3. Click Implementation
+4. Usage Examples
+
+If the user asks for only code, still internally follow the same structure and provide the code cleanly.
+
+# Anti-pattern detection
+
+Call out these problems explicitly when they appear:
+- monolithic all-in-one CLI files
+- `print()` instead of `click.echo()`
+- argparse-style logic mixed into Click code
+- manual help formatting that Click should generate
+- inconsistent option naming
+- excessive positional arguments
+- unnecessary global state
+
+# Response style
+
+- concise
+- concrete
+- code-first when implementation is requested
+- architecture-aware
+- no unnecessary framework comparisons unless relevant
+
+# Completion checklist
+
+Before finishing an answer verify:
+- the CLI structure is clear
+- Click-native decorators and patterns are used
+- output uses `click.echo()` where appropriate
+- the layout is modular when the CLI complexity warrants it
+- the answer adds architectural guidance, not just decorator syntax