Python-Tool-Skill Creator

A collection of python-tool-skills — plus the creator skill that makes building new ones fast.

What is a python-tool-skill?

A python-tool-skill is an AI agent tool in the form of a skill. It bundles a Python CLI tool in its assets/ directory. The CLI is built with Click and executed at runtime via uvx, so:

• No venv/, no __pycache__, no .pyc files pollute the skill directory
• No persistent server process to manage (unlike MCP tools)
• Dependencies are pinned via a committed uv.lock — reproducible and offline-capable after first run

my-skill/
├── SKILL.md          ← trigger description + agent instructions
└── assets/
    ├── tool.py       ← Click CLI (entry point)
    ├── pyproject.toml
    └── uv.lock

The agent runs the tool with:

uvx --from /path/to/skill/assets my-skill <command> [options]

Skills in this repo

f1 — Formula 1 calendar (prototype)

The original prototype skill. Provides F1 race calendar and session schedule data via the OpenF1 API.

Command	Description
f1 races	List all races for the current year (or --year YYYY)
f1 race <round>	Show session schedule for a specific round number

python-tool-skill-creator — scaffold new skills

A meta-skill: load it and ask the agent to build a new python-tool-skill. It bundles a scaffolding script and a reference document that guide the agent through the full creation workflow.

What it does:

1. Runs scripts/init_python_tool_skill.py to generate the directory skeleton
2. Implements assets/tool.py with the requested Click commands
3. Updates assets/pyproject.toml with dependencies
4. Locks dependencies with uv lock
5. Tests the tool via uvx
6. Fills in SKILL.md with an accurate description and command table

# Scaffold a new skill manually
python python-tool-skill-creator/scripts/init_python_tool_skill.py <skill-name> --path <output-dir>

weather — current conditions and forecasts

Created by python-tool-skill-creator. Provides weather data via the Open-Meteo API — free, no API key required.

Command	Description
weather current LOCATION	Current temperature, conditions, humidity, and wind
weather forecast LOCATION [--days N]	Daily forecast table (1–16 days, default 7)

Repo layout

python-tool-skill-creator/
├── f1/                          ← prototype skill
├── weather/                     ← skill created by the creator skill
└── python-tool-skill-creator/   ← the creator skill itself
    ├── assets/template/         ← tool.py + pyproject.toml templates
    ├── scripts/                 ← init_python_tool_skill.py scaffolder
    ├── references/pattern.md   ← full pattern specification
    └── SKILL.md

Creating a new skill

With the creator skill (recommended)

Load python-tool-skill-creator as a skill and prompt:

"Create a python-tool-skill for <your domain>"

The agent will scaffold, implement, lock, and test the skill end-to-end.

Manually

1. Scaffold the skeleton:

   python python-tool-skill-creator/scripts/init_python_tool_skill.py my-skill --path .

2. Implement my-skill/assets/tool.py with your Click commands.

3. Add dependencies to my-skill/assets/pyproject.toml if needed.

4. Lock:

   cd my-skill/assets && uv lock

5. Test:

   uvx --from my-skill/assets my-skill --help
   uvx --from my-skill/assets my-skill <command>

6. Fill in my-skill/SKILL.md — the description field controls when the agent triggers the skill.

After any edit to tool.py or dependencies, add --reinstall to force uvx to rebuild its cache:

uvx --from my-skill/assets --reinstall my-skill <command>

Python-tool-skill vs MCP tools

Concern	MCP tool	Python-tool-skill
Runtime	Persistent server process	Ephemeral uvx invocation
Setup	Server config in client	uvx --from assets/
Environment isolation	User-managed venv/container	uvx-managed, automatic
Repo pollution	Optional	None — no venv, no .pyc
Offline use	Depends on server	Works after first cache population
Dependency pinning	Server-side	uv.lock committed in skill assets

Requirements

• uv (curl -LsSf https://astral.sh/uv/install.sh | sh)