Agent skill, license/publish template options, repo CI, and modernization (tbd v0.2.3)

[jlevy]

Summary

Full implementation of the agent-skill and modernization plan (spec: docs/project/specs/active/plan-2026-06-11-agent-skill-and-modernization.md, tracked as epic smu-7kwg).

The skill (skills/simple-modern-uv/)

Installable via npx skills add jlevy/simple-modern-uv, raw-URL prompt paste, or manual copy. SKILL.md (skills-ref-validated) carries the two-tier interview contract — essentials the user confirms once (kebab-case package name with derived snake_case module shown, description, license, publish-or-not); conventions applied silently (src/ layout, v0.1.0 first tag, 3.11+ floor) — and routes three flows: new project, upgrade existing project (references/adopt-existing.md: render-and-merge with Poetry/setuptools/PDM/mypy translations), and update templated project. references/customize.md covers license changes, private packages, and reconciling new template questions; references/faq.md seeds ten real failure modes. All commands pin uvx copier@9.15.1.

Template changes

• package_license: MIT (default), Apache-2.0, BSD-3-Clause, AGPL-3.0-or-later, Proprietary, or None (choose later) — canonical license texts; None renders no LICENSE file and no license field. publish_to_pypi gates publish.yml, docs/publishing.md, and the Private :: Do Not Upload classifier. Verified behavior-preserving: defaults reproduce prior output; a v0.2.27 render updates to this branch with zero conflicts and converges to a fresh render (including across the LICENSE template rename).
• AGENTS.md in generated projects (agents.md standard; CLAUDE.md symlink note).
• uv 0.11.12 → 0.11.17, ruff floor ≥0.15.15, basedpyright floor ≥1.39.6 (all clear the 14-day cooloff); [tool.uv] required-version = ">=0.9".

CI for this repo (first CI here)

Render smoke tests (default, proprietary/no-publish, no-license variants with output assertions and full sync/lint/test/build), the update-path test, skill validation plus link check, and doc format check (cooloff scoped to render jobs so the pinned formatter resolves).

Docs

Agent-first README (uvtemplate fully removed; retirement of the external repo tracked post-release). updating.md: CI split, the answer-schema evolution policy, and version-choice guidance (minor vs patch) in the release step. New living doc research-uv-changes.md (uv 0.6.x→0.11.x timeline and decisions). Common-doc-guidelines applied throughout (Title Case headings, footers, present-state phrasing, em dashes replaced with preferred punctuation).

Validation performed

All license variants and the no-publish/no-license variants rendered and inspected; full uv sync → lint --check → pytest → build on renders with uv 0.11.17; update-path both cases locally and in CI; make format-check, skills-ref validate clean. Remaining post-merge: skill activation testing, downstream release-gate run, uvtemplate retirement.

---

Draft release notes for v0.3.0 (minor release; copy into gh release create after the downstream gate passes, per updating.md Steps 3–8)

What's Changed

New Features

Agent skill: use the template from any AI coding agent.
skills/simple-modern-uv/ routes three workflows: create a new project, upgrade an existing Python package (including Poetry/setuptools/PDM migrations), or update an already-templated project. Install with npx skills add jlevy/simple-modern-uv, or paste the raw SKILL.md URL into any agent.

New template questions (defaults reproduce prior output, so copier update --defaults is a no-op for existing projects):

• package_license: MIT (default), Apache-2.0, BSD-3-Clause, AGPL-3.0-or-later, Proprietary, or None (choose later). Drives the LICENSE file and pyproject license field; None renders neither.
• publish_to_pypi: true (default) or false. false removes publish.yml and docs/publishing.md and adds the Private :: Do Not Upload classifier.

If you had customized the license or deleted publishing files by hand, pass explicit values when updating (e.g. copier update --data publish_to_pypi=false); see the skill's references/customize.md.

AGENTS.md in generated projects (agents.md standard) with build/test commands and conventions.

CI for the template repo itself: render smoke tests, an update-path test from the previous release, and skill validation on every PR.

Improvements

• Updated uv to 0.11.17 in CI workflows; ruff floor >=0.15.15; basedpyright floor >=1.39.6
• [tool.uv] required-version = ">=0.9" in generated projects
• README is agent-first; the interactive uvtemplate helper is retired (projects it created keep updating normally)
• New research docs: uv changes timeline (research-uv-changes.md) and refreshed type-checker comparison

Downstream validation: jlevy/simple-modern-uv-template CI passed for <TEMPLATE_COMMIT>

Full Changelog: v0.2.27...v0.3.0

https://claude.ai/code/session_01T3RGHgchJZBpvuiesrrE7X

[jlevy]

Senior Engineering Review

Reviewed PR #25 at 66c75e1fb7a6336e2754287162580c4f799150f6 using tbd shortcut review-github-pr / review-code, checked out the branch locally as codex/review-pr-25, and exercised the new-project path in a temporary GitHub repo: https://github.com/jlevy/test-smu-1.

Findings

1. [P1] New-project setup leaves the editable install stuck at 0.0.0.
   The new-project instructions run uv sync --all-extras before the first commit in skills/simple-modern-uv/SKILL.md:92-99, README.md:347-353, and the Copier after-copy message in copier.yml:17-23. I followed that sequence in /private/tmp/test-smu-1: after git init, uv sync --all-extras, and the initial commit, uv run python -c "from importlib.metadata import version; print(version('test-smu-1'))" still returned 0.0.0. uv build computed 0.0.1.dev1+61fedbf, and uv sync --reinstall-package test-smu-1 then updated the installed metadata to 0.0.1.dev1+61fedbf. CI does not catch this because the render test commits and tags before the first sync (.github/workflows/ci.yml:90-104). Fix the user/agent setup sequence so the first editable install happens after a commit, or explicitly reinstall the local package after the initial commit.

2. [P2] The gh setup hook falsely warns on valid keyring auth and points to a missing doc.
   Both .codex/ensure-gh-cli.sh:109-121 and .claude/scripts/ensure-gh-cli.sh:109-121 only treat GH_TOKEN as an authenticated state. On this machine, gh auth status succeeds as jlevy via keyring, but running either hook prints NOTE: GH_TOKEN not set - some operations may require authentication and links to docs/general/agent-setup/github-cli-setup.md, which is not in this repo. The hook should run gh auth status regardless of whether GH_TOKEN is set, report success for any valid gh auth mechanism, and only warn/fail when gh auth status actually fails.

3. [P2] New CI/agent instructions still execute unpinned moving targets.
   The new root CI uses npx --yes skills-ref@latest for validation (.github/workflows/ci.yml:165-166), and the new root AGENTS.md smoke-test example uses unpinned uvx copier copy (AGENTS.md:32-35). The newly added root CI also uses the floating actions/checkout@v6 tag in each job (.github/workflows/ci.yml:34, 57, 116, 164) even though the docs and PR text emphasize pinned tools and the 14-day cool-off. These paths bypass the uv cool-off entirely and can change or fail independently of the PR. Pin skills-ref, pin the uvx copier@9.15.1 examples, and use an exact checkout version or SHA if the policy is immutable action refs.

4. [P3] README still tells users to hand-edit outputs for the new template questions.
   README.md:292-296 still says to update license/LICENSE manually and delete .github/workflows/publish.yml if not publishing. That contradicts the new package_license and publish_to_pypi answers and can leave .copier-answers.yml inconsistent, causing future updates to reintroduce or revert those files. Replace that paragraph with the new answer-based flow and link to skills/simple-modern-uv/references/customize.md.

Validation Performed

• gh auth status: authenticated as jlevy.
• gh pr checks 25 --repo jlevy/simple-modern-uv: all 5 PR checks passing.
• Checked out PR branch locally at 66c75e1.
• make format-check: pass.
• npx --yes skills-ref@latest validate skills/simple-modern-uv: pass, with npm config warnings.
• Rendered PR head with uvx copier@9.15.1 copy --defaults --vcs-ref=HEAD ... --data publish_to_pypi=false into /private/tmp/test-smu-1; verified publish workflow/docs were omitted.
• Generated project local checks: make lint-check pass, make test pass, uv build pass.
• Created and pushed temporary sandbox repo jlevy/test-smu-1; its generated GitHub Actions CI passed on Python 3.11, 3.12, 3.13, and 3.14.
• Tested repo-local agent hooks: Codex/Claude tbd-session.sh --brief works; Codex post-tool closing reminder works with a sample git push payload; gh setup hook has the false-auth warning described above.

No existing PR comments or review threads were unresolved at review time.

[jlevy]

Skill Definition Follow-Up

I reread tbd guidelines cli-agent-skill-patterns and re-reviewed skills/simple-modern-uv/SKILL.md plus its reference files.

Overall, the skill definition looks clean and concise. It follows the important baseline practices: standard SKILL.md frontmatter, a two-part description that says what it does and when to use it, a short 147-line body well under the 500-line guidance, one-level-deep reference files, and pinned uvx copier@9.15.1 command examples. It also avoids the main “slopdocs” failure mode: it gives agents the essential workflow context without copying large amounts of Copier/help text into the activation body.

Additional suggestions:

1. [P3] Expand allowed-tools to match the commands the skill asks agents to run.
   skills/simple-modern-uv/SKILL.md:15 currently pre-grants uvx, uv, git, Read, Write, and Edit, but the body also tells agents to infer from gh auth status (SKILL.md:62-64) and verify with make lint / make test (SKILL.md:101, SKILL.md:140). If the target agent enforces or uses allowed-tools for pre-approval, this creates avoidable permission friction. Consider adding Bash(gh:*) and Bash(make:*), while still keeping the list tightly scoped.

2. [P3] Avoid a moving-branch fallback for reference files.
   SKILL.md:40-42 tells agents that if the skill was fetched from a URL, references live under .../main/skills/simple-modern-uv/references/<name>.md. That works for “always latest,” but it breaks the guideline’s “pin consumers to a commit or version, not a moving tag” advice: a user can fetch an older or tagged SKILL.md while the referenced docs silently come from newer main. Prefer wording that tells agents to fetch the reference files from the same ref as the SKILL.md, or publish raw-URL examples against a release tag once this ships.

3. [P3] Add explicit activation smoke cases to the release checklist.
   CI validates frontmatter and links, but the tbd skill guideline also calls out positive, negative, and explicit-invocation activation tests before publishing. The README already has three good positive prompts. Add a short checklist in updating.md or the spec for: new-project prompt activates this skill, existing-Poetry/migration prompt activates it, unrelated Python debugging prompt does not over-activate it, and explicit /simple-modern-uv or equivalent loads cleanly in the target agents.

I would not inline the reference files into the main skill body. The current progressive-disclosure split is the right shape; the changes above are mostly about tool pre-approval, version consistency, and activation testing.

[jlevy]

All four findings addressed in the latest push:

1. [P1] Setup sequence — sync now happens after the first commit in all three places (SKILL.md Workflow 1, README Option 2, and the copier next-steps message), with uv.lock committed second. Verified locally: the editable install now reports 0.0.1.dev1+<hash> instead of 0.0.0. CI's render job now follows the documented sequence and asserts the installed version is not 0.0.0, so this can't regress silently. The FAQ gained a uv sync --reinstall-package <module> recovery entry for stale metadata.

2. [P2] gh hook — both copies now check gh auth status first (any auth mechanism counts), only mention GH_TOKEN when auth actually fails, and the dead doc link is replaced with a gh auth login hint. Verified: reports "Authenticated successfully" here. Caveat: these are tbd-generated artifacts, so a future tbd setup --auto would regenerate them — porting the fix into get-tbd is tracked as bead smu (upstream follow-up) so the next tbd release ships it.

3. [P2] Pins — skills-ref@0.1.5 (Dec 2025, past cooloff) in CI, uvx copier@9.15.1 in the AGENTS.md example, and actions/checkout pinned to immutable v6.0.2 (Jan 2026; v6.0.3 is inside the 14-day window) in both this repo's and the template's workflows, matching the README's stated pin policy. updating.md examples updated accordingly.

4. [P3] README — the hand-edit license/publish paragraph is replaced with the answer-based flow (package_license/publish_to_pypi, copier update --data …), linking the skill's customize guide, with an explicit note to prefer re-answering over hand-deleting generated files.

https://claude.ai/code/session_01T3RGHgchJZBpvuiesrrE7X

---

Generated by Claude Code

[jlevy]

All three follow-ups landed: allowed-tools now includes Bash(make:*) and Bash(gh:*); the raw-URL note tells agents to fetch references from the same ref as the SKILL.md (no more main fallback that could drift from a pinned skill); and updating.md gained the four activation smoke checks (new-project and migration prompts activate, unrelated debugging prompt doesn't, explicit invocation loads) as a pre-release step for any skill change.

https://claude.ai/code/session_01T3RGHgchJZBpvuiesrrE7X

---

Generated by Claude Code