template-skill-cli/.scaffold-notes.md

Python + click skill (skill-cli template): a .sh shim + one uv script. No venv to create, no requirements to install — uv reads the PEP-723 header on first run.

• scripts/@@NAME@@.sh — thin shim carrying # @alias: @@NAME@@. KEEP IT: the alias installer only scans *.sh, so without it the skill never lands on PATH.
• scripts/@@PKG@@.py — all the logic. A cli group with two example commands: run (ordered repeatable --step KIND:VALUE) and send (JSON POST with retries + endpoint fallback), plus the load_env_claude / err / die / emit helpers.
• scripts/test_@@PKG@@.py — click CliRunner smoke tests; run it directly.
• SKILL.md — frontmatter + docs. The description: is what makes the skill get picked, so say what it does AND when to use it.

TODO [ ] ./scripts/test_@@PKG@@.py (first run resolves click/requests/pytest via uv) [ ] Replace the run / send example commands with the real ones; delete what you don't need (the helpers are the part worth keeping). [ ] Fill in SKILL.md — the Command table and Output section must match the real subcommands, an agent reads those instead of running --help. [ ] If the skill needs a secret/host: add @@ENVPREFIX@@_* to the gitignored .env.claude at the repo root, read it via os.environ (load_env_claude already ran). [ ] scripts/install-skill-aliases.sh → puts @@NAME@@ on PATH [ ] Mention the alias in CLAUDE.md's "Skill aliases" list if it's a common one.