compare-builds
Compares two Xcode build runs to identify duration regressions, cache changes, and new issues. Can be invoked with build IDs, dashboard URLs, or branch names (e.g. tuist compare-builds --base main --head feature-branch).
- Installs
- 300
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/tuist/agent-skills --skill compare-builds- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads compare-builds automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Compare Builds
Quick Start
You'll typically receive two build identifiers (IDs, dashboard URLs, or branch names). Follow these steps:
- Run
tuist build list --jsonto find builds on each branch. - Run
tuist build show <build-id> --jsonfor both base and head builds. - Fetch sub-resource details: targets (
tuist build xcode target list <id> --json), issues (tuist build xcode issue list <id> --json), and cache tasks (tuist build xcode cache-task list <id> --json). - Compare duration, status, cache hit rates, and other metrics.
- Summarize regressions, improvements, and recommendations.
If only one identifier is provided, use the project's default branch as the baseline.
Step 1: Resolve Builds
If base/head are build IDs or dashboard URLs
Fetch each directly:
tuist build show <base-id> --json
tuist build show <head-id> --json
If base/head are branch names
List recent builds on each branch and pick the latest:
tuist build list --git-branch <base-branch> --json --page-size 1
tuist build list --git-branch <head-branch> --json --page-size 1
Then fetch full details with tuist build show <id> --json.
Defaults
- If no base is provided, use the project's default branch (usually
main). - If no head is provided, detect the current git branch with
git rev-parse --abbrev-ref HEAD.
Step 2: Fetch Sub-Resource Details
After fetching both builds with tuist build show <id> --json, drill down into sub-resources for a deeper comparison.
Compare targets
tuist build xcode target list <base-id> --json
tuist build xcode target list <head-id> --json
Look for targets that changed status (e.g., success to failure) or had significant duration changes.
Compare issues
tuist build xcode issue list <base-id> --json
tuist build xcode issue list <head-id> --json
Look for new warnings or errors introduced in the head build.
Compare cache tasks
tuist build xcode cache-task list <base-id> --json
tuist build xcode cache-task list <head-id> --json
Identify which specific targets had cache misses or hits and whether that changed between builds.
Step 3: Compare Top-Level Metrics
After fetching both builds, compare:
| Metric | What to check |
|---|---|
duration | Flag if head is >10% slower than base |
status | Flag if base succeeded but head failed |
cacheable_tasks_count | Note if task count changed |
cacheable_task_local_hits_count | Compare local hit counts |
cacheable_task_remote_hits_count | Compare remote hit counts |
| Cache hit rate | (local_hits + remote_hits) / cacheable_tasks_count * 100 |
category | Note if one is clean and the other incremental (makes duration comparison less meaningful) |
scheme / configuration | Ensure both builds used the same scheme and configuration for a fair comparison |
Compute the cache miss delta: base_misses - head_misses. Positive means head has fewer misses (improvement). Negative means regression.
Step 4: Investigate Duration Regressions
If the head build is significantly slower:
- Check if the
categorydiffers (clean vs incremental builds are not directly comparable). - Check if cache hit rate dropped, which would explain longer builds.
- If both are incremental with similar cache rates, the regression is likely in compilation time.
Step 5: Investigate Cache Changes
Compare cache statistics:
- Hit rate dropped: Possible causes include dependency changes, build setting changes, or Xcode version updates.
- Hit rate improved: Likely due to better cache warming or fewer source changes.
- Task count changed: New targets added or removed.
Step 6: Check Build Context
Compare environment details:
xcode_versionandmacos_version: Different versions can affect build times and cache validity.is_ci: CI vs local builds may have different performance characteristics.git_branchandgit_commit_sha: Verify the builds are from the expected commits.
Summary Format
Produce a summary with:
- Overall verdict: Better, worse, or neutral compared to base.
- Duration: Absolute and percentage change.
- Cache hit rate: Change in hit rate with explanation.
- Status: Any status changes (pass to fail or vice versa).
- Environment: Note any environment differences that affect comparability.
- Recommendations: Actionable next steps based on findings.
Example:
Build Comparison: base (abc123 on main) vs head (def456 on feature-x)
Duration: 45.2s -> 62.8s (+39%) -- REGRESSION
Cache hit rate: 85% -> 72% (-13%) -- 8 new cache misses
Status: success -> success
Root cause: Cache hit rate dropped due to 8 targets with invalidated caches.
The dependency hash changed for FeatureModule, cascading to 7 downstream targets.
Recommendations:
- Investigate why FeatureModule's cache was invalidated
- Consider splitting large targets to reduce cascade impact
Done Checklist
- Resolved both base and head builds
- Fetched sub-resource details (targets, issues, cache tasks)
- Compared duration, cache, and status metrics
- Identified root causes for any regressions
- Provided actionable recommendations
FAQ
What does the compare-builds skill do?
Compares two Xcode build runs to identify duration regressions, cache changes, and new issues. Can be invoked with build IDs, dashboard URLs, or branch names (e.g. tuist compare-builds --base main --head feature-branch).
How do I install compare-builds?
Run npx skills add https://github.com/tuist/agent-skills --skill compare-builds in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/compare-builds/ (personal) or .claude/skills/compare-builds/ (project).
Which AI agents can use compare-builds?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is compare-builds safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains compare-builds?
It is published by tuist in tuist/agent-skills. It has 300 recorded installs.
More from tuist/agent-skills
using-tuist-generated-projects
tuist/agent-skills
Guides day-to-day work in Tuist-generated Xcode workspaces, including generation, build and test commands, and buildable folders. Use when working in a Tuist-generated project or when users mention tuist generate, xcodebuild test, or generated workspaces.
debug-generated-project
tuist/agent-skills
Debugs issues users encounter with Tuist-generated projects by reproducing the scenario locally, building Tuist from source when needed, and triaging whether it is a bug, misconfiguration, or something that needs team input. Use when users report generation failures, build errors after generation, or unexpected project behavior.
fix-flaky-tests
tuist/agent-skills
Fixes flaky tests by analyzing failure patterns from Tuist test insights, identifying root causes, and applying targeted corrections. Can be invoked with a specific test case URL (e.g. https://tuist.dev/{account}/{project}/tests/test-cases/{id}) or without arguments to discover and fix all flaky tests in the project.
migrating-to-tuist-generated-projects
tuist/agent-skills
Migrates existing Xcode projects to Tuist generated workspaces with build and run validation, external dependency mapping, and migration checklists. Use when adopting Tuist for an existing app or converting a hand-edited Xcode project to generated projects.
analyze-selective-testing
tuist/agent-skills
Analyzes Xcode selective testing effectiveness for a test run, showing which test targets were skipped or ran, and diagnosing regressions in test selection. Can compare two test runs to identify what changed.
compare-generations
tuist/agent-skills
Open the skill to read its SKILL.md instructions.
Popular data & databases skills
supabase-postgres-best-practices
supabase/agent-skills
Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.
prisma-client-api
prisma/skills
Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
prisma-database-setup
prisma/skills
Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.
prisma-cli
prisma/skills
Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.
prisma-postgres
prisma/skills
Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.
prisma-driver-adapter-implementation
prisma/skills
Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.