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
npx skills add alinaqi/maggy --skill python -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/python/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/python/
1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill python -a codex2Manually: put the files in place
.agents/skills/python/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill python -a cursor2Manually: put the files in place
.cursor/skills/python/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install alinaqi/maggy skills/python2Manually: put the files in place
.github/skills/python/SKILL.md1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill python -a gemini-cli2Platform CLI
gemini skills install https://github.com/alinaqi/maggy --path skills/pythonManually: put the files in place
.devin/skills/python/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill python -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.