agentleFS
vintavinta/hal-9000/.claude/skills/upgrade-playbooks/SKILL.md

upgrade-playbooks

Skill143 starsChanged 27 days agoMITView on GitHub

(project) Use when upgrading install tasks in playbooks/roles/ against upstream docs — bumping a pinned version, adopting a newly recommended install method, repointing a doc link that moved, or realigning the community.general pin with the brew-installed ansible and CI's ansible-lint action with uv.lock

  • Installs packages

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep each task's install method, and note each tool whose page recommends a different macOS method for §7.

    line 50
  2. Very specific:

    When that version differs from the action's tag comment, resolve the tag to its commit and repin uses: ansible/ansible-lint@<sha> # …

    line 70
  3. Very specific:

    Run make lint. Then create one commit per tool with the commit skill, passing what moved, e.g.

    line 78

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Update Playbooks

Close the drift between each install task in playbooks/roles/*/tasks/main.yml and the upstream docs it cites, then commit per tool.

Drift takes three forms, and all three are read off the same page — the # comment URL above the task:

  • Version drift — the pin trails the newest release of its release line.
  • Method drift — upstream now recommends a different way to install.
  • Link drift — the doc URL itself moved.

A release line is the version prefix a project treats as a stable series: Node 24.x, Python 3.14.x, kubectl 1.35.x. Every bump stays inside the line (24.15.0 -> 24.18.0 is in-line for Node because Node's line is the major). When a newer line exists (Node 26, Python 3.15, kubectl 1.36), keep the pin on its current line and report the newer line in the final summary so the user can decide.

Two pins live outside the roles and answer to a different source of truth — playbooks/collections/requirements.yml, covered in §4, and CI's ansible-lint action, covered in §5.

1. Scan

grep -rn -E '^# https?://|^- name:' playbooks/roles/*/tasks/main.yml

Adjacent line numbers pair each URL with the task it documents. Done when every install task is listed with its role, its doc URL, and any version pinned in its name, command body, or download URL.

2. Read the upstream docs

Fetch each doc URL once and take all three answers off that one page:

  • newest tag inside the release line — gh api repos/OWNER/REPO/releases --jq '.[].tag_name' for a github.com/OWNER/REPO link, WebFetch otherwise.
  • the install commands the page currently recommends for macOS — quote them verbatim, including which method the page calls recommended when it ranks them.
  • where the URL lands — curl -sIL -o /dev/null -w '%{http_code} %{url_effective}\n' URL.

Done when every task has today's version, install commands, and final URL confirmed from its page. Anything recalled from training data is stale by definition.

3. Edit

Apply version and link drift, matching the surrounding task style:

  • Version — replace the old version at every occurrence in the role: the task name:, each command line, and any URL. Done when grepping the file for the old version returns nothing.
  • Link — repoint the # comment at the URL that resolved.

Keep each task's install method, and note each tool whose page recommends a different macOS method for §7. A page that ranks nothing recommends every method it lists, so note a tool only when its task's method is no longer among them.

4. Match the collection pin to brew's ansible

playbooks/collections/requirements.yml pins community.general, the collection supplying the homebrew, homebrew_tap, and homebrew_cask modules the roles install through. Upstream releases do not drive this pin — the brew-installed ansible does. Locally, ansible-playbook and make lint both load the copy brew bundles; only CI, which has no brew, installs the pin. So a pin that disagrees with brew means CI validates different module code than ansible-playbook executes here, silently.

ansible-galaxy collection list community.general

When they differ, set the pin to brew's version. Never the reverse, and never to the newest release on Galaxy — a pin ahead of brew drifts from what runs here just as badly as one behind it. Editing the pin is all it takes: CI installs it on its next run.

5. Match CI's ansible-lint to uv.lock

.github/workflows/validate-playbooks.yml runs the ansible/ansible-lint action, pinned to a commit SHA with its tag in a trailing comment. Upstream releases do not drive this pin either — uv.lock does, since it holds the ansible-lint make lint runs, and CI should lint with the same version.

grep -A1 '^name = "ansible-lint"' uv.lock

When that version differs from the action's tag comment, resolve the tag to its commit and repin uses: ansible/ansible-lint@<sha> # v<version>. Never the reverse: bumping uv.lock is not this skill's job.

gh api repos/ansible/ansible-lint/commits/v<version> --jq .sha

6. Verify and commit

Run make lint. Then create one commit per tool with the commit skill, passing what moved, e.g. bump kubectl to v1.35.7. A collection pin bump and an action repin are each their own commit, separate from any role.

7. Offer method switches

Once §6's commits are made, ask the user with AskUserQuestion in Claude Code or request_user_input in Codex whether to switch each tool noted in §3, one question per tool, up to four per call in Claude Code and three in Codex. Each question offers keeping the current method and switching to the page's recommended one, quoting the recommended commands in that option's preview; when the switch would cost something the task has, such as a version pin Homebrew cannot hold or a script's self-update, say so in the option's description.

For each yes, adopt the upstream commands; a script install points its creates: guard at the binary the script produces. A Homebrew install uses the homebrew module at state: latest, which also replaces any separate upgrade task, as fnm and bun show; a formula from the project's own tap takes a homebrew_tap task above it. Then run make lint and commit each switched tool as in §6.

Close with a summary: what changed per tool, which tools were already current, which method switches the user declined, and any newer release lines waiting on the user.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.