How to use Python skills with Claude Code
Skills bottle up your Python workflow. Instead of re-explaining “tighten these type annotations” or “use uv instead of pip” every session, save the procedure to a markdown file once and let Claude Code reach for it when you ask, either by slash command or by describing the task in plain English. Long reference material that would crowd a CLAUDE.md only loads when the skill runs.
This guide installs Astral’s plugin, walks through writing a custom Python skill, and shows when a skill beats CLAUDE.md or a hook.
Tip
For a hands-on walkthrough that sets up CLAUDE.md, hooks, and a custom skill together on a fresh project, see the project setup tutorial.
How skills work
Each skill is a SKILL.md file with YAML frontmatter (name, description, optional fields) plus a markdown body. Local Claude Code sessions load skills from these locations:
| Location | Path | Scope |
|---|---|---|
| Organization | Managed .claude/skills/<name>/SKILL.md |
Machines where the organization deploys it |
| Personal | ~/.claude/skills/<name>/SKILL.md |
Every project on your machine |
| Project | .claude/skills/<name>/SKILL.md |
Only the project where it lives |
| Plugin | Bundled with /plugin install, namespaced as plugin:skill |
Wherever the plugin is enabled |
Invoke a skill by typing /<skill-name> in the Claude Code prompt, or let Claude pick it up automatically when your prompt matches the skill’s description. Plugin skills carry the plugin name in front of a colon, so Astral’s plugin’s Ruff skill is /astral:ruff.
The description advertises the skill to Claude; the full body loads on invocation. Keep the description specific and move supporting reference material into separate files. See the official skills documentation for the full frontmatter reference.
Install Astral’s skill set for uv, Ruff, and ty
The handbook recommends Astral’s plugin as the default skill set for any uv-managed Python project. It bundles /astral:uv, /astral:ruff, and /astral:ty, plus a ty language server that streams type-checking diagnostics into the conversation.
Run two slash commands inside Claude Code:
/plugin marketplace add astral-sh/claude-code-plugins
/plugin install astral@astral-shOnce installed, invoke /astral:ty or /astral:ruff at the start of your prompt to load that skill directly. A natural-language request can also trigger it through its description.
For a team-wide install via .claude/settings.json so every collaborator gets the plugin after trusting the repo, see How to install Astral’s plugins for Claude Code.
Write your own Python skill
Lift repeated Python instructions into a project skill so the next teammate or AI session reuses them instead of regenerating the steps from scratch.
This walkthrough creates a type-tighten skill that audits Python type annotations against modern conventions and verifies the result with ty.
Create the skill directory
In any uv-managed Python project:
mkdir -p .claude/skills/type-tightenWrite the SKILL.md
Create .claude/skills/type-tighten/SKILL.md:
---
name: type-tighten
description: Tighten Python type annotations in the path provided. Use when the user wants stronger types or modern type syntax.
argument-hint: "[path]"
---
When invoked, audit Python type annotations in $ARGUMENTS:
1. Read the project's Python requirement and type-checker configuration.
2. Run `uv run ty check $ARGUMENTS` to record the baseline.
3. Propose annotation changes within the requested scope. Preserve runtime behavior and the supported Python versions; do not infer `-> None` just because a return annotation is missing.
4. Apply the requested changes and rerun the same check.
5. Report new errors separately from pre-existing failures.
Report the number of annotations changed and whether the type checker still passes.The frontmatter’s description is what Claude reads to decide whether to load the skill automatically. Write it like a brief task summary the model can match against the user’s prompt. The argument-hint is shown during slash-command autocomplete so the user knows what to pass.
Invoke the skill
In Claude Code, type:
/type-tighten src/myapp/Or ask in natural language (“tighten the types in src/myapp/”) and Claude matches the prompt against the skill’s description to load the same procedure. The skill supplies the procedure; inspect the proposed changes and the check results before accepting them.
To make the skill global instead of project-scoped, move the directory to ~/.claude/skills/type-tighten/. Organization skills take precedence over personal skills, which take precedence over project skills with the same name. To stop Claude from auto-loading a skill (so Claude cannot select it on its own), add disable-model-invocation: true to the frontmatter.
Tip
Keep SKILL.md under 500 lines. For longer reference material, drop additional files into the skill directory and reference them from the body. Claude only reads them when the skill points at them.
Choose between skills, hooks, and CLAUDE.md
Claude Code gives you several places to encode Python conventions. Each one suits a different shape of guidance:
| Need | Best fit |
|---|---|
| Project conventions loaded into session context (preferred tools, repository structure) | CLAUDE.md |
A repeatable procedure Claude loads on demand, by slash command or natural-language match against the skill’s description (“tighten types,” “review exception handling”) |
Skill |
A rule that runs automatically on a tool event, blocking the call or surfacing feedback (no pip install, autoformat after every edit) |
Hook |
Skills sit between the other two. They bundle a step-by-step procedure that loads only when triggered, which keeps the always-on context (CLAUDE.md) lean. Hooks are stricter: they fire on tool events and can block, while skills only run when invoked.
The layers compose. CLAUDE.md sets the default tooling for the project and a skill like /type-tighten loads on invocation or a description match. A hook can still block pip install underneath, regardless of which skill or guidance Claude is following.
Verify and maintain a skill
Open /skills to confirm the skill is visible, then invoke it explicitly and inspect the commands and results. If it does not trigger from natural language, refine description; use /type-tighten when you need deterministic selection.
Local personal skills are not available in cloud sessions. Follow Claude Code’s cloud skill guidance when moving the workflow to another environment; skill locations and plugin availability depend on the session type.
Review skill files and supporting scripts before installing them. A body can include !`command` snippets that execute before Claude receives the expanded instructions. Tool permissions still apply, and allowed-tools can pre-approve tools for the invocation. A skill is executable workflow guidance, not an access-control boundary.