Agent skill

stinkysnake

Progressive Python quality improvement with static analysis, type refinement, modernization planning, plan review, and test-driven implementation. Use when addressing technical debt, eliminating Any types, applying modern Python patterns, or refactoring for better design.

View SKILL.md on GitHub Repository
Stars 33
Forks 4

Install this agent skill to your Project

npx add-skill https://github.com/Jamie-BitFlight/claude_skills/tree/main/plugins/python3-development/skills/stinkysnake

SKILL.md

<file_paths>$ARGUMENTS</file_paths>

Python Quality Improvement System

Systematic Python code quality improvement through static analysis, type refinement, modernization planning with review, and test-driven implementation.

Arguments

<file_paths/>

Workflow Overview

text
┌─────────────────────────────────────────────────────────────────────────────┐
│                         STINKYSNAKE WORKFLOW                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Phase 1: STATIC ANALYSIS                                                   │
│  ├── Run formatters (ruff format)                                           │
│  ├── Run linters (ruff check --fix)                                         │
│  ├── Run type checkers (ty default; mypy/pyright if project configures)    │
│  └── Auto-fix all resolvable issues                                         │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 2: TYPE ANALYSIS                                                     │
│  ├── Determine minimum Python version                                       │
│  ├── Inventory all `Any` types                                              │
│  ├── Map type dependencies                                                  │
│  └── Identify typing gaps                                                   │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 3: MODERNIZATION PLANNING                                            │
│  ├── Plan Protocol usage for duck typing                                    │
│  ├── Plan Generic type parameters                                           │
│  ├── Plan TypeGuard narrowing                                               │
│  ├── Plan TypeAlias definitions                                             │
│  ├── Plan TypedDict for dict shapes                                         │
│  ├── Plan dataclass/Pydantic models                                         │
│  └── Plan library modernization (httpx, orjson, etc.)                       │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 4: PLAN REVIEW (context: fork)                                       │
│  ├── Review against pythonic best practices                                 │
│  ├── Verify against online references                                       │
│  ├── Check feasibility                                                      │
│  ├── Identify breaking changes                                              │
│  └── Produce review report                                                  │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 5: PLAN REFINEMENT                                                   │
│  └── Update plan based on review feedback                                   │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 6: DOCUMENTATION DISCOVERY                                           │
│  ├── Find docs requiring updates                                            │
│  └── Note what changes are needed                                           │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 7: INTERFACE DESIGN                                                  │
│  └── Create interfaces/protocols first                                      │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 8: TEST-FIRST (context: fork, python-pytest-architect)               │
│  ├── Write failing tests against interfaces                                 │
│  └── Stop after tests written                                               │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 9: IMPLEMENTATION (/python3-development:snakepolish)                                     │
│  ├── context: fork with python-cli-architect                                │
│  ├── Follow plans and implement functions                                   │
│  └── Run tests until passing                                                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Companion Plugins

This skill integrates with plugins in the same marketplace:

holistic-linting Plugin

Activation: Skill(skill: "holistic-linting:holistic-linting")

Provides: Linting rules knowledge base, linting-root-cause-resolver agent, automatic linter detection.

pre-commit Plugin

Activation: Skill(skill: "python3-development:pre-commit")

Provides: Git hook automation for quality gates.

Phase 1: Static Analysis

Run automated tools to fix all resolvable issues before manual work begins.

Step 1.1: Format Code

bash
# Format all Python files
uv run ruff format $ARGUMENTS

# Verify formatting
uv run ruff format --check $ARGUMENTS

Step 1.2: Auto-Fix Linting Issues

bash
# Fix all auto-fixable issues
uv run ruff check --fix $ARGUMENTS

# Fix unsafe fixes if appropriate
uv run ruff check --fix --unsafe-fixes $ARGUMENTS

Step 1.3: Run Type Checkers

Inspect .pre-commit-config.yaml (then CI) first, then pyproject.toml. Default for new work: ty. If hooks or CI invoke mypy: run mypy and do not rip it out. Do not switch to mypy only because [tool.mypy] exists — many repos keep that section while ty is the real gate.

bash
# Default (ty) — when hooks run ty, [tool.ty] is active, or no mypy invocation in hooks/CI
uv run ty check $ARGUMENTS

# Project that actually runs mypy in hooks/CI — respect mypy.ini / [tool.mypy]
uv run mypy $ARGUMENTS

# Project standardizes on pyright / basedpyright
uv run pyright $ARGUMENTS
# uv run basedpyright $ARGUMENTS

Step 1.4: Document Remaining Issues

Create inventory of issues that cannot be auto-fixed:

text
## Static Analysis Results

### Auto-Fixed
- [X] Formatting issues: N fixed
- [X] Import sorting: N fixed
- [X] Safe linting fixes: N fixed

### Requires Manual Resolution
| File:Line | Rule | Issue | Complexity |
|-----------|------|-------|------------|
| src/api.py:45 | ANN001 | Missing type annotation | Low |
| src/models.py:120 | B006 | Mutable default | Medium |

Phase 2: Type Analysis

Determine Python compatibility and inventory typing gaps.

Step 2.1: Determine Minimum Python Version

Check project configuration:

bash
# Check pyproject.toml
grep -E "requires-python|python_requires" pyproject.toml

# Check setup.py if exists
grep -E "python_requires" setup.py

Document the constraint:

text
## Python Version Constraint

Minimum Version: Python 3.11
Reason: [from pyproject.toml requires-python = ">=3.11"]

Available Language Features:
- Native generics (list[str], dict[str, int])
- Union syntax (str | None)
- Pattern matching (match/case)
- Exception groups
- Self type
- TypeVarTuple
- Required/NotRequired in TypedDict

Step 2.2: Inventory All Any Types

Search for explicit and implicit Any usage:

bash
# Find explicit Any imports and usage
uv run rg "from typing import.*Any|: Any|-> Any" $ARGUMENTS

# Implicit Any / strict diagnostics — use the same checker the project uses
uv run ty check $ARGUMENTS 2>&1 | grep -iE "Any|implicit" || true
# If project uses mypy instead:
# uv run mypy --strict $ARGUMENTS 2>&1 | grep -E "has type.*Any|Implicit.*Any"

Create inventory:

text
## Any Type Inventory

### Explicit Any Usage
| Location | Variable | Current Type | Proposed Type |
|----------|----------|--------------|---------------|
| api.py:23 | response | Any | dict[str, JSONValue] |
| utils.py:45 | callback | Any | Callable[[str], None] |

### Implicit Any (from untyped libraries)
| Location | Source | Mitigation |
|----------|--------|------------|
| client.py:12 | third_party.get() | Add type stub or cast |

Step 2.3: Map Type Dependencies

Understand how types flow through the codebase:

text
## Type Dependency Map

Entry Points (public API):
- cli.main() -> int
- api.fetch_data(url: str) -> ???  # Needs typing

Internal Flow:
fetch_data() -> parse_response() -> validate() -> Model

Type Gaps:
- parse_response returns Any
- validate accepts Any

Phase 3: Modernization Planning

Plan how to apply modern Python features to eliminate type gaps and improve design.

Step 3.1: Load modernpython Skill

text
Skill(skill: "python3-development:modernpython")

Step 3.2: Plan Type System Improvements

For each Any in the inventory, plan the replacement using appropriate constructs:

Select the appropriate type construct for each Any replacement:

  • Protocol — duck-typed objects sharing behavior without inheritance
  • Generic — containers/functions preserving type info across multiple types
  • TypeGuard — runtime checks that should narrow types for the checker
  • TypeAlias — repeated complex types needing a name
  • TypedDict — dicts with known keys and specific value types
  • Dataclass/Pydantic — structured data with optional validation

See references/type-patterns.md for before/after code samples and library modernization reference table.

Step 3.3: Plan Library Modernization

See the library modernization reference table in references/type-patterns.md#library-modernization-reference.

Step 3.4: Create Modernization Plan Document

Resolve the plan directory at runtime: uv run python -c 'from dh_paths import plan_dir; print(plan_dir())' (typically ~/.dh/projects/{slug}/plan/). Create the plan at {plan_dir}/stinkysnake-plan.md using the template in references/plan-templates.md#modernization-plan-template-phase-3-output.

Phase 4: Plan Review

Delegate to a review agent with context fork to critique the plan.

Step 4.1: Launch Plan Review Agent

Delegate to code-reviewer using the prompt in references/agent-prompts.md#phase-4-plan-review.

Step 4.2: Review Report Structure

The reviewer produces a report following the template in references/plan-templates.md#plan-review-report-template-phase-4-output.

Phase 5: Plan Refinement

Update the plan based on review feedback.

Step 5.1: Address Blocking Issues

For each blocking issue:

  1. Understand the concern
  2. Research alternatives
  3. Update the plan
  4. Document the change

Step 5.2: Acknowledge Warnings

For each warning:

  1. Add mitigation to the plan
  2. Or accept risk with justification

Step 5.3: Consider Suggestions

For each suggestion:

  1. Evaluate effort vs benefit
  2. Include if beneficial, defer if not

Step 5.4: Update Plan Document

Update {plan_dir}/stinkysnake-plan.md (resolve plan_dir as in Step 3.4) using the revised plan format in references/plan-templates.md#revised-plan-template-phase-5-output.

Phase 6: Documentation Discovery

Find documentation that needs updating after code changes.

Step 6.1: Inventory Documentation

bash
# Find all documentation files
fd -e md -e rst -e txt . docs/ README.md CHANGELOG.md

# Find docstrings in affected files
uv run rg "^\s+\"\"\"" $ARGUMENTS

Step 6.2: Map Code to Docs

Create documentation update plan using the template in references/plan-templates.md#documentation-update-plan-template-phase-6-output.

Phase 7: Interface Design

Create interfaces and protocols before implementation.

Step 7.1: Define Type Aliases

python
# src/types.py
from typing import TypeAlias

JSONValue: TypeAlias = str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
APIResponse: TypeAlias = dict[str, JSONValue]

Step 7.2: Define Protocols

python
# src/protocols.py
from typing import Protocol

class Handler(Protocol):
    def handle(self, data: bytes) -> None: ...

class Serializable(Protocol):
    def to_dict(self) -> dict[str, Any]: ...

Step 7.3: Define TypedDicts

python
# src/schemas.py
from typing import TypedDict, NotRequired

class UserData(TypedDict):
    name: str
    email: str
    age: NotRequired[int]

Step 7.4: Define Data Classes

python
# src/models.py
from dataclasses import dataclass

@dataclass
class User:
    name: str
    email: str
    age: int | None = None

Phase 8: Test-First Implementation

Delegate to python-pytest-architect to write failing tests against the interfaces.

Step 8.1: Launch Test Writing Agent

Delegate to python-pytest-architect using the prompt in references/agent-prompts.md#phase-8-test-writing-agent.

Step 8.2: Verify Tests Fail

bash
# Run tests - they should fail
uv run pytest tests/ -v

# Expected output: X failed, 0 passed

Phase 9: Implementation

Use the /python3-development:snakepolish skill to implement until tests pass.

Step 9.1: Launch Implementation Skill

text
/python3-development:snakepolish $ARGUMENTS

This skill:

  • Has context: fork to work in isolation
  • Uses agent: python-cli-architect for implementation
  • Follows the refined plan
  • Runs tests after each change
  • Continues until all tests pass

Step 9.2: Verify All Tests Pass

bash
# Final verification
uv run pytest tests/ -v
uv run ty check $ARGUMENTS
# If project uses mypy: uv run mypy $ARGUMENTS
uv run ruff check $ARGUMENTS

Output Artifacts

The complete workflow produces:

Artifact Location Purpose
Static Analysis Results .claude/reports/static-analysis-{ts}.md Auto-fix summary
Type Inventory .claude/reports/type-inventory-{ts}.md Any types found
Modernization Plan {plan_dir}/stinkysnake-plan.md Implementation plan
Plan Review .claude/reports/plan-review-{ts}.md Review feedback
Revised Plan {plan_dir}/stinkysnake-plan.md Updated plan
Doc Update Plan .claude/reports/doc-updates-{ts}.md Docs to change
Test Files tests/test_*.py Failing tests
Implementation src/ Passing code

Quick Reference

Skill Activations

text
Skill(skill: "holistic-linting:holistic-linting")     # Linting workflows
Skill(skill: "python3-development:pre-commit")       # Git hooks
Skill(skill: "python3-development:modernpython")     # Python 3.11+ patterns
Skill(skill: "python3-development:python3-development")  # Core patterns

Agent Delegations

text
Agent(subagent_type="holistic-linting:linting-root-cause-resolver", ...)  # Phase 1 linting
Agent(subagent_type="python3-development:code-reviewer", ...)     # Phase 4 review
Agent(subagent_type="python3-development:python-pytest-architect", ...)  # Phase 8 tests

Related Skills

text
/python3-development:snakepolish  # Phase 9 implementation (context: fork)

Agent Team Alternative for Phase 4

When Phase 4 (quality improvement implementation) involves 3+ independent improvement areas where findings from one area inform or challenge another, consider agent teams instead of sequential subagents.

When Agent Teams Apply

A quality improvement workflow is a candidate for agent teams when ALL of these are true:

  1. 3+ independent improvement areas (enough parallelism to justify coordination overhead)
  2. Areas benefit from cross-communication (findings from one area inform or challenge another)
  3. No shared file mutations (each teammate owns different files)
  4. Result is a synthesis, not a concatenation (value comes from combining, deduplicating, or reconciling findings across areas)

When Subagents Suffice

A quality improvement workflow is NOT a candidate for agent teams when:

  • Only 1-2 improvement areas (subagent overhead is lower)
  • Areas are fully independent with no cross-communication need (subagents suffice)
  • Result is just collecting N outputs (no synthesis step)
  • Work is sequential (each step depends on the previous)

Reference

See ../../../plugin-creator/skills/claude-skills-overview-2026/resources/agent-teams.md for complete criteria, architecture, and usage patterns.

SOURCE: Lines 27-39 of agent-teams.md (accessed 2026-02-06)

References

Skill Reference Files

  • ../python3-development/references/python3-standards.md — Shared development standards, knowledge graph, and process graph
  • references/plan-templates.md — document formats for modernization plan, review report, revised plan, and documentation update plan
  • references/agent-prompts.md — pre-built delegation prompts for Phase 4 review agent and Phase 8 test writing agent

External Documentation

Companion Plugins

  • holistic-linting - Linting rules knowledge base
  • pre-commit - Git hook automation

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

Jamie-BitFlight/claude_skills

ccc

This skill should be used when code search is needed (whether explicitly requested or as part of completing a task), when indexing the codebase after changes, or when the user asks about ccc, cocoindex-code, or the codebase index. Trigger phrases include 'search the codebase', 'find code related to', 'update the index', 'ccc', 'cocoindex-code'.

33 4
Explore
Jamie-BitFlight/claude_skills

agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.

33 4
Explore
Jamie-BitFlight/claude_skills

delegate

Quick delegation template for sub-agent prompts. Use when assigning work to a sub-agent, before invoking the Agent tool, or when preparing prompts for specialized agents. Provides the WHERE-WHAT-WHY framework. For comprehensive delegation guidance, activate the agent-orchestration how-to-delegate skill.

33 4
Explore
Jamie-BitFlight/claude_skills

swarm-spawning

Spawn agents and teammates in Claude Code swarms. Use when choosing between subagents vs teammates, selecting agent types (Explore, Plan, general-purpose, plugin agents), configuring spawn backends (in-process, tmux, iterm2), or setting environment variables for spawned agents.

33 4
Explore
Jamie-BitFlight/claude_skills

knowledge-explorer

Manage the research/ knowledge base (KB) of tool and library research entries. Use when browsing KB topics, adding new research entries, updating existing entries with dated revisions, fetching GitHub repo metadata into a draft KB entry, or migrating old-format entries to skill-spec frontmatter. Triggers on tasks like "what do we have on X", "add this to the KB", "update the KB entry for Y", "fetch github info for owner/repo", or "migrate old entries".

33 4
Explore
Jamie-BitFlight/claude_skills

design-anti-patterns

Enforce anti-AI UI design rules based on the Uncodixfy methodology. Use when generating HTML, CSS, React, Vue, Svelte, or any frontend UI code. Prevents "Codex UI" — the generic AI aesthetic of soft gradients, floating panels, oversized rounded corners, glassmorphism, hero sections in dashboards, and decorative copy. Applies constraints from Linear/Raycast/Stripe/GitHub design philosophy: functional, honest, human-designed interfaces. Triggers on: UI generation, dashboard building, frontend component creation, CSS styling, landing page design, or any task producing visual interface code.

33 4
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results