How do I install the Therock First Build With Commit skill?

Run npx skillmds@latest add rocm/therock-first-build-with-commit in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Therock First Build With Commit skill do?

Find the first TheRock nightly build that includes a given rocm-systems commit It is listed under Coding & Dev Tools on SkillMD.

Is Therock First Build With Commit safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Therock First Build With Commit?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Therock First Build With Commit free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Therock First Build With Commit?

rocm (@rocm) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Therock First Build With Commit by rocm

Name: Therock First Build With Commit
Author: rocm

Find the First TheRock Nightly Build to Include a Commit

Walks scheduled runs of the Multi-Arch Release workflow on ROCm/rockrel (workflow id 265449761 — the workflow that currently publishes nightly manifests to S3) in chronological order, starting at (or just before) the commit's date, and reports the first build whose rocm-systems pin_sha is a descendant of (or equal to) the user's commit — i.e. the commit is an ancestor of the build's pin_sha.

Legacy: Before mid-June 2026, nightlies used Release portable Linux packages on ROCm/TheRock (workflow id 161312296, now deleted). For commits first shipped in that era, pass --legacy (equivalent to --workflow-repo ROCm/TheRock --workflow 161312296). The default rockrel walk may report a later run as "first" if the commit actually shipped in an earlier TheRock nightly.

Backed by an executable helper script: find_first_build.py.

When to Use

Use this skill when:

User asks "what is the first nightly build to include commit <sha>?"
User asks "has my fix shipped yet, and if so where can I grab it?"
Bisecting which nightly first contained a regression
Verifying a PR landed in a downstream consumer (a TheRock-based image, package, or wheel)

Unless the user says otherwise, this skill targets the rocm-systems submodule on ROCm/rocm-systems.

Inputs

Flag	Required	Default	Notes
`--commit SHA`	yes	-	Full 40-char SHA preferred (>= 7 chars); must be visible on `--repo`
`--repo OWNER/REPO`	no	`ROCm/rocm-systems`	The repo that hosts the commit
`--submodule NAME`	no	`rocm-systems`	Submodule name in `therock_manifest.json`
`--gpu-family FAMILY`	no	`gfx94X-dcgpu`	Legacy only — fallback path for older builds with per-GPU-family manifests
`--legacy`	no	off	Walk `ROCm/TheRock` workflow `161312296` instead of current `ROCm/rockrel` / `265449761`
`--workflow-repo OWNER/REPO`	no	`ROCm/rockrel`	Override repo hosting the nightly workflow (`ROCm/TheRock` with `--legacy`)
`--workflow ID`	no	`265449761`	Override workflow id (`161312296` with `--legacy`)
`--since YYYY-MM-DD`	no	commit date minus 1 day	Lower bound for the run listing
`--max-runs N`	no	`90`	Caps the linear walk (Actions retention is ~90 days)
`--json`	no	off	Emit final result as JSON on stdout (per-iteration progress still goes to stderr)

Prerequisites

gh CLI installed and authenticated against github.com (see skills/git-gh-client/SKILL.md for setup).
python3 >= 3.8 (standard library only; no pip install needed).
Outbound HTTPS to github.com and therock-nightly-artifacts.s3.amazonaws.com.

Quick sanity check:

gh auth status
python3 --version

Process

The skill is a thin wrapper around the bundled script. The agent's job is to:

Confirm prerequisites.
Determine the SKILL directory (the folder containing this SKILL.md); call it SKILL_DIR. Typically ~/.claude/skills/therock-first-build-with-commit/.

Invoke the script with the user's commit:

python3 "$SKILL_DIR/find_first_build.py" --commit <SHA>

Stream the per-iteration progress (stderr) to the user as it runs. When done, present the final result (stdout) verbatim — it is already a bullet list; do not reformat it into a table or prose.
If the user wants to pipe the result into other tooling, add --json:
```
python3 "$SKILL_DIR/find_first_build.py" --commit <SHA> --json
```

Resolving non-SHA inputs

If the user provides a PR URL/number instead of a SHA, resolve it first:

gh api repos/ROCm/rocm-systems/pulls/<PR_NUMBER> \
  --jq '{merged, merge_commit_sha, head_sha, base_ref: .base.ref}'

Use merge_commit_sha (the commit that landed on the base branch) - not head_sha (the tip of the PR branch before merge). Then pass merge_commit_sha to --commit.

Examples

Example 1: Recent commit — first rockrel nightly

SKILL_DIR=~/.claude/skills/therock-first-build-with-commit
python3 "$SKILL_DIR/find_first_build.py" \
  --commit d22352b782e728115786965046088fc4a71341fb

Sample stderr (progress):

Resolving commit d22352b782e728115786965046088fc4a71341fb on ROCm/rocm-systems...
  committed: 2026-06-19T17:02:00+00:00
Listing scheduled runs of ROCm/rockrel workflow 265449761 since 2026-06-18 (max 90)...
Inspecting 9 runs in chronological order.
[  1/9] run=27728528519 created=2026-06-18T00:25:59Z pin=7ced1a66 status=behind    ahead_by=0 behind_by=205
[  2/9] run=27797822902 created=2026-06-19T00:29:01Z pin=7ced1a66 status=behind    ahead_by=0 behind_by=205
[  3/9] run=27854481844 created=2026-06-20T00:21:36Z pin=a0952b2b status=behind    ahead_by=0 behind_by=30
[  6/9] run=27993312669 created=2026-06-23T00:22:14Z pin=971dc690 status=ahead     ahead_by=34 behind_by=0  FOUND

Sample stdout (final result):

Commit d22352b7 first shipped in the 2026-06-23 nightly.

First nightly build to include d22352b782e728115786965046088fc4a71341fb:
  - run_id: 27993312669 (created 2026-06-23T00:22:14Z)
  - pin_sha: 971dc6904568e810f00473760000939deaf30e84 (34 commits ahead)
  - the_rock_commit: 86af3706e7bf2e43f673dbf2f9038e226ede3af7
  - Repo snapshot: https://github.com/ROCm/rocm-systems/tree/971dc6904568e810f00473760000939deaf30e84
  - GitHub Actions: https://github.com/ROCm/rockrel/actions/runs/27993312669
  - Compare: https://github.com/ROCm/rocm-systems/compare/d22352b782e728115786965046088fc4a71341fb...971dc6904568e810f00473760000939deaf30e84
  - Manifest: https://therock-nightly-artifacts.s3.amazonaws.com/27993312669-linux/manifests/therock_manifest.json
  - Packages (deb): https://rocm.nightlies.amd.com/packages-multi-arch/deb/20260623-27993312669/index.html
  - Tarball: https://rocm.nightlies.amd.com/tarball-multi-arch/therock-dist-linux-multiarch-7.14.0a20260623.tar.gz

Example 1b: Pre-migration commit — use `--legacy`

For commits first shipped before the rockrel migration (~2026-06-12), walk the deleted TheRock workflow:

python3 "$SKILL_DIR/find_first_build.py" \
  --commit 570dcd3205005305b32b50996be1d7154d399c4a \
  --legacy

Legacy run URLs use https://github.com/ROCm/TheRock/actions/runs/<RUN_ID> and per-GPU-family manifest paths.

Example 2: Commit hasn't shipped yet

python3 "$SKILL_DIR/find_first_build.py" --commit <fresh_sha>

Final stdout:

No nightly build in the inspected window contains <fresh_sha>.
  Inspected runs: 1 (since 2026-06-03)
  The commit may still ship in a later nightly; rerun later or widen --max-runs / --since.

Exit code is 5 (no match). Suggest the user rerun in a day, or widen the window if their commit is older.

Example 3: Old commit - widen the search window

python3 "$SKILL_DIR/find_first_build.py" \
  --commit <old_sha> \
  --since 2026-03-01 \
  --max-runs 90

Example 4: JSON output for piping

python3 "$SKILL_DIR/find_first_build.py" --commit <sha> --json \
  | jq '.first_build.run_id // empty'

Example 5: PR -> first build (compose with `gh`)

PR=6445
COMMIT=$(gh api repos/ROCm/rocm-systems/pulls/$PR --jq .merge_commit_sha)
python3 "$SKILL_DIR/find_first_build.py" --commit "$COMMIT"

Output

This skill produces:

Per-iteration progress on stderr (one line per nightly run, with status and ahead/behind counts).
Final result on stdout - either a human-readable bullet list (default) or a JSON object (--json).
Exit codes: 0 found, 3 invalid input, 4 upstream/network failure, 5 exhausted window without finding. (5 rather than 2 so callers can distinguish "no match" from Python's argparse default of 2.)

No files are written.

Common Mistakes

Mistake	Fix
Passing a PR number instead of a SHA	Resolve via `gh api repos/.../pulls/<N> --jq .merge_commit_sha` first
Passing the PR's `head_sha` instead of `merge_commit_sha`	The head SHA may not exist on the base branch (especially after squash); always use `merge_commit_sha`
Setting `--since` after the commit's committer date	The walk would skip the very window where the fix could appear; if unsure, omit `--since` and let the default handle it
Assuming `pin_sha` varies by architecture	It does not — multi-arch nightlies publish one manifest; `pin_sha` is the same everywhere
Treating exit code `5` as a script failure	Exit code `5` means "no nightly in the window contains the commit yet" - rerun later or widen `--max-runs` / `--since`. (Note: argparse uses exit `2` for CLI errors like missing `--commit`, so `5` lets callers distinguish "no match" from "bad invocation".)
Reading from stdout while the script is still running	Per-iteration progress goes to stderr; redirect appropriately (`2>progress.log` or just observe both)

Troubleshooting

Many `manifest=missing (skipped)` lines

Cause: not every workflow run publishes artifacts. Failed, cancelled, or in-progress runs typically have no manifest. The script skips them and continues.

If all runs are skipped, verify manifest availability against one known-good build using therock-build-to-commit:

curl -fsSL https://therock-nightly-artifacts.s3.amazonaws.com/<RUN_ID>-linux/manifests/therock_manifest.json | head -c 200

For legacy builds, fall back to .../manifests/gfx94X-dcgpu/therock_manifest.json.

`gh` rate-limit errors

Cause: anonymous rate limit hit, or token scope too narrow.

Steps:

Confirm a personal token is configured: gh auth status.
For ephemeral environments, export GH_TOKEN=<your_pat> before invoking the script.
Reduce --max-runs to limit API calls.

`error: could not resolve commit <sha> on ROCm/rocm-systems`

Cause: the SHA is on a private fork or not pushed to upstream.

Steps:

Verify visibility: gh api repos/ROCm/rocm-systems/commits/<sha> --jq .sha.
If the SHA is fork-only, ask the user to push to upstream or rebase the work onto an upstream-visible base.

Script reports `status=null`

Cause: GitHub returns extra states for very large diffs.

The script logs ahead_by/behind_by either way. Use that as the source of truth: behind_by == 0 -> commit is an ancestor (included).

Integration with Other Skills

Relationship	Skill	Why
Calls	git-gh-client	For `gh` availability and authentication setup
Sibling	therock-build-to-commit	Reverse direction: given a build, what's the pinned commit?
Sibling	therock-commit-in-build	Single-build spot check (you already know which build to look at)

Decision matrix:

User asks...	Use
"What commit is in build X?"	`therock-build-to-commit`
"Is commit Y in build X?"	`therock-commit-in-build`
"What's the first build containing commit Y?"	this skill

Notes

This is the first skill in this repository to ship an executable helper script. The rationale: this lookup has multiple knobs (--commit, --repo, --submodule, --legacy, --workflow, --workflow-repo, --since, --max-runs, --json), needs structured per-iteration progress, and is most useful when reusable from a shell prompt or CI - not just from inside an agent session.
Standard library only; no pip install required.
Bounded by GitHub Actions' default 90-day retention - older commits may not be locatable via this method even if they did ship.
Source recipe: Wiki - Helpful Links and Information, TheRock Nightly Builds section.

Therock First Build With Commit

File contents

Find the First TheRock Nightly Build to Include a Commit

When to Use

Inputs

Prerequisites

Process

Resolving non-SHA inputs

Examples

Example 1: Recent commit — first rockrel nightly

Example 1b: Pre-migration commit — use `--legacy`

Example 2: Commit hasn't shipped yet

Example 3: Old commit - widen the search window

Example 4: JSON output for piping

Example 5: PR -> first build (compose with `gh`)

Output

Common Mistakes

Troubleshooting

Many `manifest=missing (skipped)` lines

`gh` rate-limit errors

`error: could not resolve commit <sha> on ROCm/rocm-systems`

Script reports `status=null`

Integration with Other Skills

Notes

Frequently asked questions

Therock First Build With Commit

File contents

Find the First TheRock Nightly Build to Include a Commit

When to Use

Inputs

Prerequisites

Process

Resolving non-SHA inputs

Examples

Example 1: Recent commit — first rockrel nightly

Example 1b: Pre-migration commit — use --legacy

Example 2: Commit hasn't shipped yet

Example 3: Old commit - widen the search window

Example 4: JSON output for piping

Example 5: PR -> first build (compose with gh)

Output

Common Mistakes

Troubleshooting

Many manifest=missing (skipped) lines

gh rate-limit errors

error: could not resolve commit <sha> on ROCm/rocm-systems

Script reports status=null

Integration with Other Skills

Notes

Related skills

Frequently asked questions

How do I install the Therock First Build With Commit skill?

What does the Therock First Build With Commit skill do?

Is Therock First Build With Commit safe to use?

Which AI agents work with Therock First Build With Commit?

Is Therock First Build With Commit free to use?

Who published Therock First Build With Commit?

Example 1b: Pre-migration commit — use `--legacy`

Example 5: PR -> first build (compose with `gh`)

Many `manifest=missing (skipped)` lines

`gh` rate-limit errors

`error: could not resolve commit <sha> on ROCm/rocm-systems`

Script reports `status=null`