Python Skill Pack

What This Pack Covers

Two skills: one that reviews Python code against real project conventions (a Validator), and one that scaffolds test files correctly (a Workflow). Together they cover the two moments a Python-focused skill earns its keep most: reviewing code someone just wrote, and setting up the boilerplate for code that’s about to be written.

Skill 1: python-convention-check

---
name: python-convention-check
description: Reviews Python code against project conventions — type hints, docstrings, import ordering, and dependency pinning. Use when reviewing a Python pull request, checking a new module before merge, or when the user asks whether their Python code follows project style.
metadata:
  version: "1.0.0"
---

## Review checklist

Check the file against these rules, in order, and report every failing rule
— not just the first one found:

1. **Type hints.** Every function signature has parameter and return type
   hints, except `__init__` return types (always `None`, may be omitted).
2. **Docstrings.** Every public function and class has a docstring. Private
   functions (prefixed `_`) are exempt unless they exceed 15 lines.
3. **Import ordering.** Standard library imports, then third-party, then
   local — each group separated by a blank line, alphabetized within
   each group.
4. **Dependency pinning.** Any new entry in `pyproject.toml` or
   `requirements.txt` specifies a version constraint — never a bare
   package name with no version at all.
5. **No mutable default arguments.** Flag any `def f(x=[])` or
   `def f(x={})` — these are a well-known Python foot-gun.

For each failure, report: the file and line, which rule failed, and a
corrected example. If everything passes, confirm explicitly.

Pattern: Validator, per Skill Design Patterns — checks against fixed rules and reports specifics, never producing new code itself.

Skill 2: python-test-scaffold

---
name: python-test-scaffold
description: Generates a pytest test file skeleton for a given Python module, following this project's test conventions. Use when the user asks to write tests, add test coverage, or scaffold a test file for a module that doesn't have one yet.
metadata:
  version: "1.0.0"
---

## Generate a test scaffold

1. Read the target module and identify every public function and class
   method (skip anything prefixed `_`).
2. Create `tests/test_<module_name>.py` if it doesn't already exist.
3. For each public function, add one test stub named
   `test_<function_name>_<expected_behavior>` — e.g.
   `test_parse_config_raises_on_missing_file`.
4. Include a `# TODO: implement` comment in each stub body rather than
   leaving it empty — an empty `pass` body is easy to forget about.
5. Add necessary imports (`pytest`, the module under test) at the top,
   following the import-ordering rule from python-convention-check.

Do not write actual test assertions — this skill's job is the scaffold,
not the test logic itself, which needs a human's judgment about what
"correct" behavior actually is for each function.

Pattern: Workflow — a fixed sequence producing a consistent structure every time, deliberately stopping short of writing assertions a human needs to author with real judgment.

Testing Both Skills

Before trusting either in your own workflow, run the checks from the free course’s Testing Skills lesson:

• python-convention-check — try it against a file with zero violations (should confirm cleanly), a file with exactly one violation (should catch it precisely), and a file with several different violation types at once (should report all of them, not stop at the first).
• python-test-scaffold — try it against a module with a mix of public and private functions (should skip the private ones), and against a module that already has a partial test file (decide, and state in the skill, whether it should add missing stubs or leave the existing file alone — as written above, it doesn’t say, which is worth fixing before you rely on it).

That last point is deliberate: it’s a small, realistic gap for you to notice and patch, the same kind of gap the quality checklist is built to catch.

Customizing for Your Own Project

The convention checklist above is a reasonable default, not a universal one — your project may use different docstring conventions (Google-style vs. NumPy-style), a different import sorter, or additional rules entirely (a required CHANGELOG.md entry, a specific commit-message format). Treat the five rules here as a starting shape, and add or replace rules to match what your team actually enforces in code review today — a convention-check skill only earns trust once it matches real review comments your team already makes by hand.

Summary

• python-convention-check is a Validator skill catching real, common Python review issues — missing type hints, missing docstrings, import order, unpinned dependencies, mutable default arguments
• python-test-scaffold is a Workflow skill producing consistent test file structure, deliberately stopping before writing actual assertions
• Both need testing against real files with varied violation counts before you’d trust them — not just a single clean-pass check
• Adjust the rule set to match your own team’s actual review conventions before relying on either skill

Next, the same treatment for SQL — a validator focused on migration safety, and a skill for writing queries that are actually reviewable.