# Tophat Build Install > Find, build, and install mobile artifacts for the current repository through GitHub Actions and Tophat. Use it for requests like "install the latest build from main", "install PR - Skill: `tomevault-io/tophat-build-install` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/tophat-build-install` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/tophat-build-install/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/tophat-build-install --- # Tophat Build Install Use this skill to turn a user request into a concrete GitHub Actions artifact install through Tophat. This skill is GitHub Actions only. Require: - `gh` - Tophat at `/Applications/Tophat.app/Contents/MacOS/tophatctl` with the `gha` provider installed - a repository that already publishes GitHub Actions artifacts Do not switch to another artifact provider from this skill. ## Inputs Collect only the missing inputs. - Platform: `ios` or `android`. - Repository: derive it from the current checkout first. Ask only if there is no usable GitHub remote. - Source selector: branch, PR number, workflow run ID, or explicit artifact ID. - Workflow: only when a new build must be triggered. - Destination: `simulator` or `device` when it matters. - Launch arguments: only if the app needs them. If the user says "latest build", prefer the latest successful existing run for the requested branch instead of forcing a rebuild. If the user says "build", "rebuild", or "trigger", dispatch a new workflow run first. ## Default Flow Use this order: 1. Infer the current repository. 2. Resolve the target from the user request. 3. If the user gave an explicit artifact ID, install it directly. 4. Otherwise, look for an existing artifact first. 5. Trigger a workflow only when no suitable artifact exists or the user explicitly asked for a rebuild. ## Build Resolution Resolve the user's target into a concrete artifact. Use `gh` when you need to inspect PRs, workflows, runs, or artifacts. Use `scripts/gha.py list-artifacts` when you want the local helper to list non-expired artifacts for the current repo or a chosen selector. The helper prefers the repository-wide artifacts endpoint, but if GitHub returns `404` there it should fall back to recent workflow runs instead of stopping immediately. Prefer this order: 1. If the user gave an explicit artifact ID, install it directly. 2. If the user gave a workflow run ID, list artifacts and match `artifact.workflow_run.id`. 3. If the user gave a PR number, resolve the PR head branch and head SHA, then list artifacts for that head. 4. If the user gave a branch or commit SHA, list artifacts and match branch and-or SHA. 5. Trigger a workflow only when no matching non-expired artifact exists or the user explicitly asked for a rebuild. `scripts/gha.py list-artifacts` supports these selectors: - `--ref ` - `--sha ` - `--pr ` - `--run-id ` If multiple artifacts exist, ask the user which artifact to install. Do not filter artifact selection by platform because GitHub Actions artifact names may not include platform text. Use platform only as a Tophat recipe hint during install. ## Install Prefer `scripts/install_artifact.py` for the normal install flow. It creates a temporary recipe, calls Tophat, prints a short status line, and removes the recipe unless `--keep-recipe` is set. Use `/Applications/Tophat.app/Contents/MacOS/tophatctl` as the Tophat CLI path. Keep that path explicit when reporting missing local tooling so agents do not guess. Use `scripts/make_recipe.py` directly only when you need the raw recipe JSON. For `gha`, the recipe must include: - `owner` - `repo` - `artifact_id` If `owner` and `repo` are omitted, infer them from Git. Treat the known `tophatctl` timeout as "install may still be in progress in Tophat", not as a hard failure. For `destination=device`, use only workflows that already produce signed device builds. If that path does not exist, stop and explain it. ## Reference Notes Read `references/public-contract.md` when you need the public Tophat schema, the GitHub Actions provider details, or command examples. --- > Source: [nimblehq/ios-templates](https://github.com/nimblehq/ios-templates) — distributed by [TomeVault](https://tomevault.io).