android-update-deps

An Agent Skill for the safe, gated review and update of dependencies in an Android (Kotlin/Gradle) project that uses a Gradle version catalog. One SKILL.md folder that works with Claude Code, OpenAI Codex, Gemini CLI, and any Agent-Skills-compatible tool.

Upgrading dependencies is easy to get wrong: automated bumpers jump every library to its latest version with zero analysis, silently breaking your build or your app. This skill does the opposite — it turns "update my dependencies" into a controlled, reviewable procedure that detects what's outdated, reasons about the risk, and never changes anything without your explicit confirmation.

It's designed for real Android projects: version catalogs (gradle/libs.versions.toml), the Android Gradle Plugin, Compose/Firebase BOMs, coupled version blocks (Kotlin ↔ KSP ↔ Compose Compiler), JitPack libraries, and convention plugins (build-logic/).

Why use it

• Gated by design. It detects, groups, classifies by risk, and stops at a proposal for you to approve — all / safe-only / a specific subset. Nothing is edited or committed until you say go.
• Sees the whole picture, not just version numbers. It groups coupled blocks and BOM-governed artifacts into single items, ignores transitive noise, and flags hidden requirements (a "safe-looking" minor that actually needs a higher compileSdk/AGP/Kotlin).
• Covers the tool's blind spot. The ben-manes gradle-versions-plugin can't see JitPack (com.github.*) libraries — the skill checks those by hand.
• Verifies before it trusts. Applied bumps are built with :app:assembleDebug; if something breaks, it isolates the culprit, reverts it, and returns to the proposal — never leaving your tree broken.
• Clean git hygiene. Commits locally on a feature branch (never the default branch, no push), one thematic commit per theme, with a separate commit for any code adaptation to new APIs.
• Speaks your language. User-facing prose mirrors the language you write in (English or Spanish).

What it handles

Concern	Behavior
Version catalog	Edits gradle/libs.versions.toml version.refs — the single source of truth
Detection	./gradlew dependencyUpdates --no-parallel (ben-manes), aggregated across all modules
JitPack (com.github.*)	Checked manually via JitPack metadata / GitHub releases (plugin blind spot)
BOMs (Compose, Firebase, …)	Bumps only the BOM; ignores the governed child artifacts in the report
Coupled blocks	Kotlin ↔ KSP ↔ Compose Compiler, AGP ↔ Gradle wrapper, Retrofit, OkHttp, Room, Hilt… treated as single items
Risk	Semver magnitude + hidden compileSdk/AGP/Kotlin requirements + known vulnerabilities + license changes
Verification	:app:assembleDebug (plus tests/linters when relevant); isolates any culprit bump
Code adaptation	Post-bump deprecation/migration pass, in a separate refactor(deps) commit

How it works

A fixed, repeatable procedure (the skill stops at step 5 for your approval):

1. Discover the project shape — catalog, detection tool, JitPack libs, coupled blocks, SDK/JDK/wrapper.
2. Detect updates with the ben-manes plugin (+ a manual JitPack pass).
3. Aggregate & dedupe the per-module reports (helper script included).
4. Filter noise — drop BOM-governed children and transitive satellites; group coupled blocks.
5. Classify by risk and propose a table (safe vs. handle-with-care) — ⛔ GATE: waits for you.
6. Apply only what you confirmed.
7. Verify with a build; isolate and revert any culprit.
8. Commit locally on a branch, one thematic chore(deps) commit, no push.
9. Adapt the code to new APIs if needed — separate refactor(deps) commit.

Installation

Agent Skills are an open format — the same SKILL.md folder works across compatible agents. Install it wherever your agent looks for skills.

Any agent — universal .agents/skills/

Codex, Gemini CLI, VS Code and others scan a shared skills directory. Clone the repo there:

# user-level (all your projects)
git clone https://github.com/alvarose/android-update-deps.git ~/.agents/skills/android-update-deps

# or project-scoped
git clone https://github.com/alvarose/android-update-deps.git .agents/skills/android-update-deps

Gemini CLI

gemini skills install https://github.com/alvarose/android-update-deps --consent

OpenAI Codex

Place the folder in ~/.agents/skills/android-update-deps/ (or a repo .agents/skills/), then mention it in chat with $skills.

Claude Code

Install as a plugin (one command), then update with /plugin update android-update-deps@alvarose:

/plugin marketplace add alvarose/android-update-deps
/plugin install android-update-deps@alvarose

…or clone into a directory Claude scans for skills:

git clone https://github.com/alvarose/android-update-deps.git ~/.claude/skills/android-update-deps

Or download the packaged android-update-deps.skill from the Releases page.

Usage

Once installed, just ask your agent in an Android project — the skill triggers on phrases like:

• "review / update / bump the dependencies of my Android app"
• "what's outdated in my libs.versions.toml?"
• "actualiza las dependencias, solo las seguras"
• or invoke it by name (e.g. /android-update-deps in Claude Code, $skills in Codex, /skills in Gemini CLI)

The agent will detect, analyze, and show you a risk-grouped proposal. You pick what to apply; it verifies with a build and commits on a branch. It won't touch anything without your OK.

Requirements

• An Android (Kotlin/Gradle) project, ideally with a version catalog (gradle/libs.versions.toml).
• The ben-manes gradle-versions-plugin applied (the skill offers to add it temporarily if it's missing). On Gradle 9+ use 0.52.0+.
• A working Android SDK (sdk.dir in the repo's local.properties).

Repository layout

android-update-deps/
├── SKILL.md          # the skill: discovery, the 9-step gated procedure
├── references/
│   └── reference.md  # coupled-versions table, JitPack procedure, report.json format
├── scripts/
│   └── aggregate-updates.py   # dedupe report.json across modules; list JitPack libs
├── .claude-plugin/   # Claude-specific plugin + marketplace manifests (for /plugin install)
├── evals/            # evaluation prompts + assertions used to test the skill
├── CHANGELOG.md
├── LICENSE
└── README.md

Contributing

Issues and PRs welcome. The skill is intentionally concise and gated — proposals that add scope should preserve those principles (see the "handle with care" philosophy in SKILL.md).

License

MIT © Alvaro Serrano