ask-bazel - SKILL.md Agent Skill

name: ask-bazel description: Research and answer Bazel questions by reading the Bazel source tree, commit history, and GitHub context (Issues, PRs, Discussions). Use when the user asks how Bazel works, why behavior changed, when a feature/regression appeared, or asks version-specific Bazel questions tied to bazelbuild/bazel.

Ask Bazel

Goal

Answer Bazel questions using evidence from code, history, and community context.

Workspace Selection

Use ${BAZEL_REPO:-$HOME/work/bazelbuild/bazel} as the primary repository.

Set repo="${BAZEL_REPO:-$HOME/work/bazelbuild/bazel}" before running git commands below.

Detect whether the user gave a Bazel version/ref (tag, branch, commit SHA, release name).

When no version/ref is provided, stay on the current checkout and research directly.

When a version/ref is provided, follow this exact flow:

Check repository cleanliness.

git -C "$repo" status --porcelain

If clean, resolve and checkout that version/ref in place.
If dirty, create a local clone first and use the clone for all versioned research.

tmp_repo="$(mktemp -d "$(dirname "$repo")/bazel-codex-XXXX")"
git clone --no-hardlinks "$repo" "$tmp_repo"
repo="$tmp_repo"

Verify the ref exists locally.

git -C "$repo" rev-parse --verify "${ref}^{commit}"

If not found, fetch from GitHub and re-check.

git -C "$repo" fetch https://github.com/bazelbuild/bazel.git --tags --prune
git -C "$repo" rev-parse --verify "${ref}^{commit}"

If still not found, report that the version/ref could not be resolved.
If found, checkout detached at the exact commit.

git -C "$repo" checkout --detach "${ref}^{commit}"

Always report the exact commit hash and repo path used for research.

Research Workflow

Read relevant source, tests, and docs in the selected repo.
Use fast code search first (rg, git grep) to find symbols, flags, errors, or behavior. Before opening a file with sed or narrowing history to a path, confirm the path in the checked-out ref with rg --files, git grep -l, or similar when the exact location is not already known. Bazel moves files across packages often enough that guessed paths are a common source of wasted turns.
Investigate history with pickaxe and regex diffs:

git -C "$repo" log -p -S'needle' -- path/to/area
git -C "$repo" log -p -G'regex' -- path/to/area

Review commit messages for rationale and links to issues/PRs.
Use gh to gather community and maintainer context:

gh issue list --repo bazelbuild/bazel --search "terms" --limit 20
gh issue view <number> --repo bazelbuild/bazel --comments
gh pr list --repo bazelbuild/bazel --search "terms" --limit 20
gh pr view <number> --repo bazelbuild/bazel --comments

For Discussions, query GraphQL via gh api graphql against bazelbuild/bazel and search titles/bodies for the topic.

Parallelization

Spawn subagents when useful:

One agent for local code understanding.
One agent for commit-history and pickaxe analysis.
One agent for GitHub Issues/PRs/Discussions.

Merge findings only after verifying they agree on key facts (version, behavior, timeline).

Response Requirements

Return concise, evidence-backed answers.

Include:

Exact repo path and commit hash researched.
Key code references (file paths and symbols).
Relevant commits with short rationale from messages/diffs.
Relevant Issue/PR/Discussion links and what they add.
Explicit uncertainty when evidence is incomplete or conflicting.