Dependency Refresh Playbook
A disciplined, safety-first playbook for running the monthly dependency and version refresh across Python lockfiles, Actions, uv CLI, base images, and infra images in agent-service-toolkit.
The project's own dependency-upgrade workflow (requires reading the full playbook before touching any pin, no improvising) — for this project's maintainer.
What does this skill do, and when should you use it?
dependency-refresh is a self-contained operational skill inside the agent-service-toolkit repository, providing a complete playbook for dependency refreshes. It goes beyond bumping Python packages in pyproject.toml/uv.lock: it also covers Docker base images, GitHub Actions pins, the uv CLI version (synced in four places), the supported Python range, and the postgres/mongo/LangFuse infra images used by compose and smoke tests. Two cooldown layers are built in: a global 14-day resolver cooldown enforced by uv's exclude-newer, and a three-month major cooldown for key dependencies. Each refresh produces exactly one PR whose body doubles as the state record for the next round. A references directory captures version-coupling constraints and the live end-to-end verification recipe.
Step 0 searches for the most recent refresh PR to recover the deferred-majors table and verification caveats; it then surveys all candidates against the PyPI API plus non-Python surfaces (Actions pins, uv CLI, base images, infra tags). Each candidate is triaged against both cooldowns; safe bumps are applied by editing pins in pyproject.toml; uv lock --upgrade re-resolves and pins are reconciled to the lock. Verification runs uv sync --frozen, ruff check, ruff format --check, pyrefly check, and pytest, followed by the live e2e recipe (fake-model HTTP ladder, Streamlit browser smoke) and relevant scripts/smoke_test.sh targets when checkpointers, AG-UI, or LangFuse moved. The round ends with one PR using the fixed branch name, title, and a body template with 'What moved', 'Deferred majors & cooldowns', and 'Verification' sections.
- A solo maintainer of a LangGraph/FastAPI/Streamlit project who wants regular, non-risky dependency upgrades
- A maintainer responding to a Dependabot security advisory who needs the sanctioned cooldown override for an immediate fix
- Teams hitting resolver conflicts when coupled packages like langchain and langgraph must move in lockstep
- Operators who must wait before adopting postgres/mongo image majors that can change on-disk formats
- AI maintenance-agent workflows that need every refresh traceable in a PR (what moved, what was deferred, verification results)
- Projects needing to keep the Python support range, CI matrix, ruff target-version, and Docker base images mutually consistent
What are this skill's strengths and limitations?
- Fully self-contained playbook covering state recovery through PR submission
- Two cooldown layers (uv-enforced 14-day + process-enforced 3-month major cooldown) sharply reduce the risk of adopting broken or compromised fresh releases
- PR-as-state-record convention makes every round traceable, with the deferred-majors table carried forward automatically
- references/coupling-constraints.md encodes real-world gotchas (langchain⇄langgraph lockstep, checkpointer majors, uv quirks)
- A clearly defined, single sanctioned security override with a commented temporary setting removed next round
- Deeply tied to agent-service-toolkit's file layout (uv.lock, compose.yaml, scripts/smoke_test.sh); substantial rework needed for other repos
- Process rules (3-month cooldown, PR template) rely on the model following them, with no mechanical enforcement
- Smoke tests require a Docker daemon, and the LangFuse target is explicitly heavyweight (full self-host stack)
- Running state lives in past PR descriptions rather than files, so recovery depends on PR search succeeding
How do you install this skill?
This skill is one of 4 bundled in JoshuaC215/agent-service-toolkit, at .claude/skills/dependency-refresh/. Place the skill folder (SKILL.md plus references/coupling-constraints.md and references/live-e2e.md) into your project's .claude/skills/ directory for Claude Code. The repository README documents installation of the whole collection; standalone installation steps for just this skill are not documented in the source.
How do you use this skill?
In a repo with the skill installed, ask Claude to "update dependencies", "bump versions", or "do a dependency refresh", or wait for the scheduled monthly run. The skill executes its steps automatically: recover the last PR's state, survey, triage, apply safe bumps, re-lock, run static checks, run live verification, and produce the formatted refresh PR. Note the playbook is written for agent-service-toolkit's specific structure — references contain project-specific coupling constraints, so porting to another repo requires adaptation.
How does this skill compare with similar options?
Compared with simply running uv lock --upgrade or auto-merging Dependabot PRs, this skill adds cooldown policies, key-dependency major deferral, cross-surface syncing (Actions/uv CLI/images), and a traceable PR-based state record — at the cost of being heavier, slower, and coupled to one repository's structure.