Agent skill

python

Python development with uv and PEP 723 inline dependencies

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/yurifrl/cly/tree/main/.opencode/skill/python

SKILL.md

Python Development Best Practices

Overview

Python scripts in this repository use uv for dependency management and follow a standalone script pattern with inline PEP 723 dependency declarations when external packages are needed.

Always Use uv

  • NEVER use pip, pipenv, poetry, or venv directly
  • ALWAYS use uv for all Python package management
  • Script shebang: #!/usr/bin/env -S uv run --quiet --script

Script Templates

Script with Dependencies

python
#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "click",
#     "rich",
#     "questionary",
# ]
# ///

"""Brief script description."""

import click
from rich.console import Console

console = Console()

@click.command()
def main():
    """Main entry point."""
    console.print("[green]Hello![/green]")

if __name__ == "__main__":
    main()

Simple Script (No Dependencies)

python
#!/usr/bin/env python3

"""Brief script description."""

def main():
    """Main entry point."""
    print("Hello!")

if __name__ == "__main__":
    main()

PEP 723 Inline Script Metadata

When external packages are needed, use inline dependency declarations:

python
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "package-name>=1.0.0",
# ]
# ///

Benefits:

  • No separate requirements.txt needed
  • Script is self-contained and portable
  • uv run automatically installs dependencies in isolated environment

Common Dependencies

CLI Tools

python
"click>=8.1.0",          # Command-line interface
"typer>=0.9.0",          # Alternative CLI framework
"questionary>=2.0.0",    # Interactive prompts

Output & Formatting

python
"rich>=13.0.0",          # Rich terminal output
"tabulate>=0.9.0",       # Table formatting

Data Handling

python
"pyyaml>=6.0",           # YAML parsing
"pydantic>=2.0",         # Data validation
"python-dateutil>=2.8",  # Date/time parsing

HTTP & APIs

python
"httpx>=0.27.0",         # Modern HTTP client
"requests>=2.31.0",      # Traditional HTTP client

Running Scripts

bash
# Direct execution
./script_name.py

# With arguments
./script_name.py --option value

Anti-Patterns (DO NOT USE)

❌ pip install ❌ python -m venv ❌ requirements.txt for standalone scripts ❌ Global package installs

Best Practices

✅ Use uv for all package management ✅ Use inline # /// script block when dependencies needed ✅ Use type hints (Python 3.11+) ✅ Make scripts executable: chmod +x script.py ✅ Use pathlib.Path instead of string paths ✅ Handle errors with try/except ✅ Use rich.console for colored output ✅ Use click or typer for CLI parsing

Common Patterns

CLI Tool

python
#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# dependencies = ["click>=8.1.0", "rich>=13.0.0"]
# ///

import click
from rich.console import Console

console = Console()

@click.command()
@click.option('--verbose', is_flag=True)
@click.argument('name')
def main(verbose: bool, name: str):
    """Greet NAME."""
    if verbose:
        console.print("[dim]Verbose mode[/dim]")
    console.print(f"[green]Hello, {name}![/green]")

if __name__ == "__main__":
    main()

Interactive Prompts

python
#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# dependencies = ["questionary>=2.0.0", "rich>=13.0.0"]
# ///

import questionary
from rich.console import Console

console = Console()

def main():
    """Interactive tool."""
    name = questionary.text("Name?").ask()
    choice = questionary.select(
        "Pick one:",
        choices=["A", "B", "C"]
    ).ask()
    console.print(f"[green]{choice}[/green]")

if __name__ == "__main__":
    main()

When NOT to Use Python

Use bash/fish for:

  • Simple file operations
  • Git operations
  • Single-command wrappers

Use Python for:

  • Complex logic
  • Data transformation
  • API interactions
  • Interactive CLI tools

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

yurifrl/cly

ag:changelog

Generates and updates project CHANGELOG.md from git commits, conversation decisions, and architectural changes. Auto-invoke this skill when new features are added, features are removed, or architecture changes occur.

0 0
Explore
yurifrl/cly

prompt-engineering

Prompt engineering reference and workflow for creating, refining, and reviewing high-quality prompts for AI tools, agents, and skills.

0 0
Explore
yurifrl/cly

ag:claudemd-update

Updates CLAUDE.md based on recent conversation history. This skill should be used when the user asks to update their CLAUDE.md, sync learnings from conversations, or review what was discussed recently.

0 0
Explore
yurifrl/cly

write-skill

Create Claude Code skills with proper structure and documentation. Use when building custom skills, writing SKILL.md files, or when user asks "write a skill" or "create Claude skill".

0 0
Explore
yurifrl/cly

add-module

Create new demo or utility modules following CLY project patterns. Use when adding TUI demonstration modules to modules/demo/ or utility modules to modules/, following Bubbletea/Bubbles conventions with proper Cobra CLI integration.

0 0
Explore
yurifrl/cly

git-worktrees

Manage git worktrees for parallel development. Use when user mentions worktrees, parallel branches, or working on multiple branches simultaneously.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results