Skip to main content
skill CX Codex

python · alinaqi — Claude Code skill: what it does, how to install

Guides the agent through Python development using ruff, strict mypy types, and pytest coverage thresholds.

MIT 282 installs ★ 713 updated 2026-10-13

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add alinaqi/maggy --skill python -a claude-code
Open on GitHub

What python does

This skill enforces strict Python conventions focused on type safety and test-driven development. It defines a layered directory layout that keeps domain logic in core/ and side effects like FastAPI or databases in infra/. Standard configurations for ruff, strict mypy, and pytest coverage are included out of the box.

The skill cannot be called directly via a slash command. Instead, the agent loads these instructions when touching *.py, pyproject.toml, or dependency manifests. It also supplies a ready-made GitHub Actions pipeline for Python 3.12 along with local pre-commit hooks.

Because the pytest configuration fails builds under 80% test coverage, incomplete test suites will stop the CI check immediately.

What it helps with

  • configure ruff, mypy, and pytest inside pyproject.toml
  • organize application code into separate core and infra layers
  • set up a GitHub Actions quality gate for Python 3.12
  • implement dependency injection and Result types in domain services

Example prompts for the agent

  • Set up pyproject.toml with ruff and strict mypy settings
  • Refactor the service to use dependency injection and Result types
  • Create unit tests with pytest for the order calculation logic

How to install python

1Skills CLI (Vercel)

npx skills add alinaqi/maggy --skill python -a claude-code

2Manually: put the files in place

~/.claude/skills/python/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/python/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about python

How to install python in Claude Code?

Run npx skills add alinaqi/maggy --skill python -a claude-code in your terminal. You can also place the skill file directly at ~/.claude/skills/python/SKILL.md.

What does the python skill do?

It sets strict Python code standards, mandating explicit type hints, TDD habits with pytest, and clean separation between business logic and infrastructure.

How does the python skill get triggered?

The skill has user invocation disabled, so it activates automatically whenever the assistant works on *.py, pyproject.toml, setup.py, or requirements*.txt files.

Source text

SKILL.md · MIT
---
name: python
description: Python development with ruff, mypy, pytest - TDD and type safety
when-to-use: When working on Python files
user-invocable: false
paths: ["**/*.py", "pyproject.toml", "setup.py", "requirements*.txt"]
effort: medium
---

# Python Skill


---

## Type Hints

- Use type hints on all function signatures
- Use `typing` module for complex types
- Run `mypy --strict` in CI

```python
def process_user(user_id: int, options: dict[str, Any] | None = None) -> User:
    ...
```

---

## Project Structure

```
project/
├── src/
│   └── package_name/
│       ├── __init__.py
│       ├── core/           # Pure business logic
│       │   ├── __init__.py
│       │   ├── models.py   # Pydantic models / dataclasses
│       │   └── services.py # Pure functions
│       ├── infra/          # Side effects
│       │   ├── __init__.py
│       │   ├── api.py      # FastAPI routes
│       │   └── db.py       # Database operations
│       └── utils/          # Shared utilities
├── tests/
│   ├── unit/
│   └── integration/
├── pyproject.toml
└── CLAUDE.md
```

---

## Tooling (Required)

```toml
# pyproject.toml
[tool.ruff]
line-length = 100
select = ["E", "F", "I", "N", "W", "UP"]

[tool.mypy]
strict = true

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under=80"
```

---

## Testing with Pytest

```python
# tests/unit/test_services.py
import pytest
from package_name.core.services import calculate_total

class TestCalculateTotal:
    def test_returns_sum_of_items(self):
        # Arrange
        items = [{"price": 10}, {"price": 20}]
        
        # Act
        result = calculate_total(items)
        
        # Assert
        assert result == 30

    def test_returns_zero_for_empty_list(self):
        assert calculate_total([]) == 0

    def test_raises_on_invalid_item(self):
        with pytest.raises(ValueError):
            calculate_total([{"invalid": "item"}])
```

---

## GitHub Actions

```yaml
name: Python Quality Gate

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          
      - name: Install dependencies
        run: |
          pip install -e ".[dev]"
          
      - name: Lint (Ruff)
        run: ruff check .
        
      - name: Format Check (Ruff)
        run: ruff format --check .
        
      - name: Type Check (mypy)
        run: mypy src/
        
      - name: Test with Coverage
        run: pytest
```

---

## Pre-Commit Hooks

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.13.0
    hooks:
      - id: mypy
        additional_dependencies: [pydantic]
        args: [--strict]

  - repo: local
    hooks:
      - id: pytest
        name: pytest
        entry: pytest tests/unit -x --tb=short
        language: system
        pass_filenames: false
        always_run: true
```

Install and setup:
```bash
pip install pre-commit
pre-commit install
```

---

## Patterns

### Pydantic for Data Validation
```python
from pydantic import BaseModel, Field

class CreateUserRequest(BaseModel):
    email: str = Field(..., min_length=5)
    name: str = Field(..., max_length=100)
```

### Dependency Injection
```python
# Don't import dependencies directly in business logic
# Pass them in

# Bad
from .db import database
def get_user(user_id: int) -> User:
    return database.fetch(user_id)

# Good
def get_user(user_id: int, db: Database) -> User:
    return db.fetch(user_id)
```

### Result Pattern (No Exceptions in Core)
```python
from dataclasses import dataclass

@dataclass
class Result[T]:
    value: T | None
    error: str | None
    
    @property
    def is_ok(self) -> bool:
        return self.error is None
```

---

## Python Anti-Patterns

- ❌ `from module import *`
- ❌ Mutable default arguments
- ❌ Bare `except:` clauses
- ❌ Using `type: ignore` without explanation
- ❌ Global variables for state
- ❌ Classes when functions suffice

© alinaqi · MIT · alinaqi/maggy

Similar skills

All skills for Programming languages →

python by other authors comes first.

python Mindrally This skill tells your coding agent how to write Python: PEP 8, type hints, early returns, async for I/O. Useful when the agent edits or generates code in a Python repo. CX Codex +1 1,100installs python pproenca Skill for Claude Code, Codex, Cursor and other agents with Python 3.11+ performance optimization rules. Triggers on asyncio, data structures, memory management, loops and strings. CX Codex +1 329installs python siviter-xyz Gives the agent one set of Python conventions: typing, dependency injection, module and test layout. Useful when edits land in an existing codebase. CX Codex +1 353installs python martinholovsky A backend skill for Python work: type hints, asyncio, input validation and pytest. The agent writes the failing test before the code. CX Codex +1 229installs python finom Turns Vovk.ts schemas into a typed Python package: RPC functions, TypedDict shapes, JSON Lines streaming. Useful when the API exists but the Python client does not. CX Codex +1 ★ 57repo stars gravitas-python udaysharmadev The gravitas-python skill adds Python-focused checks and test patterns to GRAVITAS. Use it when reviewing types, lint rules, pytest setup, or common failures. CX Codex +1 419installs python-pro qdhenry python-pro is a Claude Code subagent for Python refactoring, performance work, and complex features. It joins these coding tasks and includes tests with its changes. CX Codex ★ 1,357repo stars pare-python Dave-London pare-python — an MCP server for Claude Code and Codex that wraps ruff, mypy, pip, uv, black and pytest, returning typed JSON instead of raw terminal output. Agents read fields directly, with no string parsing. CX Codex +1 ★ 141repo stars writing-python julianobarbosa writing-python — a skill that keeps an agent on Python 3.14 idioms: standard library first, type hints on every function, uv and ruff in place of pip and black. CX Codex +1 134installs python-code-style Seth Hobson python-code-style — a skill for Python style rules, linting, formatting, naming, and documentation. Use it when writing code, reviewing changes, or setting project standards. CX Codex +1 16,456installs python-projects-guide-cursorrules-prompt-file PatrickJS python-projects-guide-cursorrules-prompt-file guides Cursor to write Python code following modular design, Rye dependency management, pytest suites, and Ruff formatting. CX Codex +1 ★ 41,178repo stars

From the same set61

The whole set →
code-graph code-graph — a skill that indexes your project as a symbol and dependency graph. Query the graph instead of reading files sequentially: get function signatures, call chains, and blast radius in milliseconds. CX Codex +1 285installs medusa This skill guides headless commerce work with Medusa, covering modules, API routes, workflows, and the admin UI. Use it when building a Medusa project. CX Codex +1 285installs gemini-review The gemini-review skill routes code reviews through Gemini CLI, covering branch changes, security issues, and large repositories. It also describes CI/CD use. CX Codex +1 283installs ticket-craft ticket-craft formats Jira, Linear, and Asana tickets so AI agents can execute them autonomously without clarification. CX Codex +1 283installs project-tooling project-tooling is a skill that validates and configures CLI tools for GitHub, Vercel, Supabase, and Render. Use it before starting projects with CI/CD and cloud services. CX Codex +1 277installs base base sets strict code limits and a mandatory TDD workflow with atomic task tracking for AI coding agents. CX Codex +1 276installs shopify-apps shopify-apps guides Shopify app work with Remix, the Admin GraphQL API, and checkout extensions. Use it when building an app or extension for a Shopify store. CX Codex +1 273installs azure-cosmosdb Skill for Azure Cosmos DB work: partition key selection, consistency levels, change feed, and SDK patterns with TypeScript examples. Adds CRUD templates, hierarchical keys, and cross-partition query patterns to your IDE. CX Codex +1 269installs

Project sponsors

Companies that keep this analytics open