uv-cli-creator

Design goals

The goal is simple:

• Do not manually install dependencies, and do not rely on a Python environment that is already prepared on the host
• By default rely only on one uv
• Easy to modify and version-control
• The script can be executed directly like an executable file:./scripts/foo.py

How to implement

The basic flow of the entry script:

uv init --script scripts/foo.py
uv add --script scripts/foo.py <package>
chmod +x scripts/foo.py
./scripts/foo.py --help

Dependency management rules:

• Add a dependency:uv add --script scripts/foo.py <package>
• Remove a dependency:uv remove --script scripts/foo.py <package>
• Do not manually edit the header /// script dependency block

Invocation rules:

• Place the entry script in the corresponding skill's scripts/ directory
• The entry script should be directly executable by default:./scripts/foo.py
• Do not write the entry script in the skill documentation as python ... or uv run python ...

When used by other skills

If a skill calls this script, the following template should be written directly into that skill's own SKILL.md, and kept as an invocation convention:

说明：以下脚本调用均以当前 `SKILL.md` 所在文件夹为 workdir。

脚本调用方式（必须直接当作可执行命令运行，不要用 `uv run python` 或 `python`）：

```bash
cd skills/<skill-name> && ./scripts/<tool>.py --help
```

错误示例：

```bash
uv run python skills/<skill-name>/scripts/<tool>.py --help
python skills/<skill-name>/scripts/<tool>.py --help
```

Detail preferences

• Dependency library preferences:

Scenario	Preferred choice	Description
Command line	Typer	Used to define the CLI, arguments, and subcommands
Human-readable output	Rich	Used for tables, prompts, and clearer terminal output
Argument validation	Pydantic	Used for input validation and clearer error messages

• Ordinary modules imported by the entry script should not have a shebang, and should not have /// script
• Keep arguments and output stable; when machine-readable output is needed, provide --json
• Paths, repository directories, and configurations that can be passed in via arguments must not secretly depend on the current shell cwd
• Write short Chinese docstrings for modules, functions, and types

Verification

• ./scripts/foo.py --help
• uv run ruff check <path>
• uv run ruff format --check <path>