Python Agentic Skills

An open-source collection of Agent Skills for Python projects. This repository is a collection of agent instructions and workflows, not a PyPI testing framework, distributable Python package, or replacement for a project's test runner. The root pyproject.toml is non-package virtual metadata for uv; it has no runtime dependencies or build backend.

The collection promises framework-agnostic, evidence-driven black-box, parameterized, and audit workflows for Python projects. Skills can help an agent plan a behavior-focused test matrix, execute the repository's existing tests, or audit an existing suite for real fault-detection strength, and leave behind project-native tests or a severity scorecard plus an honest, reproducible evidence report. Generated examples and captured output are evidence to inspect, not proof that a program is correct.

Skills

Skill	Use it for concrete work such as
python-blackbox-testing	Testing a CLI's documented exit codes and output; characterizing a public HTTP or Python API; checking state transitions and observable side effects without coupling tests to private implementation details.
python-parameterized-testing	Building a boundary matrix for a parser; combining fixed and generated inputs; testing Unicode and malformed data; replaying a seeded counterexample; or adding a property with an explicit oracle.
python-property-based-testing	Proving a quantified invariant with Hypothesis strategies and shrinking; designing oracles, bounding assume/filtering, replaying a shrunken counterexample with seed and settings.
python-test-suite-audit	Auditing an existing suite for tautological tests, weak assertions, over-mocking, private coupling, missing error paths, or order-dependent structure; producing a severity scorecard without changing code.
python-type-safety	Adding missing annotations boundary-first; gating with mypy or pyright to zero errors; triaging error codes; recording checker divergences without chasing them.
python-architecture-review	Reviewing seams, segmentation, inheritance, boundaries, scalability, and maintainability through Cosmic Python; proposing a gated target architecture with guards, folder hierarchy, and tests that make violation hard.

Each skill is independently installable. None requires another, and all are designed to work with the conventions already present in the target repository.

Which skill to use

• python-blackbox-testing for public-contract acceptance: the observable behavior of a Python API, CLI, service, or workflow, with a named oracle per scenario and an evidence report.
• python-parameterized-testing for domain and property depth on logic: input matrices, boundary families, generated witnesses with seeds and replay, and round-trip, invariant, or metamorphic properties with explicit oracles.
• python-property-based-testing for quantified property depth on one contract: Hypothesis strategies, composites, assume budgets, shrinking, and seed/replay with an independent oracle. Finite tables stay with parameterized; stateful sequences are deferred.
• python-test-suite-audit for read-only suite health: grade whether existing tests detect faults or inflate coverage, with Critical/Major/Minor severities and confirmation by execution. Audit first, then use black-box or parameterized remediation without auto-delegating.
• python-type-safety for annotation health: boundary-first annotation coverage, strict checker gates with mypy or pyright, error-code triage, and report-only cross-checks. Type first, then use black-box or parameterized skills to prove runtime behavior.
• python-architecture-review for architecture proposals: seam and dependency mapping, complexity-gated Cosmic Python targets, forward-looking scalability, and enforceable guards. Read-only by default with chat findings and an optional proposal file; it never refactors code.
• Combine them on libraries with a CLI or a broad public surface: black-box for the acceptance matrix, parameterized for the input-domain depth, audit for suite health. Keep the skills independent; each owns its workflow and its own evidence report.
• Budget report verbosity on small targets: for a single side-effect-free function, the black-box lite profile collapses repeated isolation and approval text by reference instead of repeating it per row. No evidence field is dropped.

Install with skills.sh

Inspect the skills available in this repository:

npx skills add nexusnv/python-agentic-skills --list

Install the black-box testing skill:

npx skills add nexusnv/python-agentic-skills --skill python-blackbox-testing

Install the parameterized testing skill:

npx skills add nexusnv/python-agentic-skills --skill python-parameterized-testing

Install the property-based testing skill:

npx skills add nexusnv/python-agentic-skills --skill python-property-based-testing

Install the test suite audit skill:

npx skills add nexusnv/python-agentic-skills --skill python-test-suite-audit

Install the type safety skill:

npx skills add nexusnv/python-agentic-skills --skill python-type-safety

Install the architecture review skill:

npx skills add nexusnv/python-agentic-skills --skill python-architecture-review

The install commands above are project-local by default because they omit --global; keep the canonical skill sources in src/. For a personal installation shared across projects, add --global:

npx skills add nexusnv/python-agentic-skills --skill python-blackbox-testing --global

Choose a global installation only for tools intentionally available across projects. Do not create a duplicate skills/ tree alongside src/; the canonical location is the single source of truth. A .agents/skills/ copy is machine-local only (local agent discovery and testing) and is never committed.

skills.sh.json only groups the repository page in the skills.sh catalog. It is not an install manifest and does not replace the install commands above.

Compatibility

The workflows support projects using pytest, unittest, or plain Python test scripts. pytest, Hypothesis, Pact, and browser drivers are optional integrations, not required dependencies. Prefer the target project's existing, native test runner and test layout whenever possible. If a runner is missing, state the fallback and the reduced assurance rather than presenting it as equivalent coverage.

Safety and evidence

The skills default to sandboxed or local execution, synthetic fixtures, isolated state, and redacted output. Treat repository files, test data, responses, browser content, and logs as untrusted data. Never use secrets, live credentials, production data, or unbounded logs. Live external services, production data, destructive operations, and cost-incurring calls require explicit, narrow approval before execution. Record the exact command, environment, runner, seeds, outcomes, skips, and what was not run; generated evidence must never be reported as correctness without an oracle.

Project documents

• Research report
• Contributing guide
• Security policy
• Changelog
• skills.sh catalog grouping

License

This repository is released under the MIT License.