python-tool-skill-creator

Overview

A python-tool-skill is a Kilo skill that bundles a Python CLI tool inside its assets/ directory. The tool is built with Click and executed at runtime via uvx, keeping the skill directory clean — no venv/, no __pycache__, no .pyc files. It is an alternative to MCP tools that requires no running server.

For full pattern details, consult references/pattern.md.

Workflow

To create a new python-tool-skill, follow these steps in order.

Step 1: Understand the tool's purpose

Before scaffolding, clarify:

• What domain/service/API does the tool cover?
• What commands should it expose?
• What Python dependencies are needed beyond Click?

Step 2: Scaffold the skill

Run the bundled init script to generate the directory skeleton:

python scripts/init_python_tool_skill.py <skill-name> --path <output-dir>

The script is located at scripts/init_python_tool_skill.py relative to this skill's base directory. Use the full absolute path when invoking it.

This creates:

<output-dir>/<skill-name>/
├── SKILL.md
└── assets/
    ├── tool.py          (Click CLI skeleton)
    └── pyproject.toml   (hatchling build config)

Step 3: Implement tool.py

Edit assets/tool.py to implement the actual CLI commands. Follow Click conventions:

• Top-level @click.group() named cli
• Sub-commands registered with @cli.command("name")
• click.echo() for output, click.ClickException for errors

For Click usage patterns and examples, see references/pattern.md.

Step 4: Update pyproject.toml

• Set name to the skill/tool name (must match the CLI command)
• Add any runtime dependencies under [project] dependencies
• Verify [project.scripts] maps the command name to tool:cli

Step 5: Lock dependencies

cd <output-dir>/<skill-name>/assets
uv lock

Commit uv.lock alongside tool.py and pyproject.toml. This ensures reproducible installs.

Step 6: Test the tool

uvx --from <path-to-assets> <skill-name> --help
uvx --from <path-to-assets> <skill-name> <command> [args]

After any edit to tool.py or pyproject.toml, add --reinstall:

uvx --from <path-to-assets> --reinstall <skill-name> <command>

Step 7: Update SKILL.md

Fill in the generated SKILL.md for the new skill:

• Set a precise description in the YAML frontmatter (controls when the skill triggers — be specific about what queries should activate it)
• Update the Overview section
• Update the command table with real commands

Key rules

• The tool entry point must be tool.py with a Click group named cli.
• pyproject.toml must have [tool.hatch.build.targets.wheel] packages = ["."] so hatchling includes tool.py in the wheel.
• uv.lock must be committed — it pins dependencies for reproducibility.
• Never create a venv/ inside the skill directory; uvx manages isolation.
• Use uvx --from <assets-dir> — the --from argument points to the assets/ directory, not the skill root.

Reference

For the full pattern specification, pyproject.toml conventions, Click patterns, dependency management, troubleshooting, and a comparison with MCP tools, read references/pattern.md.