writing-python — Claude Code skill: what it does, how to install
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.
MIT 134 installs ★ 17 updated 2026-10-14
npx skills add julianobarbosa/claude-code-skills --skill writing-python -a claude-codeWhat writing-python does
The skill sets house rules for new code on Python 3.14 and later. Reach for the standard library first, and pull in a package only when there is a reason. Every function and parameter gets an annotation. Errors are raised early, with a message that says what went wrong.
Inside are short snippets: annotations, a dataclass built with field(default_factory=...), event dispatch through match. A section on 3.14 covers deferred annotations, t-strings, except without parentheses, concurrent.interpreters and compression.zstd. Pointers to PATTERNS.md, CLI.md and TESTING.md follow, and two merged skills sit as reference in References/code-style.md and References/type-safety.md. The toolchain is named outright: uv in place of pip or poetry, ruff in place of flake8 or black, plus pytest and mypy. The agent may use Read, Bash, Grep and Glob.
The gotchas section says what breaks on an older codebase. On Python 3.9 dataclass(slots=True) does nothing quietly, int | None is evaluated at runtime only from 3.10, and importing annotations from __future__ turns every annotation into a string, so typing.get_type_hints fails on forward refs to classes in local scope.
What it helps with
- write a CLI tool on the standard library alone
- add type annotations to a module that has none
- move a project from pip and black to uv and ruff
- catch version traps: slots, union syntax, deferred annotations
- dispatch events with pattern matching instead of if-chains
Example prompts for the agent
- Write a Python 3.14 CLI that uses only the standard library, then run
ruffandmypyover it. - Convert this module to the
uvandrufftoolchain and drop the flake8 config. - Add a
dataclassconfig withslots=Trueand tell me what breaks on Python 3.9.
How to install writing-python
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill writing-python -a claude-code2Manually: put the files in place
~/.claude/skills/writing-python/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/writing-python/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill writing-python -a codex2Manually: put the files in place
.agents/skills/writing-python/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill writing-python -a cursor2Manually: put the files in place
.cursor/skills/writing-python/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install julianobarbosa/claude-code-skills skills/writing-python2Manually: put the files in place
.github/skills/writing-python/SKILL.md1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill writing-python -a gemini-cli2Platform CLI
gemini skills install https://github.com/julianobarbosa/claude-code-skills --path skills/writing-pythonManually: put the files in place
.devin/skills/writing-python/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill writing-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 writing-python
How do I install writing-python in Claude Code?
Run npx skills add julianobarbosa/claude-code-skills --skill writing-python -a claude-code. The skill lands at ~/.claude/skills/writing-python/SKILL.md.
What does writing-python do?
It gives the agent a set of rules for Python 3.14 code: the standard library comes first, annotations go on everything, errors surface early, and the toolchain is uv, ruff, pytest and mypy.
How does it relate to the python-infrastructure and uv skills?
This one covers code style, typing and the 3.14 feature set. Background jobs and retries live in python-infrastructure, while dependency handling and project scaffolding belong to uv.
Source text
SKILL.md · MIT
---
name: writing-python
description: Idiomatic Python 3.14+ development. Use when writing Python code, CLI tools, scripts, or services. Emphasizes stdlib, type hints, uv/ruff toolchain, and minimal dependencies.
allowed-tools: Read, Bash, Grep, Glob
---
# Python Development (3.14+)
## Core Principles
- **Stdlib first**: External deps only when justified
- **Type hints everywhere**: All functions, all parameters
- **Explicit over implicit**: Clear is better than clever
- **Fail fast**: Raise early with informative errors
## Toolchain
```bash
uv # Package management (not pip/poetry)
ruff # Lint + format (not flake8/black)
pytest # Testing
mypy # Type checking
```
## Quick Patterns
### Type Hints
```python
def process_users(users: list[User], limit: int | None = None) -> list[Result]:
...
async def fetch_data(url: str, timeout: float = 30.0) -> dict[str, Any]:
...
```
### Dataclasses
```python
from dataclasses import dataclass, field
@dataclass
class Config:
host: str
port: int = 8080
tags: list[str] = field(default_factory=list)
```
### Pattern Matching
```python
match event:
case {"type": "click", "x": x, "y": y}:
handle_click(x, y)
case {"type": "key", "code": code}:
handle_key(code)
case _:
raise ValueError(f"Unknown event: {event}")
```
## Python 3.14 Features
- **Deferred annotations**: No more `from __future__ import annotations`
- **Template strings (t"")**: `t"Hello {name}"` returns Template object
- **except without parens**: `except ValueError, TypeError:`
- **concurrent.interpreters**: True parallelism via subinterpreters
- **compression.zstd**: Zstandard in stdlib
- **Free-threaded build**: No GIL (opt-in)
## References
- [PATTERNS.md](PATTERNS.md) - Code patterns and style
- [CLI.md](CLI.md) - CLI application patterns
- [TESTING.md](TESTING.md) - Testing with pytest
## Tooling
```bash
uv sync # Install deps
ruff check --fix . # Lint and autofix
ruff format . # Format
pytest -v # Test
mypy . # Type check
```
---
## Absorbed sub-skills (post-consolidation)
This skill now subsumes the former `python-code-style` and `python-type-safety` skills. Their original SKILL.md content is preserved as deep reference:
| Subject | Path |
|---------|------|
| ruff, mypy, naming, imports, docstrings (Google style) | `References/code-style.md` |
| Type annotations, generics, protocols, strict checking patterns | `References/type-safety.md` |
For system-reliability concerns (background jobs, retries, observability), see the sibling **`python-infrastructure`** skill. For dependency management and project scaffolding, see **`uv`**.
---
## Gotchas
- **`from __future__ import annotations` makes ALL annotations strings** — runtime introspection (`typing.get_type_hints`) needs the actual types available; forward refs to local-scope classes fail.
- **f-string debug syntax (`f"{var=}"`) is 3.8+** — quietly fails (treats `=` as literal) in 3.7 and earlier.
- **`dataclass(slots=True)` is 3.10+** — silently does nothing in 3.9. Use `__slots__` manually for portability.
- **PEP 604 union syntax (`int | None`) is 3.10+ at runtime** — works as a string annotation in 3.9 with `from __future__ import annotations`, fails at runtime introspection.
- **`async def` vs `def` for FastAPI dependencies**: async deps run in the event loop; sync deps run in a thread pool. Mixing without thought causes either blocking or extra context-switch overhead.
© julianobarbosa · MIT · julianobarbosa/claude-code-skills