mcp server

claude-code-python-setup

Ready-to-use .claude configuration for Python projects: agents, skills, commands, rules, and MCP server templates for Claude Code.

skateddu/claude-code-python-setupcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 25, 2026

Claude Code Python Setup

A ready-to-use .claude configuration for Python development projects with Claude Code. Includes curated agents, commands, skills, and MCP server templates.

Prerequisites

Claude Code

Claude Code requires a Pro, Max, Teams, Enterprise, or Console account (the free Claude.ai plan does not include Claude Code access).

System requirements:

macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+ / Debian 10+
4 GB+ RAM
Internet connection
On Windows: Git for Windows is required

Installation:

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

# Windows (alternative: WinGet)
winget install Anthropic.ClaudeCode

After installation, navigate to your project directory and run claude to start. On first run, follow the browser prompts to authenticate.

Verify with:

claude --version
claude doctor     # detailed check

Full documentation: code.claude.com/docs/en/setup

Optional Dependencies

Some components require additional tools. Install only what you need:

Dependency	Required by	Install
Node.js 18+	context7, playwright MCP servers	nodejs.org
Python >= 3.10 + uv	postgres, docker MCP servers	docs.astral.sh/uv
Docker	docker MCP server	docker.com
PostgreSQL	postgres MCP server	Running instance (local or remote)
jq	all six hooks — each one parses its payload and builds its response with it	jqlang.github.io/jq
bubblewrap + socat	Bash sandbox on Linux/WSL2 only (macOS needs nothing; native Windows unsupported)	your package manager
RTK	token optimization (recommended)	install guide

npx comes with Node.js. uvx comes with uv. No additional installs needed beyond the base tools.

Token savings tip: RTK (Rust Token Killer) (v0.43.0+) is a CLI proxy that reduces token consumption by 60-90% on common dev commands (git, tests, build, lint). Run rtk init -g to install a hook that automatically optimizes all shell commands in Claude Code sessions, then rtk gain to see per-command and session token savings.

Project Structure

claude-code-python-setup/
├── .claude/
│   ├── agents/              # Specialized subagents
│   │   ├── architect.md
│   │   ├── code-architect.md
│   │   ├── code-explorer.md
│   │   ├── code-reviewer.md
│   │   ├── comment-analyzer.md
│   │   ├── database-reviewer.md
│   │   ├── planner.md
│   │   ├── pr-test-analyzer.md
│   │   ├── refactor-cleaner.md
│   │   ├── security-reviewer.md
│   │   ├── silent-failure-hunter.md
│   │   ├── tdd-guide.md
│   │   └── type-design-analyzer.md
│   ├── commands/            # Slash commands (/command-name)
│   │   ├── build-fix.md
│   │   ├── clean-gone.md
│   │   ├── commit.md
│   │   ├── commit-push-pr.md
│   │   ├── feature-dev.md
│   │   ├── notebook-review.md
│   │   ├── orchestrate.md
│   │   ├── review-pr.md
│   │   ├── revise-claude-md.md
│   │   └── test-coverage.md
│   ├── hooks/                # Deterministic guardrails
│   │   ├── lib/
│   │   │   └── command-text.sh  # Strips heredoc bodies before pattern matching
│   │   ├── session-start.sh  # Check uv env (.venv, lockfile) at session start
│   │   ├── guard-secrets.sh  # Block prompts containing hardcoded secrets
│   │   ├── enforce-uv.sh     # Rewrite bare python/pytest to uv run, block pip
│   │   ├── protect-main.sh   # Block force push, direct push to main, broad rm -rf
│   │   ├── auto-lint.sh      # Auto-format Python files with ruff after edits
│   │   └── verify.sh         # Run ruff + pytest on Stop; block until green
│   ├── rules/                # Modular coding standards
│   │   ├── api-patterns.md   # FastAPI/Pydantic (path-scoped)
│   │   ├── architecture.md
│   │   ├── compaction.md
│   │   ├── documentation.md
│   │   ├── exception-handling.md
│   │   ├── git-workflow.md
│   │   ├── project-structure.md
│   │   ├── python-idioms.md
│   │   ├── security.md
│   │   └── testing.md
│   ├── settings.json          # Project-level hooks, permissions, status line
│   ├── statusline.py          # Status line script (Python, cross-platform)
│   └── skills/                # Reference docs and scripts
│       ├── api-design/
│       ├── claude-api/
│       ├── claude-automation-recommender/
│       ├── claude-md-improver/
│       ├── database-migrations/
│       ├── deployment-patterns/
│       ├── django-patterns/
│       ├── django-security/
│       ├── django-tdd/
│       ├── django-verification/
│       ├── doc-coauthoring/
│       ├── docker-patterns/
│       ├── docx/
│       ├── frontend-design/
│       ├── mcp-builder/
│       ├── pdf/
│       ├── playground/
│       ├── postgres-patterns/
│       ├── pptx/
│       ├── skill-creator/
│       ├── webapp-testing/
│       └── xlsx/
├── .github/
│   ├── ISSUE_TEMPLATE/      # Bug report and feature request forms
│   ├── dependabot.yml       # Weekly grouped bumps for Actions and uv deps
│   ├── pull_request_template.md
│   └── workflows/
│       └── ci.yml           # Lint, shellcheck, hook tests on every PR
├── mcp_config/
│   ├── linux_mac.mcp.json   # MCP server config (Linux/Mac)
│   └── windows.mcp.json     # MCP server config (Windows)
├── tests/
│   ├── conftest.py          # Fixtures that run a hook against a payload
│   ├── hook_harness.py      # HookResult and payload builders
│   └── unit/                # One file per hook, asserting its decisions
├── .env.example             # Environment variables template
├── .gitattributes           # Force *.sh to LF so hooks run on Windows
├── .gitignore
├── .python-version          # Python version pin for uv
├── CHANGELOG.md             # Version history (Keep a Changelog format)
├── CLAUDE.md                # Project instructions (< 200 lines, imports rules)
├── CODE_OF_CONDUCT.md       # Contributor Covenant 2.1
├── CONTRIBUTING.md          # How to contribute, setup, PR workflow
├── LICENSE                  # MIT License
├── pyproject.toml           # Project metadata, ruff and pytest config
├── README.md
└── SECURITY.md              # Vulnerability reporting policy

Setup

1. Copy the `.claude` folder

Copy the .claude/ directory and CLAUDE.md into the root of your project.

Then open CLAUDE.md and replace the <YOUR_OPERATING_SYSTEM> placeholder with your actual OS (e.g., Windows 11, macOS 15, Ubuntu 24.04).

2. Configure MCP servers

Copy the appropriate MCP template to .mcp.json in your project root:

# Windows
cp mcp_config/windows.mcp.json .mcp.json

# Linux / Mac
cp mcp_config/linux_mac.mcp.json .mcp.json

.mcp.json is gitignored so each developer can use the template matching their OS.

3. Set environment variables (optional)

Some components use environment variables for configuration. These must be system environment variables (Claude Code does not read .env files). See .env.example for all available variables and defaults.

# Linux / Mac — add to ~/.bashrc or ~/.zshrc
export POSTGRES_USER=myuser
export POSTGRES_PASSWORD=mypassword
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=mydb
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=85

# Windows — via setx or System Properties > Environment Variables
setx POSTGRES_USER myuser
setx POSTGRES_PASSWORD mypassword
setx POSTGRES_HOST localhost
setx POSTGRES_PORT 5432
setx POSTGRES_DB mydb
setx CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 85

Variable	Used by	Default	Description
`POSTGRES_*`	postgres MCP server	see `.env.example`	Database connection parameters
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	Claude Code	`95`	Context % threshold that triggers auto-compaction (lower = compacts earlier, reduces response time)
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`	Claude Code	`0` (disabled)	Set to `1` to enable Agent Teams: spawning a teammate via the Agent tool's `name` parameter implicitly forms a team for the session (no `TeamCreate`/`TeamDelete` setup needed) (docs)
`CLAUDE_CODE_NO_FLICKER`	Claude Code	`1` (enabled)	Fullscreen rendering (flicker-free display, flat memory usage, mouse support) is the default; set to `0` for the classic renderer, or use `"tui": "fullscreen"` in `settings.json` (docs)
`CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`	Claude Code	`0` (enabled)	Set to `1` to hide the skills and workflows bundled with Claude Code itself (e.g. `/init`, `/security-review`); plugin skills and this project's own `.claude/skills/` are unaffected. Equivalent to `"disableBundledSkills": true` in `settings.json` (docs)
`BASH_DEFAULT_TIMEOUT_MS`	Claude Code	`120000` (2 min)	Default timeout for Bash commands. Raise it if your test suite regularly runs longer than two minutes, otherwise `uv run pytest` gets killed mid-run
`BASH_MAX_OUTPUT_LENGTH`	Claude Code	`30000` (max `150000`)	Characters of command output Claude reads back. Raise it when verbose `pytest -v` output gets truncated before the failure summary
`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`	Claude Code	`3`	How many layers of subagents can nest below the main conversation. Set `1` to turn nesting off (docs)
`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`	Claude Code	`20`	How many subagents may run at once before `Agent` spawns start failing. Requires Claude Code v2.1.217+ (docs)
`CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`	Claude Code	`200`	WebSearch calls allowed per session, counted across the main conversation and every subagent, so parallel research fan-outs draw on the same budget. Accepts a positive whole number — the cap can be raised but not turned off; `/clear` resets the count. Requires v2.1.212+ (docs)
`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`	Claude Code	`120000` (2 min)	How long a main-conversation MCP tool call may run before it moves to a background task instead of blocking the session. Set `0` to disable auto-backgrounding. Calls from subagents are never backgrounded. Requires v2.1.212+ (docs)
`CLAUDE_CODE_DISABLE_WEB_FETCH`	Claude Code	unset (enabled)	Set to `1` to turn off the WebFetch tool, for example where Claude must not reach arbitrary URLs. Requires v2.1.285+

4. Verify MCP servers

Run /mcp inside Claude Code to check that all servers are connected.

5. Install development tooling (optional)

The pyproject.toml declares PEP 735 dependency groups for the tools this setup relies on:

# Core tooling (ruff, pytest, pytest-cov) — used by the auto-lint hook,
# the enforce-uv hook, and the verification flow. Installed by default:
uv sync

# Agent tooling (mypy, bandit, pip-audit, safety, vulture, autoflake) —
# only needed by on-demand agents (security-reviewer, refactor-cleaner,
# code-reviewer). Opt in when required:
uv sync --group agents

Components

CLAUDE.md (project root)

CLAUDE.md is the project instructions file that Claude Code reads automatically at the start of every conversation. It defines the coding standards, conventions, and constraints that Claude must follow when working on your project.

Think of it as a persistent system prompt scoped to your codebase. It's always loaded — no manual invocation needed.

Key characteristics:

Auto-loaded: Claude reads it at startup, before any user message
Imports via @path: use @.claude/rules/testing.md to pull in modular rules without bloating the main file
Keep under 200 lines: long files waste context; extract details into rules
Project-scoped: place in the project root for repo-wide instructions; nest in subdirectories for folder-specific overrides

This setup's CLAUDE.md contains project specs (OS, language, tools), naming conventions, file organization, common commands, and @import references to all rules.

In a project with no CLAUDE.md, Claude Code reads AGENTS.md instead (configurable under "Project instructions" in /config). This template ships CLAUDE.md, so AGENTS.md is ignored unless you remove it.

Run /doctor prompt-audit (also /checkup prompt-audit) after customizing the template, and again after a model upgrade: it audits your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models. Requires Claude Code v2.1.283+.

Full documentation: code.claude.com/docs/en/memory

Rules (`.claude/rules/`)

Rules are modular coding standards that extend CLAUDE.md without inflating it. Each rule is a standalone Markdown file focused on a single topic (testing, security, API patterns, etc.), imported into CLAUDE.md via @.claude/rules/<file>.md.

Rules are loaded into Claude's context at session start alongside CLAUDE.md, so they act as persistent instructions — not invoked on demand like skills or agents.

Key characteristics:

Always in context: rules are loaded at startup and apply to every interaction
Path-scoped (optional): add paths in YAML frontmatter to activate a rule only for matching file patterns (e.g., api-patterns.md only for src/api/**/*.py)
One topic per file: keeps each rule focused and easy to update independently
Referenced by agents: agents point to rules instead of duplicating standards (e.g., "see .claude/rules/security.md")

Full documentation: code.claude.com/docs/en/memory

Rule	Scope	Description
api-patterns	`src/api/*/.py`	FastAPI routers, Pydantic models, dependency injection
architecture	global	Layered architecture, modularity, dependency flow
compaction	global	What to preserve during context compaction
documentation	global	README, docstrings, type annotations, changelog
exception-handling	global	Custom exception hierarchy, catch-at-boundary pattern
git-workflow	global	Conventional Commits, branch naming, PR conventions
project-structure	global	src layout, module conventions, pydantic-settings config
python-idioms	global	Data structure selection, generators, match/case, explicit kwargs, unpacking
security	global	Secrets management, input validation, injection prevention
testing	global	pytest structure, coverage targets, fixtures, markers

Hooks (`.claude/hooks/`)

Hooks are deterministic guardrails that run automatically before or after Claude uses a tool. Unlike rules (which are advisory — Claude should follow them), hooks are enforced by the system — Claude cannot bypass them.

Each hook is a shell script triggered by a specific event. PreToolUse hooks can block an action before it happens; PostToolUse hooks run after a tool completes (e.g., to auto-format code). Hook configuration lives in .claude/settings.json.

Key characteristics:

Deterministic: hooks always execute — they don't depend on Claude's interpretation
Blocking: PreToolUse hooks return a hookSpecificOutput object whose permissionDecision is one of deny (block), allow (auto-approve), ask (escalate to the user), or defer (fall back to the normal permission flow); they can also rewrite the tool call via updatedInput. Example: {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"..."}}
Composable: multiple hooks can run on the same event (e.g., enforce-uv + protect-main both run on Bash)
Conditional: an if field (permission-rule syntax, e.g. Bash(git *)) scopes a hook to matching commands so it doesn't spawn a process on every tool call — enforce-uv and protect-main use this to skip non-Python/non-git commands
Dependency: requires jq for JSON parsing of hook input
Code vs. text: a hook receives the whole command string, which mixes code with data. The two PreToolUse hooks strip heredoc bodies (via hooks/lib/command-text.sh) before matching, so a gh pr create whose description quotes pip install or rm -rf / isn't mistaken for running them

This setup hooks into SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop, all with command handlers. Claude Code exposes more than thirty events, and four other handler types: http (POST to an endpoint), mcp_tool (call a tool on a configured MCP server), prompt (a single-turn model evaluation) and agent (a subagent that can use tools, experimental). Among the events most useful to extend this setup:

PostToolBatch — after a whole batch of parallel tool calls resolves (run linting once per batch instead of once per file)
PostToolUseFailure — after a tool call fails, for reacting to errors rather than successes
SubagentStart / SubagentStop — around each subagent's lifecycle
InstructionsLoaded — when a CLAUDE.md or .claude/rules/*.md file is loaded into context
PermissionRequest / PermissionDenied — when a call needs a permission decision, or auto mode denies it
PreModelSwitch / PostModelSwitch — block, confirm or annotate a model switch, for example to warn before moving a long session to a model whose cache is cold
SessionEnd, PreCompact / PostCompact, Notification, ConfigChange, FileChanged

See the docs for the full list.

Full documentation: code.claude.com/docs/en/hooks

Hook	Event	Description
session-start	`SessionStart`	Checks the uv environment (`.venv`, `uv.lock` freshness) and injects the status into the session context
guard-secrets	`UserPromptSubmit`	Blocks a prompt that looks like it contains a hardcoded secret (API keys, tokens, private keys)
enforce-uv	`PreToolUse` (Bash)	Auto-rewrites simple bare `python`/`pytest`/`ruff`/`mypy`/`bandit` calls to `uv run`; blocks `pip` and ambiguous cases with `uv add`/`uv sync` guidance
protect-main	`PreToolUse` (Bash)	Blocks `git push --force`, direct push to main/master, `git reset --hard`, broad `rm -rf`
auto-lint	`PostToolUse` (Edit\|Write)	Runs `ruff check --fix` and `ruff format` on Python files after every edit
verify	`Stop`	Runs `ruff check` + `pytest` when Claude finishes; on failure, blocks the stop and feeds the errors back so Claude keeps fixing

Permissions (`.claude/settings.json`)

Pre-configured permission rules in .claude/settings.json control what Claude can and cannot access.

Allowed commands — auto-approved without prompting:

Pattern	Description
`uv sync `, `uv add `, `uv remove *`	Dependency management
`uv run pytest `, `uv run ruff `, `uv run python *`	Test, lint, and run

Denied reads — Claude is blocked from reading sensitive files:

Pattern	Files protected
`.env`, `.env.{local,development,staging,production,test}`, `.envrc`	Environment variables (`.env.example` is allowed)
`secrets/**`	Secrets directory
`*/credentials`, `*/secret`	Credential and secret files
`*/.pem`, `*/.key`, `*/.p12`, `*/.pfx`, `*/.jks`	Certificates and private keys
`*/token*`	Token files
`~/.ssh/`, `/id_rsa`, `/id_ed25519`, `*/id_ecdsa`, `*/id_dsa`	SSH keys

These rules are enforced at the system level — Claude cannot bypass them regardless of the prompt. Customize by editing the permissions object in .claude/settings.json.

Full documentation: code.claude.com/docs/en/settings#excluding-sensitive-files

Fallback model — .claude/settings.json also sets fallbackModel, a chain of up to three models (e.g. ["claude-sonnet-5-5", "claude-haiku-5-5"]) that Claude Code switches to when the primary model is overloaded or unavailable, keeping the session going. Edit or remove the array to match your plan's model access.

Default permission mode — permissions.defaultMode is set explicitly to "default" (prompt on first use of each tool) so the behavior is visible and easy to change, rather than relying on the implicit default. Other values: "plan" (read-only, no modifications), "acceptEdits" (auto-accepts file edits), "bypassPermissions" (skips all prompts — isolated environments only), "dontAsk" (auto-denies unless pre-approved), "auto" (auto-approves with background safety checks).

The label and the value differ: in the Shift+Tab cycle this mode appears as "Manual", not "default" — in the CLI, the VS Code and JetBrains extensions, and the desktop app. "default" is the canonical value in settings.json; "manual" is accepted as an alias on Claude Code v2.1.200+.

Three related settings are intentionally not set here, since they have no neutral value that preserves default behavior while being explicit — adding them would itself be a behavior change:

permissions.disableAutoMode: "disable" — permanently removes auto from the Shift+Tab mode cycle; there's no value that means "keep auto mode available" other than omitting the key.
language: "italian" (or any language name) — pins Claude's response language, voice dictation, and terminal tab title generation to that language; omitting it lets Claude follow the conversation's language.
attribution — hides or changes the Co-authored-by trailer Claude Code adds to commits and the attribution line in pull request descriptions. "attribution": false hides both, but Claude Code versions older than the one that introduced it skip a settings file containing it entirely — hooks and permissions included. In a file shared across a team, use the object form instead: "attribution": {"commit": false, "pr": false}. Omitting the key keeps the standard attribution. Replaces the deprecated includeCoAuthoredBy.

Full documentation: code.claude.com/docs/en/settings

Bash Sandbox (opt-in, not enabled here)

The permission rules above govern Claude's tools. The Bash sandbox is a different layer: it constrains what a shell command can touch once it runs, enforced by the operating system for the command and every child process it spawns. A deny rule stops the Read tool from opening ~/.ssh/id_rsa; the sandbox stops a shell command from reading it.

In exchange for defining the boundary up front, Claude stops asking permission for each command — in auto-allow mode, anything that fits inside the sandbox just runs.

This template does not enable it, deliberately. The sandbox runs on macOS, Linux, and WSL2, but not on native Windows, and this setup is meant to work unchanged on all three. Enabling it in a checked-in .claude/settings.json would degrade to a startup warning for every Windows contributor. Turn it on per-machine instead: run /sandbox to see the panel, install status, and mode.

On macOS nothing needs installing (it uses Seatbelt). On Linux and WSL2 it needs bubblewrap (filesystem isolation) and socat (network relay).

A starting point for a uv-based Python project — add to your user settings (~/.claude/settings.json) so it follows you across projects without affecting Windows contributors:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": [
        "pypi.org",
        "files.pythonhosted.org",
        "github.com",
        "*.githubusercontent.com"
      ]
    },
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "POSTGRES_PASSWORD", "mode": "deny" }
      ]
    }
  }
}

The allowedDomains list covers uv sync, uv add, and git against GitHub. Any other host prompts once on first use, so the list only needs the traffic you don't want to be asked about. Sandboxed commands can write to the working directory and the session temp directory; widen that with sandbox.filesystem.allowWrite if a tool needs more.

Two things worth knowing before relying on it:

There is no built-in credential deny list. Only the paths and variables you list under credentials are protected — the default read policy still allows ~/.aws and ~/.ssh. The block above is a starting point, not a complete one.
Sandbox failures can be retried outside the sandbox. When a command fails on a sandbox restriction, Claude may retry it with dangerouslyDisableSandbox, which then goes through the normal permission flow. Set "allowUnsandboxedCommands": false to remove that escape hatch entirely.

Full documentation: code.claude.com/docs/en/sandboxing

Agents (`.claude/agents/`)

Agents are specialized AI subagents that run in their own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches an agent's description, it automatically delegates to that agent, which works independently and returns results.

Each agent is a Markdown file with YAML frontmatter (configuration) and a body (system prompt). Agents help preserve the main conversation context by isolating heavy tasks, and can enforce constraints like read-only access or specific tool sets.

Key characteristics:

Automatic delegation: Claude uses the agent's description to decide when to delegate
Isolated context: each agent runs in its own context window, keeping verbose output out of the main conversation
Configurable tools and model: agents can restrict tool access and use a different model (e.g., Haiku for speed)
Nesting: subagents can spawn their own subagents, up to 3 layers below the main conversation by default; at the limit Claude Code withholds the Agent tool so the subagent does the work itself. Change the limit with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH
Background by default: subagents run in the background while you keep working, and notify on completion or when they need input

Full documentation: code.claude.com/docs/en/sub-agents

Agent	Description	Source
architect	System design, ADRs, trade-off analysis, scalability planning	ECC (adapted)
code-architect	Implementation blueprints: file plans, data flow, build sequence	claude-plugins-official
code-explorer	Codebase tracing: execution paths, architecture mapping, dependency analysis	claude-plugins-official
code-reviewer	Code quality, Python patterns, concurrency, FastAPI/Django/Flask checks	ECC (adapted)
comment-analyzer	Code comment accuracy, completeness, and comment rot detection	claude-plugins-official
database-reviewer	PostgreSQL schema, query optimization, and migration review	ECC
planner	Task decomposition and implementation planning	ECC
pr-test-analyzer	Test coverage quality: behavioral gaps, critical paths, edge cases	claude-plugins-official
refactor-cleaner	Dead code detection, refactoring (vulture, ruff)	ECC (adapted)
security-reviewer	Security audit (bandit, safety, pip-audit, OWASP Top 10)	ECC (adapted)
silent-failure-hunter	Error handling audit: silent failures, catch blocks, fallback behavior	claude-plugins-official
tdd-guide	Test-driven development with pytest	ECC (adapted)
type-design-analyzer	Type design quality: encapsulation, invariants, enforcement ratings	claude-plugins-official

Skills (`.claude/skills/`)

Skills extend what Claude can do. Each skill is a directory containing a SKILL.md file (with optional supporting files like templates, examples, or scripts). Claude loads skills automatically when relevant to the conversation, or you can invoke them directly with /skill-name.

Skills serve two purposes:

Reference content: conventions, patterns, domain knowledge that Claude applies to your work (loaded inline)
Task content: step-by-step workflows for specific actions like deployments or code generation

Key characteristics:

Auto-discovery: Claude reads skill descriptions and loads them when relevant
Invocation control: disable-model-invocation: true makes a skill user-only; user-invocable: false makes it Claude-only
Arguments: skills accept $ARGUMENTS from the user (e.g., /fix-issue 123)
Subagent execution: skills with context: fork run in an isolated subagent
Supporting files: a skill directory can include templates, examples, and scripts alongside SKILL.md

Full documentation: code.claude.com/docs/en/skills

None of the skills below were written for this template: each one is vendored from anthropics/skills, anthropics/claude-plugins-official or ECC, as the Source column shows — see Credits. They are copies, so they don't update themselves — re-sync them from upstream periodically, especially claude-api, which pins the model IDs Claude will reach for.

Upstream's other skills (academy-guide, discernment-nudge, algorithmic-art, canvas-design, brand-guidelines, internal-comms, slack-gif-creator, theme-factory, web-artifacts-builder) are deliberately not vendored: they fall outside Python development, and every installed skill's description costs context in every session.

Every skill here is loaded whether a project uses it or not. Run /skill-doctor after a few sessions to see which skills go unused and what each costs in context, then delete the directories your project doesn't need — the Django and Office-document skills are the usual candidates in a FastAPI project.

Skill	Description	Source
api-design	REST API design: resource naming, status codes, pagination, versioning	ECC
claude-api	Claude API and Anthropic SDK reference: model IDs and pricing, streaming, tool use, prompt caching, token counting, Managed Agents, model migration, cost optimization, evals, Python SDK 0.x → 1.x upgrade	anthropics/skills
claude-automation-recommender	Analyze codebases and recommend Claude Code automations (hooks, skills, MCP servers)	claude-plugins-official
claude-md-improver	Audit and improve CLAUDE.md files: quality scoring, targeted updates	claude-plugins-official (adapted)
database-migrations	Safe zero-downtime migrations, reversible patterns (SQLAlchemy, Django, golang-migrate)	ECC
deployment-patterns	CI/CD pipelines, rolling/blue-green deployments, health checks, production readiness	ECC (adapted)
django-patterns	Django architecture, DRF, ORM best practices, caching, signals, middleware	ECC
django-security	Django security: authentication, CSRF/XSS prevention, secure configuration	ECC
django-tdd	TDD with pytest-django, factory_boy, model/view/serializer testing	ECC
django-verification	Django pre-deployment verification: migrations, tests, security scans	ECC (adapted)
doc-coauthoring	Structured documentation co-authoring workflow	anthropics/skills
docker-patterns	Docker/Compose: multi-container orchestration, networking, security hardening	ECC
docx	Word document and `.dotx` template creation and manipulation	anthropics/skills
frontend-design	Visual design direction for new or reshaped UI: aesthetics, typography, avoiding templated defaults	anthropics/skills
mcp-builder	Guide for creating MCP servers	anthropics/skills
pdf	PDF reading, merging, splitting, OCR	anthropics/skills
playground	Interactive HTML playgrounds: visual controls, live preview, prompt output	claude-plugins-official
postgres-patterns	PostgreSQL query optimization, schema design, indexing, RLS, connection pooling	ECC
pptx	PowerPoint presentation and `.potx` template creation	anthropics/skills
skill-creator	Create and optimize skills, run evals, benchmark triggering accuracy	anthropics/skills
webapp-testing	Web app testing with Playwright	anthropics/skills
xlsx	Spreadsheet creation and manipulation	anthropics/skills

Commands (`.claude/commands/`)

Commands are the legacy format for skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work identically. Existing command files continue to work and support the same frontmatter as skills.

Skills are the recommended format because they support additional features (supporting files directory, auto-discovery by Claude). Commands are kept for simplicity when a single .md file is sufficient.

Full documentation: code.claude.com/docs/en/skills

Command	Description	Source
`/build-fix`	Incremental build/type error fixing with guardrails	ECC
`/clean-gone`	Clean up stale local branches marked as [gone] and their worktrees	claude-plugins-official
`/commit`	Stage and create a git commit with contextual message	claude-plugins-official
`/commit-push-pr`	One-command workflow: branch → commit → push → PR creation	claude-plugins-official
`/feature-dev`	Guided 7-phase feature development with codebase exploration and architecture design	claude-plugins-official
`/notebook-review`	Review Jupyter notebooks	this template
`/orchestrate`	Multi-agent workflow: planner → tdd-guide → code-reviewer → security-reviewer	ECC (adapted)
`/review-pr`	Interactive PR review with formal GitHub decision (approve/request changes/comment)	claude-plugins-official (adapted)
`/revise-claude-md`	Capture session learnings and update CLAUDE.md	claude-plugins-official
`/test-coverage`	Analyze coverage gaps, generate missing tests for 80%+ target	ECC

MCP Servers (`.mcp.json`)

MCP (Model Context Protocol) servers extend Claude Code with external tool integrations. They run as local processes that Claude communicates with via stdio, providing access to databases, browsers, APIs, and other services.

The .mcp.json file in the project root defines which servers are available. Each server declaration specifies a command to launch and its arguments. Environment variables are expanded at runtime using ${VAR:-default} syntax.

Full documentation: code.claude.com/docs/en/mcp

Server	Description	Recommended
context7	Up-to-date library documentation lookup	Always
playwright	Browser automation, testing, and web scraping	If testing web apps or scraping
postgres	PostgreSQL database interaction	If using PostgreSQL
docker	Docker container management	If using Docker

context7 is recommended for all projects — it gives Claude access to current library docs, reducing hallucinated APIs and outdated patterns. The other servers are situational: keep or remove them from .mcp.json based on your project's stack.

Status Line (`.claude/statusline.py`)

A persistent status bar at the bottom of Claude Code that displays session info at a glance. It's pre-configured in .claude/settings.json and works automatically — no setup needed.

The status line shows three rows:

Row	Content
1	Model name, current directory, git branch with staged/modified counts (color-coded)
2	Context window progress bar (green/yellow/red), context %, session cost, elapsed time, prompt-cache hit ratio (green while the cache is warm, yellow once it has gone cold; hidden until first API response, requires Claude Code v2.1.251+)
3	Rate limit usage bars for 5-hour and 7-day windows (Pro/Max only, hidden until first API response)

The script is written in Python and works cross-platform: Windows, macOS, and Linux. Git operations are cached for 5 seconds to avoid lag on large repositories.

Full documentation: code.claude.com/docs/en/statusline

Continuous Integration

.github/workflows/ci.yml runs on every pull request and on pushes to main. It lints and runs the hook tests, so the guardrails this template ships are known to work before anyone copies the .claude/ folder.

Check	Catches
`ruff check` / `ruff format --check`	Lint (rule sets `E`, `F`, `W`, `I`, `UP`, `B`, `SIM`) and formatting on `.claude/statusline.py` and `tests/` (`src/*/.py` is in scope for projects built from this template)
`shellcheck --severity=warning`	Shell quoting and syntax bugs in the hook scripts
`pytest`	Hooks reaching the wrong decision — see below

Run the same checks locally with:

uv run ruff check . && uv run ruff format --check . && uv run pytest

Hook tests (`tests/`)

The hooks are the only enforced guardrails in this setup, and the faults that matter in them are logic errors rather than shell errors: a script can be syntactically clean, correctly wired, and still reach the wrong decision — or stop firing altogether. shellcheck sees none of that.

So each test runs the real script in a subprocess with a crafted payload and asserts on the decision it emits. Nothing is mocked, because "the hook stopped firing" is precisely the regression worth catching, and a mock cannot fail that way.

File	Asserts
`test_protect_main_hook.py`	Force pushes, pushes to main, `reset --hard` and broad `rm -rf` are denied — while `--force-with-lease`, `rm -rf .git` and `rm -rf ~/tmp-dir` still pass
`test_enforce_uv_hook.py`	Bare `python`/`pytest`/`ruff` are rewritten to `uv run ...`; `pip` and compound commands are denied; anything already using uv is left alone
`test_guard_secrets_hook.py`	Credential-shaped prompts are blocked, prose about credentials is not
`test_session_start_hook.py`	Missing `.venv` or a stale `uv.lock` is reported; a healthy project stays silent
`test_verify_hook.py`	The `stop_hook_active` loop guard and the non-Python-project exit
`test_auto_lint_hook.py`	Non-Python files, deleted files and payloads without a path are ignored
`test_heredoc_false_positives.py`	Tooling quoted inside a heredoc body is text, not an invocation — while code around the heredoc is still caught
`test_statusline.py`	The status line's prompt-cache segment: green while warm, yellow once cold, hidden until a hit ratio exists

Two gaps are deliberate and worth knowing:

verify.sh's ruff/pytest execution path is not covered. Running it from inside the suite would invoke pytest recursively, and a throwaway uv project would need a network install on every CI run. Only its guard clauses are tested.
auto-lint.sh's formatting path is not covered, because whether ruff acts on a given file depends on the surrounding project's include configuration. Only the conditions under which the hook must do nothing are tested.

The tests do not check the hook wiring in settings.json — that a hook's matcher and if condition actually route the events you expect. A hook can be correct, referenced, and still never fire. That wiring is verifiable only by running Claude Code.

Contributing

Contributions are welcome! If you have ideas for new agents, skills, rules, or improvements to the existing setup:

Fork the repository
Create a feature branch (git checkout -b feature/your-idea)
Make your changes
Submit a Pull Request with a clear description of what you added or changed

For bug reports or suggestions, open an issue.

Credits

Most agents, skills and commands in .claude/ are not original to this template. They come from the projects below, whose authors deserve the credit for them. "Adapted" in the Source columns means the file was substantially rewritten here — typically ported to Python, uv and ruff — while the rest are copies with at most small local edits.

Source	License	What comes from it	Last synced
anthropics/skills	see each skill's `LICENSE.txt`	10 skills: `claude-api`, `doc-coauthoring`, `docx`, `frontend-design`, `mcp-builder`, `pdf`, `pptx`, `skill-creator`, `webapp-testing`, `xlsx`	`683bc88` (2026-10-07)
anthropics/claude-plugins-official	Apache-2.0	3 skills, 6 agents and 6 commands from the `claude-code-setup`, `claude-md-management`, `playground`, `feature-dev`, `pr-review-toolkit` and `commit-commands` plugins	skills: `8f814f4` (2026-10-15); agents and commands: initial import (2026-03-20)
ECC (Everything Claude Code) by Affaan Mustafa	MIT	9 skills, 7 agents and 3 commands	skills: `b92f181` (2026-10-12); agents and commands: initial import (2026-03-20)

Where a component exists in both upstreams, the Anthropic copy is the one vendored — except code-reviewer, which shares only its name with the Anthropic agents and comes from ECC. /notebook-review is the only component written for this template.

References

This project builds on top of the official Claude Code documentation and tooling by Anthropic:

Claude Code Documentation: setup guides, CLAUDE.md reference, skills, agents, MCP configuration
Anthropic GitHub: official repositories and examples
Model Context Protocol: open standard for LLM-tool integrations

claude-code-python-setup

Set up

README

Claude Code Python Setup

Prerequisites

Claude Code

Optional Dependencies

Project Structure

Setup

1. Copy the .claude folder

2. Configure MCP servers

3. Set environment variables (optional)

4. Verify MCP servers

5. Install development tooling (optional)

Components

CLAUDE.md (project root)

Rules (.claude/rules/)

Hooks (.claude/hooks/)

Permissions (.claude/settings.json)

Bash Sandbox (opt-in, not enabled here)

Agents (.claude/agents/)

Skills (.claude/skills/)

Commands (.claude/commands/)

MCP Servers (.mcp.json)

Status Line (.claude/statusline.py)

Continuous Integration

Hook tests (tests/)

Contributing

Credits

References

1. Copy the `.claude` folder

Rules (`.claude/rules/`)

Hooks (`.claude/hooks/`)

Permissions (`.claude/settings.json`)

Agents (`.claude/agents/`)

Skills (`.claude/skills/`)

Commands (`.claude/commands/`)

MCP Servers (`.mcp.json`)

Status Line (`.claude/statusline.py`)

Hook tests (`tests/`)