--- name: errorgap-setup description: Set up errorgap in this codebase or add another errorgap feature to it. Covers error tracking, deploys, source maps, performance (APM), logs, infrastructure metrics, server security, web sign-ins, session replay, uptime, alerts, integrations and MCP agent access. Use when the user asks to install, configure, extend or verify errorgap, or pastes an errorgap setup prompt. Not for investigating production errors; that is what the errorgap MCP server is for. --- # errorgap setup You are setting up errorgap, a managed incident-intelligence platform, in the user's repository. The work has four phases: inspect the repository, ask the user what they want, implement it, and verify it. Ask before you change anything. The user decides which features are set up; you do the work for the ones they choose. This skill works the same way in Claude Code, Codex and other coding agents. It ships with one companion file, `features.md`, that holds the setup facts for each feature. Read it before the interview. If you fetched this file from a URL, `features.md` is at the same URL with the file name swapped. ## Values you need | Value | Where it comes from | |---|---| | `ERRORGAP_ENDPOINT` | The setup prompt, or the origin of the user's errorgap app (for example `https://acme.errorgap.com`). No trailing slash. | | `ERRORGAP_PROJECT_SLUG` | The setup prompt, or the project's URL in the app (`/projects/`). | | `ERRORGAP_API_KEY` | The setup prompt, or Project Settings in the app. Starts with `egp_` (older keys start with `flk_`). | | `ERRORGAP_UPLOAD_KEY` | Project Settings → Upload key. Only needed for source maps. Never part of a setup prompt. | Look for these in the prompt that invoked you first, then in the environment and the repository's existing errorgap configuration. Ask the user for whatever is still missing. Do not guess a slug or an endpoint. Both keys are secrets: - Store them in environment variables or the repository's existing secret mechanism. Never hardcode or commit them, and never repeat them in your summary. - The API key is public by nature in browser and mobile bundles, so it is fine there. The upload key must stay in CI secrets and must never reach a client bundle. Guides are served by the user's errorgap instance: - `{ERRORGAP_ENDPOINT}/agent-docs/index.md` documents the ingestion API and lists a guide for each stack. - `{ERRORGAP_ENDPOINT}/agent-docs/errorgap-agent.md` covers the server agent. - `https://errorgap.com/developers/sdks/` is the full guide for each SDK, including the optional features. After installing an SDK, read the README of the version you actually installed. Take option names from it, not from memory: SDKs differ between languages and gain features between versions. ## Phase 1: inspect the repository Do this before asking anything, so you only ask what the repository cannot tell you. 1. Find every runtime in the repository: server frameworks, browser bundles, mobile apps, workers. A monorepo usually has several, and each needs its own SDK. 2. Check whether errorgap is already installed. If it is, note the SDK versions and which features are configured, and treat this run as adding to that setup. 3. Find how the app is built and deployed: CI workflows, deploy scripts, Dockerfiles, Compose files, Kubernetes manifests, infrastructure code. Deploy tracking and source maps hook in here. 4. Find how secrets and environment variables reach each runtime and CI. 5. Find where the app runs: hosts you can reach from this repository's deployment config, a container platform, or a serverless platform. The server agent only applies to hosts and containers the user controls. 6. Note log file paths and formats, health-check endpoints, the authentication library, and whether the browser bundle is minified. Later questions depend on them. ## Phase 2: ask the user Tell the user in two or three sentences what you found, then run the interview. Use your structured question tool if you have one (for example `AskUserQuestion` in Claude Code). Otherwise ask in a short numbered list and wait for the answer. Rules for the interview: - Ask about every feature in the table below that applies to this repository. Skip the ones that cannot apply, and say which you skipped and why in one line. - Do not ask what the setup prompt already answered. If the prompt says the user wants logs shipped, that is decided. - Do not ask what the repository answers. Confirm it instead ("I found a Rails app and a Vite frontend, both deployed from `.github/workflows/deploy.yml`"). - Ask the feature questions first, as one multiple-choice round or two. Then ask the follow-up questions only for the features the user chose. - Give a recommendation with each question and a one-line reason. The user can accept all your recommendations at once. - Keep each round to four questions or fewer. Say what each feature costs the user: a code change, a CI secret, a package on a server, or a few clicks in the app. | # | Feature | Applies when | What you do | |---|---|---|---| | 1 | Error tracking | Always | Install and configure an SDK per runtime | | 2 | Deploy tracking | There is a deploy pipeline or script | Add a step that records each deploy | | 3 | Source maps | A minified browser or React Native bundle | Build hidden maps and upload them in CI | | 4 | Performance (APM) | A server or app SDK that supports it | Enable it in the SDK configuration | | 5 | Browser performance | A browser app | Enable web vitals and server trace links | | 6 | Logs | Any server-side app | Ship from the SDK, or tail files with the agent | | 7 | Infrastructure metrics | Hosts or containers the user controls | Install and configure `errorgap-agent` | | 8 | Server security | Linux hosts the user controls | Enable login auditing and security checks in the agent | | 9 | Web sign-ins | The app has its own login | Enable sign-in events in the SDK | | 10 | Session replay | Browser or mobile app | Confirm the SDK version; the user enables it in the app | | 11 | Uptime monitors | Public endpoints exist | Propose the monitors; the user creates them | | 12 | Alerts | Always | Propose starting rules; the user creates them | | 13 | Integrations | The team uses Slack, GitHub, GitLab, Jira or webhooks | Tell the user where to connect them | | 14 | MCP agent access | The user wants agents to read production context | Add the MCP server to this agent once the user has a token | | 15 | Privacy and redaction | The app handles personal or sensitive data | Propose redaction rules; the user adds them | `features.md` lists the follow-up questions for each feature. Typical ones: which environments should report, what the release identifier is, the sample rate for performance data, whether user identifiers may be attached to events, and which hosts get the agent. When the interview is done, state the plan as a short list of what you will change and what the user will need to do in the errorgap app. Then start. ## Phase 3: implement Work through the chosen features in the order of the table. Error tracking comes first because everything else builds on it. - Follow `features.md` for each feature and the linked guide for exact steps. - Use the same `environment` and `release` values everywhere: every SDK, the deploy step, and the source map upload. Deploy attribution and source map resolution both depend on them matching. - Follow the repository's conventions for configuration, secrets, CI and dependency management. Make the smallest change that works. - Do not invent log paths, hostnames, labels or health-check URLs. Use what the repository shows, or ask. - Some steps happen in the errorgap app and need a signed-in user: enabling session replay, creating uptime monitors and alert rules, connecting integrations, creating an MCP token, copying the upload key. Do not try to automate them. Collect them into one checklist with the exact page for each, and give it to the user. - If a step needs access you do not have, such as a production host or a CI secret store, write the exact commands or values for the user and continue with the rest. ## Phase 4: verify 1. Check connectivity before relying on any SDK: ```sh curl -sS -X POST "$ERRORGAP_ENDPOINT/api/projects/$ERRORGAP_PROJECT_SLUG/notices" \ -H "content-type: application/json" \ -H "x-errorgap-project-key: $ERRORGAP_API_KEY" \ -d '{"errors":[{"type":"ErrorgapInstallTest","message":"Errorgap install verification"}],"context":{"environment":"development"}}' ``` HTTP 201 with a `group_id` means it worked. 202 means the event was received but sampled or rate-limited, which is still a working connection. 401 means the key is wrong or missing. 2. Trigger a real test error through each installed SDK, the way its guide shows. Check first that the SDK is not configured to ignore the environment you are testing in. 3. Verify each additional feature the way `features.md` describes. Where the errorgap app is the only real proof, such as a log line on the Logs page or a host on the Infrastructure page, say so and ask the user to look. 4. Remove any temporary test code you added, such as a throwing route or button. ## Finish End with a summary the user can act on: - What you set up, by feature, and the files you changed. - What you verified and how. Say plainly if something could not be verified. - The checklist of steps left for the user in the errorgap app or their secret store. - Features the user declined or that did not apply. They can run this skill again later to add them. If you were given a one-off prompt and this skill is not installed in the repository, offer to install it so the user can run it again: copy `SKILL.md` and `features.md` to `.claude/skills/errorgap-setup/` for Claude Code and to `.agents/skills/errorgap-setup/` for Codex.