gravitas-python — Claude Code skill: what it does, how to install
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.
MIT 419 installs ★ 509 updated 2026-10-24
npx skills add udaysharmadev/Gravitas --skill gravitas-python -a claude-codeWhat gravitas-python does
gravitas-python extends the base GRAVITAS workflow for Python repositories. It inspects settings in pyproject.toml, legacy setup.py or setup.cfg, dependency files, conftest.py, package markers, and installed type stubs. Load skills/gravitas/SKILL.md first; without it, this extension cannot provide the base workflow.
Its verification chain covers mypy . --strict, ruff check ., ruff format --check ., and pytest -v --tb=short. The skill also explains frequent type errors, circular imports, missing stubs, builtin shadowing, and bare exception handling. It includes fixture, parametrization, FastAPI, and Django testing patterns.
What it helps with
- check strict Python typing
- catch lint and formatting issues
- run a repeatable pytest verification chain
- trace circular imports or missing type stubs
- design tests for FastAPI or Django code
Example prompts for the agent
- Run the Python project through
mypy,ruff, andpytestchecks. - Read
pyproject.tomland explain the active typing and lint configuration. - Diagnose
Optional[X] has no attribute Yand suggest a code fix.
How to install gravitas-python
1Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-python -a claude-code2Manually: put the files in place
~/.claude/skills/gravitas-python/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gravitas-python/
1Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-python -a codex2Manually: put the files in place
.agents/skills/gravitas-python/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-python -a cursor2Manually: put the files in place
.cursor/skills/gravitas-python/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install udaysharmadev/Gravitas skills/gravitas-python2Manually: put the files in place
.github/skills/gravitas-python/SKILL.md1Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-python -a gemini-cli2Platform CLI
gemini skills install https://github.com/udaysharmadev/Gravitas --path skills/gravitas-pythonManually: put the files in place
.devin/skills/gravitas-python/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-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 gravitas-python
How do I install gravitas-python in Claude Code?
Run npx skills add udaysharmadev/Gravitas --skill gravitas-python -a claude-code, then check ~/.claude/skills/gravitas-python/SKILL.md.
What does gravitas-python do?
It adds Python guidance to GRAVITAS for type checking with mypy or pyright, linting with ruff or flake8, pytest patterns, and recurring Python failures.
Does it require the base GRAVITAS skill?
Yes. Load skills/gravitas/SKILL.md before gravitas-python, since this package extends the base skill.
Source text
SKILL.md · MIT
---
name: gravitas-python
description: >
GRAVITAS extension for Python projects. Adds Python-specific recon,
type checking with mypy/pyright, ruff/flake8 lint, pytest patterns,
and common Python failure modes.
Load in addition to the base GRAVITAS skill.
triggers:
- "python"
- "py"
- "django"
- "fastapi"
- "flask"
- "pytest"
- "mypy"
---
# GRAVITAS — Python Extension
Extends the base GRAVITAS skill with Python-specific patterns.
Load `skills/gravitas/SKILL.md` first, then this file.
---
## Python Recon Additions
```
□ pyproject.toml — [tool.mypy], [tool.ruff], [tool.pytest.ini_options]
□ setup.py / setup.cfg — legacy config
□ requirements.txt / requirements-dev.txt — dependency versions
□ conftest.py — pytest fixtures (critical for understanding test patterns)
□ __init__.py — package structure
□ Type stubs — are there py.typed markers? stub packages installed?
```
### Read pyproject.toml for type strictness
```bash
cat pyproject.toml | grep -A 10 "\[tool.mypy\]"
cat pyproject.toml | grep -A 10 "\[tool.ruff\]"
```
---
## Python Verification Chain
```bash
# Full chain — in this order
mypy . --strict # type correctness
ruff check . # lint (fast, Rust-based)
ruff format --check . # format check
pytest -v --tb=short # all tests
# With coverage
pytest --cov=src --cov-report=term-missing -v
# Type coverage
mypy . --strict 2>&1 | tail -5 # summary line shows error count
```
---
## Python-Specific Anti-Patterns
### Never use bare `except`
```python
BAD: except:
GOOD: except ValueError as e:
GOOD: except (TypeError, ValueError) as e:
```
### Never shadow builtins
```python
BAD: list = [1, 2, 3] # shadows list()
BAD: id = user.id # shadows id()
GOOD: items = [1, 2, 3]
GOOD: user_id = user.id
```
### Type annotations required (with mypy strict)
```python
BAD: def process(data):
GOOD: def process(data: dict[str, Any]) -> ProcessResult:
```
### Use dataclasses or Pydantic over dicts for structured data
```python
BAD: return {"user_id": 1, "name": "Alice"} # no type safety
GOOD: return UserResponse(user_id=1, name="Alice")
```
---
## Common Python Failure Modes
| Failure | Root Cause | Fix |
|---------|-----------|-----|
| `Optional[X] has no attribute Y` | None not handled | Add `if x is not None:` guard |
| `Incompatible return value type` | Wrong return type | Check function signature |
| `Missing return statement` | Not all paths return | Add explicit return |
| `Module has no attribute X` | Wrong import | Check module with `dir(module)` |
| `Cannot find implementation for X` | Missing stub | Install `types-X` package |
| Circular import | Import at module level | Move to function level or restructure |
---
## Test Patterns (pytest)
### Fixture pattern
```python
# conftest.py
import pytest
from myapp.db import get_db
@pytest.fixture
def db():
conn = get_db(":memory:")
yield conn
conn.close()
@pytest.fixture
def client(db):
from myapp import create_app
app = create_app({"TESTING": True})
with app.test_client() as c:
yield c
```
### Standard test structure
```python
class TestUserAuth:
def test_login_success(self, client, db):
# Arrange
db.execute("INSERT INTO users VALUES (1, 'alice', 'hash')")
# Act
response = client.post("/login", json={"username": "alice", "password": "pw"})
# Assert
assert response.status_code == 200
assert response.json["token"] is not None
def test_login_wrong_password(self, client, db):
response = client.post("/login", json={"username": "alice", "password": "wrong"})
assert response.status_code == 401
```
### Parametrize for edge cases
```python
@pytest.mark.parametrize("input,expected", [
("", ValueError),
(None, TypeError),
("[email protected]", None),
("not-an-email", ValueError),
])
def test_validate_email(input, expected):
if expected:
with pytest.raises(expected):
validate_email(input)
else:
validate_email(input) # should not raise
```
---
## Framework-Specific Notes
### FastAPI
```python
# Always test with TestClient, not raw function calls
from fastapi.testclient import TestClient
client = TestClient(app)
# Type all path/query params and bodies
@router.post("/users", response_model=UserResponse)
async def create_user(body: CreateUserRequest) -> UserResponse:
...
```
### Django
```python
# Use pytest-django
# settings for tests
@pytest.mark.django_db
def test_user_creation():
user = User.objects.create_user(username="test", password="pass")
assert user.id is not None
```
---
## Quick Reference
```bash
# Run single test file
pytest src/auth/test_session.py -v
# Run single test
pytest src/auth/test_session.py::TestSession::test_timeout -v
# Run with pdb on failure
pytest --pdb
# Show slowest tests
pytest --durations=10
# Type check single file
mypy src/auth/session.py --strict
```
© udaysharmadev · MIT · udaysharmadev/Gravitas