Python CLI-Based Agent Skills
A pattern for building AI agent tools as standalone Python CLIs that run via uvx, bundled inside skills with no virtual environment pollution.
Read the full writeup: An Alternative to MCP - Python CLI-Based Agent Skills
What it is
A python-tool-skill packages a Python CLI tool in a skill's assets/ directory. The tool is built with Click and run via uvx, which handles environment isolation automatically.
skill-name/
├── SKILL.md ← trigger description + agent instructions
└── assets/
├── tool.py ← Click CLI entry point
├── pyproject.toml
└── uv.lock
The agent invokes it like any other CLI tool:
uvx --from /path/to/skill/assets tool-name <command>
Why it exists
CLI tools provide text-efficient interfaces that serve as excellent agent tools. Too often, custom skills devolve into messy bash scripts that exceed their original purpose. Python Click CLIs offer structure and a solid foundation for building upon.
Python-tool-skills let you build custom tools with the same simplicity as wrapping existing CLIs. uvx handles environment isolation, dependencies are locked in a committed uv.lock, and there's no repo pollution.
Key benefits
- Just CLI programs: Test independently, use outside agent context
- Fewer tokens than MCP through progressive disclosure (agent loads
--helpon demand rather than full schemas upfront) - No server startup process to manage