# Add Registry Changeset > Write a changeset file in the `hyperlane-registry` repo for a PR that adds, updates, or modifies warp route config / chain metadata / addresses. Canonical pattern — never run the interactive `pnpm changeset` CLI; write the file directly. Referenced by any skill that opens a registry PR. - Skill: `hyperlane-xyz/add-registry-changeset` (Agent Skill) - Install (CLI): `npx skillmds@latest add hyperlane-xyz/add-registry-changeset` - Raw SKILL.md: https://api.skillmd.com/api/skills/hyperlane-xyz/add-registry-changeset/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: hyperlane-xyz (https://skillmd.com/u/hyperlane-xyz) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/hyperlane-xyz/add-registry-changeset --- # Add a Registry Changeset The `hyperlane-registry` repo uses changesets to track PR-level changes and drive npm releases of `@hyperlane-xyz/registry`. Every PR that touches the published surface (warp route configs, chain metadata, addresses, deployments) MUST carry a changeset, otherwise the merge bot blocks the PR and the published package falls behind. Skills that open registry PRs invoke this skill to write the changeset before committing. ## Why a dedicated skill - Single source of truth for filename / frontmatter / style / semver-bump conventions. - Avoids per-skill drift — fresh deploys, route updates, chain extensions, address backfills, logo updates all need the same shape; encode it once. - Closes the recurring miss where the PR-opening was done ad-hoc (user prompts the agent to "open a registry PR") and the agent forgets the changeset because it isn't in the parent skill's checklist. ## Input - **Change summary** (required) — one short sentence describing what the PR does. Past tense, lowercase, concise (CLAUDE.md style for changesets). - **Bump type** (required) — `minor` for new warp routes / new chains / new published assets; `patch` for updates / fixes / metadata tweaks to existing entries. - **Filename slug** (optional) — short kebab-case identifier; if not provided, the agent picks a slug derived from the PR scope (e.g. `add-ikas-ethereum-igra`, `update-eth-arbitrum-base-fee-11bps`, `fix-katana-rpc`). The auto-generated `--.md` names that the interactive CLI emits are also acceptable but discouraged — descriptive slugs are easier to scan in PR diffs. ## Step 1: Confirm the Registry Path The changeset must be written to the `hyperlane-registry` checkout, NOT the monorepo. Determine the registry path: ```bash REGISTRY_PATH="${HYPERLANE_REGISTRY:-$HOME/hyperlane-registry}" ls -d "$REGISTRY_PATH/.changeset" || { echo "Registry .changeset/ missing — wrong path?" >&2; exit 1; } ``` If the registry checkout isn't at the expected location, surface the discrepancy to the user before continuing. ## Step 2: Choose the Filename Use the provided slug, OR derive one from the PR scope: | PR scope | Filename example | | ---------------------------------------------------- | ------------------------------------------- | | New warp route deploy | `add--.md` | | Warp route config update (fees / ISM / hook / owner) | `update---.md` | | Adding a chain | `add-.md` | | Updating chain metadata (RPCs, blocks, logo, etc.) | `update--.md` | | Fix / backfill | `fix-.md` | The file must be `*.md` and live directly under `.changeset/`. The registry `.changeset/config.json` enforces the schema. ## Step 3: Write the File The content has TWO parts: a YAML frontmatter block specifying the package + bump, then a free-form markdown body that becomes the changelog entry on publish. ```markdown --- '@hyperlane-xyz/registry': --- ``` **Bump rules**: - `minor` — added something new that downstream consumers will start seeing (new warp route, new chain, new published asset). - `patch` — modified or fixed an existing entry (fee change on an existing route, RPC update, ICA address backfill, logo swap). **Style** — per CLAUDE.md: > Write changeset descriptions in past tense describing what changed. > Good: "The registry code is restructured by moving filesystem components to a dedicated directory." > Bad: "Restructures the registry code." Lowercase first letter, no terminal period if it's a single short sentence. Multi-sentence summaries can use sentence case. ## Step 4: Validate Inspect the file before staging: ```bash cat "$REGISTRY_PATH/.changeset/" ``` Confirm: - Frontmatter has exactly one package entry: `'@hyperlane-xyz/registry': ` - Bump value matches the rule above - Body is one or two sentences in the right tense + voice - No secrets / private RPC URLs leaked into the body ## Step 5: Hand Back to the Calling Skill Return control to the caller. The caller is responsible for staging the changeset alongside the PR's other files: ```bash cd $REGISTRY_PATH git add .changeset/ # … plus the warp route config / chain metadata files specific to the change git commit -m "" ``` **Do NOT use `git add .` or `git add -A`** in the registry checkout. Scope to the changeset + the specific files the PR touches. If a warp apply run was done with the HTTP registry in writeMode, unrelated files may have been written by the server — staging them blindly risks publishing API-keyed RPC overrides. Always run `git status` first and review the file list before staging. --- ## Notes - **Do NOT run `pnpm changeset` (the interactive CLI)** — its prompts hang in headless / agent environments and produce auto-generated `--.md` names that are less informative. Writing the file directly is faster and produces better history. - The auto-generated filename pattern is acceptable if the registry's CI rejects custom slugs for some reason, but in practice the `.changeset/config.json` doesn't enforce a naming pattern beyond the `.md` extension. - For consumers: `/warp-deploy-update-owners` Step 12 (fresh-deploy PR), `/warp-update` post-broadcast registry PR step, any chain-metadata update skill.