bazel-build-optimization

Overview of bazel-build-optimization skill

What the bazel-build-optimization skill does

The bazel-build-optimization skill helps an agent give structured, production-oriented guidance for making Bazel faster and more maintainable in large repositories. It is aimed at real build-system work: monorepo setup, remote cache or remote execution rollout, slow target analysis, flaky builds, dependency graph cleanup, and migration toward more scalable Bazel patterns.

Who should use it

This skill is best for platform engineers, build engineers, infra teams, and senior application developers working in Bazel-based codebases that are already large enough for build speed, cache hit rate, or rule design to matter. It is especially relevant if you need help with:

• reducing local and CI build times
• designing package boundaries
• configuring remote caching or execution
• choosing rule and target structure
• debugging slow incremental builds
• migrating a polyrepo or mixed toolchain setup into Bazel

The real job-to-be-done

Most users do not need a Bazel tutorial. They need an assistant that can look at a messy performance problem and turn it into concrete next steps: what to inspect, which files matter, what anti-patterns to remove, and how to trade speed against complexity. The bazel-build-optimization skill is useful when your prompt should produce architecture-aware optimization advice instead of generic “use caching” recommendations.

What makes it different from a generic build prompt

The differentiator is specificity around Bazel concepts and repo layout. The skill is grounded in Bazel primitives like WORKSPACE.bazel, BUILD.bazel, labels, packages, rules, and aspects, and it frames optimization work around the way Bazel actually evaluates and builds targets. That makes it more likely to produce actionable guidance for Performance Optimization than a broad prompt about CI speed.

Best-fit and misfit cases

Use bazel-build-optimization for Performance Optimization when you have an actual Bazel repository, a target performance problem, and enough context to share file structure, build commands, or symptoms.

Do not expect it to replace:

• official Bazel docs for exact rule syntax
• repo-specific build policies your org enforces
• low-level diagnosis when you provide no target names, configs, logs, or timing data

If your project is not using Bazel yet and you only want a generic tool comparison, this skill is probably too specialized.

How to Use bazel-build-optimization skill

Install context for bazel-build-optimization

Install the skill from the wshobson/agents repository in your skills-compatible environment. A practical install command is:

npx skills add https://github.com/wshobson/agents --skill bazel-build-optimization

After install, invoke it when you want Bazel-specific optimization help rather than a general coding assistant response.

Read this file first before prompting

Start with:

• plugins/developer-essentials/skills/bazel-build-optimization/SKILL.md

This skill ships mainly as a single instruction file, so there are no helper scripts or reference docs to hide important behavior. Reading SKILL.md first gives you the architecture model, target concepts, and example configuration patterns the agent will likely use in its reasoning.

What input the skill needs to work well

The bazel-build-optimization usage quality depends heavily on the inputs you provide. Give the agent:

• your Bazel version
• whether you use WORKSPACE.bazel and/or bzlmod
• a short repo layout
• one or more slow commands, such as bazel build //... or a specific target
• where the slowdown appears: analysis, fetch, compile, test, link, or remote execution
• whether CI and local builds behave differently
• relevant files like .bazelrc, root BUILD.bazel, and one representative package BUILD.bazel

Without that context, the agent can only return broad heuristics.

Turn a vague goal into a strong prompt

Weak prompt:

Help optimize our Bazel build.

Stronger prompt:

Use the bazel-build-optimization skill. We have a monorepo with apps/ and libs/, Bazel 7, remote cache enabled but poor cache hit rates in CI. Incremental builds are slow after changes in libs/utils. Review this .bazelrc, root BUILD.bazel, and libs/utils/BUILD.bazel. Identify likely dependency and target-graph issues, suggest a prioritized remediation plan, and show what to measure before and after.

The stronger version works because it gives the skill a topology, a symptom, a scope, and success criteria.

Ask for a diagnosis, not just recommendations

The best workflow is to ask the skill to first classify the problem, then propose fixes. For example:

1. identify likely bottleneck category
2. inspect package and target structure
3. recommend the smallest high-impact changes
4. define validation steps

This keeps the agent from jumping straight into speculative rule rewrites.

Practical prompt patterns that usually work

Use prompt patterns like:

• Audit these BUILD files for over-broad dependencies and target granularity issues.
• Propose a remote caching rollout checklist for this Bazel monorepo.
• Explain why this target likely invalidates too much of the graph.
• Compare current layout against a better package structure.
• Help migrate this repo to more scalable Bazel conventions without breaking CI.

These patterns align with the actual scope surfaced in the skill.

Repository files to share with the agent

For high-signal bazel-build-optimization install and usage success, the most useful files are:

• .bazelrc
• .bazelversion
• WORKSPACE.bazel
• root BUILD.bazel
• a few representative BUILD.bazel files in slow areas
• custom rule files under tools/bazel/rules/ or similar
• failing or slow command examples from CI logs

If you can only share one thing, share the slow command plus the BUILD files for the involved targets.

What outputs you should expect

A good bazel-build-optimization guide style response should give you:

• likely root causes, not only generic tips
• prioritized changes with rationale
• Bazel-specific terminology tied to your repo
• sample config or file edits where helpful
• a measurement plan to confirm improvement

If the response only says “enable cache” or “split modules” without relating that to your target graph, inputs were probably too thin.

Common workflows where this skill adds value

The skill is most useful in these workflows:

• monorepo adoption planning
• first remote cache or remote execution setup
• CI build-time reduction
• target and package refactoring
• custom rule design review
• migration from ad hoc scripts to Bazel-native structure

It is less valuable for one-off syntax questions, where the official docs may be faster.

Tradeoffs to decide before following advice

Optimization changes in Bazel often trade simplicity for speed. Ask the agent to call out tradeoffs such as:

• finer-grained targets vs maintenance overhead
• remote execution benefits vs infra complexity
• custom rules vs standard rule ecosystems
• aggressive caching vs reproducibility and debugging clarity

This is important because the skill can help you optimize, but you still need to choose the operational burden you are willing to carry.

bazel-build-optimization skill FAQ

Is bazel-build-optimization good for beginners?

Yes, if you already have a Bazel repo and need guided reasoning more than a full beginner course. The skill introduces core concepts like targets, packages, labels, and rules, but it is more useful for practical optimization than first-time Bazel learning from zero.

When should I use this instead of a normal prompt?

Use bazel-build-optimization when your problem involves Bazel architecture, build graph design, remote cache or execution, or monorepo scaling. A normal prompt can brainstorm ideas, but this skill is more likely to structure the answer around the files and concepts that actually control Bazel performance.

Does it help with remote caching and remote execution?

Yes. The source material explicitly covers configuring remote caching and remote execution as valid use cases. If that is your goal, include your current cache setup, CI behavior, auth model, and any cache hit or miss symptoms.

Can it help with Bazel migration?

Yes, especially for teams moving toward Bazel in a large codebase. The skill is useful for planning repository structure, package boundaries, dependency management, and build-performance considerations during migration.

Is this skill only for huge enterprise monorepos?

No, but that is its strongest fit. Smaller repos can still benefit if build graph design, target boundaries, or remote cache behavior matter. For a very small repo with only a few targets, the overhead of Bazel-specific optimization may outweigh the gain.

What does the skill not do well?

The skill does not ship with repo-specific automation, profiling scripts, or enforcement rules. It gives guidance and templates, but it will not automatically inspect your build system unless you provide files, commands, and symptoms.

How is this different from reading SKILL.md directly?

Reading SKILL.md gives you patterns and examples. Using the bazel-build-optimization skill through an agent becomes valuable when you want those patterns adapted to your repo, constraints, and performance problem instead of manually translating them yourself.

How to Improve bazel-build-optimization skill

Give the skill performance evidence, not just opinions

The fastest way to improve bazel-build-optimization usage is to supply evidence:

• slow commands
• timing deltas
• local vs CI differences
• cache hit-rate observations
• representative BUILD files

This lets the agent reason from actual symptoms instead of repeating common Bazel best practices.

Scope the problem to one target path first

Do not start with //... unless the issue is truly global. Better prompt quality comes from one slow package, one flaky test target, or one problematic dependency area. Once the agent helps on a focused case, expand the same pattern repo-wide.

Ask for prioritized fixes with expected impact

A strong improvement prompt is:

Use the bazel-build-optimization skill and rank the top 5 changes by likely impact, implementation cost, and risk. Include how each change should affect analysis time, cacheability, or incremental rebuild behavior.

That forces decision-ready output instead of an unranked checklist.

Share real file contents, not paraphrases

Paste actual .bazelrc, WORKSPACE.bazel, and BUILD.bazel snippets when possible. Small syntax and structure details can completely change Bazel behavior. Paraphrased summaries usually hide the exact issue.

Request before-and-after validation steps

To improve trust in the output, ask the skill to include:

• what to measure before changes
• what to change first
• what success looks like after each step
• what rollback signs to watch for

This turns advice into an optimization loop instead of a one-shot suggestion list.

Watch for common failure modes

The most common reasons the skill underperforms are:

• no target names or commands provided
• no distinction between local and CI problems
• asking for “best practices” without a concrete bottleneck
• hiding custom rules or macros that shape the build graph
• expecting exact syntax without sharing current config

If the answer feels generic, the prompt was likely too abstract.

Iterate after the first answer

After the initial response, come back with one of these:

• Here is the current BUILD file after change 1. What remains problematic?
• Cache hit rates improved locally but not in CI. Reassess likely causes.
• We cannot use remote execution. Re-rank the optimization plan.

This second pass is where the bazel-build-optimization for Performance Optimization value usually becomes much more concrete.

Ask the skill to explain tradeoffs in your environment

If your team cares about developer experience, CI cost, or migration risk, say so explicitly. The best way to improve the bazel-build-optimization skill output is to make the optimization objective clear: fastest CI, fastest local iteration, easiest maintenance, or safest migration. Different goals lead to different recommendations.