# Setup > First-run install for hydrant-skills — detect the active harness, configure the hosted Hydrant MCP server, write a fenced "Hydrant lifecycle workflow" section into AGENTS.md (and CLAUDE.md if Claude Code), and verify the connection by calling `mcp__hydrant__list_spaces`. Use when the user asks for `/setup`, says "set up hydrant-skills", "install Hydrant MCP", "wire up Hydrant", or runs the toolkit for the first time after `npx skills add`. - Skill: `background-craft/setup` (Agent Skill) - Install (CLI): `npx skillmds@latest add background-craft/setup` - Raw SKILL.md: https://api.skillmd.com/api/skills/background-craft/setup/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Background-Craft (https://skillmd.com/u/background-craft) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/background-craft/setup --- # Setup `/setup` is the first thing a user runs after `npx skills add Background-Craft/hydrant-skills`. It collapses three chores into a single guided ritual: getting a Hydrant personal access token, configuring the hosted MCP server in the user's harness, and dropping a workflow pointer into `AGENTS.md` so future invocations of `/create-issue`, `/refine`, `/nail`, `/prep`, `/go`, `/preflight`, `/yeet`, and `/cleanup` know they exist. `/setup` writes config files. It is the one skill in this catalogue that mutates anything beyond `AGENTS.md`. Treat the user's existing files with care. ## What this skill produces Three artifacts, in order: 1. **An MCP server entry for `hydrant`** in the active harness's MCP config, pointing at `https://hydrant.dev/mcp` with `Authorization: Bearer hyd_pat_…`. 2. **A fenced lifecycle-workflow section** appended to `AGENTS.md` at the repo root: ```markdown ## Hydrant lifecycle This codebase uses the Hydrant ticket lifecycle. Skills available: - `/create-issue` — interview the user, draft a well-shaped ticket, write via `mcp__hydrant__create_issue` - `/refine` — analyze an existing ticket, surface gaps, update via `mcp__hydrant__update_issue` - `/nail` — tighten ambiguity, ground references against the codebase, extract metadata into proper fields - `/prep` — assess implementation readiness, surface clarifying questions before starting - `/go` — guided implementation: fetch context, create branch, plan, build - `/preflight` — pre-PR mechanical checks, adversarial review, quality scoring - `/yeet` — ship pipeline: detect commit/push/PR/merge state, pick up from there - `/cleanup` — post-merge sync, prune branches Run `/align` once to record this codebase's conventions (test command, branch naming, PR flow) so the lifecycle skills don't have to ask every time. ``` 3. **A mirrored copy of the same fenced section in `CLAUDE.md`**, but only when the active harness is Claude Code (Claude Code reads `CLAUDE.md` for memory; other harnesses use `AGENTS.md`). That is the entire write set. No other file is touched. ## Workflow Run these phases in order. Stop at the first phase that fails and surface a clear error — never silently move on. ### Phase 1: Detect the harness Walk the repo root and the user's home directory looking for harness signals. Stop at the first match in this priority order; do not keep looking once you have one. 1. `.claude/` directory at repo root → **Claude Code** 2. `.cursor/` directory at repo root, or `~/.cursor/` → **Cursor** 3. `.codex/` directory at repo root, or `~/.codex/` → **Codex CLI** 4. `.opencode/` directory at repo root, or `~/.opencode/` → **OpenCode** 5. `~/.gemini/` directory → **Gemini CLI** 6. None of the above → **generic** (the skill prints a JSON snippet at the end and lets the user paste it) Record the detected harness in working memory. Tell the user what you detected and that you'll proceed unless they correct you. ### Phase 2: Get a Hydrant PAT If the user already has a PAT they're ready to paste, skip to the prompt. Otherwise: 1. Tell the user where to generate one: **** (or whatever the current settings UI calls it). 2. Tell them what scope to grant — full read/write on the space they want to wire up. 3. Wait for them to paste the token. Then ask for the **space slug** they want as the default (e.g. `hydrant`, `acme`). The slug is needed because most lifecycle skills accept a `spaceId` argument and the canonical lookup is `mcp__hydrant__get_space(slug: …)`. Validate quickly before writing anything: - Token must start with `hyd_pat_`. If it doesn't, tell the user it looks wrong and ask them to re-paste. - Slug must be lowercase letters/digits/hyphens. If it isn't, normalize and confirm with the user. Do not echo the token back in plaintext after you've stored it. When you reference it in subsequent prompts, mask it (`hyd_pat_***…***`). ### Phase 3: Configure the MCP server Pick the path for the detected harness. If the user runs Claude Code or Cursor, ask whether they want **project scope** (lives in the repo, gets committed) or **user scope** (lives in their home directory, applies to every repo). For the rest, use the harness's documented default scope. Always check whether a `hydrant` MCP entry already exists at the target location before writing. If it does: - If the existing entry's URL matches the hosted endpoint and only the token differs → tell the user "an existing entry was found; replacing it" and proceed. - If the existing entry points somewhere else (a self-hosted URL, a custom command) → stop and ask the user before overwriting. They may be running their own MCP server intentionally. #### Claude Code - **Project scope** → `.mcp.json` at the repo root. Create the file if it doesn't exist. - **User scope** → run `claude mcp add` if the CLI is available; otherwise edit `~/.claude.json`. Snippet (HTTP transport, native — Claude Code supports HTTP MCP servers directly): ```json { "mcpServers": { "hydrant": { "type": "http", "url": "https://hydrant.dev/mcp", "headers": { "Authorization": "Bearer hyd_pat_…" } } } } ``` CLI form for user scope (preferred over hand-editing `~/.claude.json`): ```sh claude mcp add --scope user --transport http hydrant https://hydrant.dev/mcp \ --header "Authorization: Bearer hyd_pat_…" ``` Note: `.claude/settings.json` holds permissions, hooks, and env — *not* MCP server definitions. The canonical home for MCP entries in Claude Code is `.mcp.json` (project) or `~/.claude.json` (user, written by `claude mcp add`). #### Cursor - **Project scope** → `.cursor/mcp.json` at the repo root. Create the directory and file if missing. - **User scope** → `~/.cursor/mcp.json`. Snippet (Cursor supports HTTP MCP servers natively): ```json { "mcpServers": { "hydrant": { "url": "https://hydrant.dev/mcp", "headers": { "Authorization": "Bearer hyd_pat_…" } } } } ``` #### Codex CLI Codex's TOML config does not always support HTTP transport directly. Use the `mcp-remote` stdio bridge to be safe. Append to `~/.codex/config.toml`: ```toml [mcp_servers.hydrant] command = "npx" args = ["-y", "mcp-remote", "https://hydrant.dev/mcp", "--header", "Authorization: Bearer hyd_pat_…"] ``` If the user is on a recent Codex build that has native HTTP MCP support, they can swap this for the URL form documented in their Codex release notes. #### OpenCode OpenCode reads MCP config from `opencode.json` at the project root or the user's config directory. Use the `mcp-remote` stdio bridge: ```json { "mcp": { "hydrant": { "type": "local", "command": ["npx", "-y", "mcp-remote", "https://hydrant.dev/mcp", "--header", "Authorization: Bearer hyd_pat_…"] } } } ``` If the user's OpenCode build supports the `type: "remote"` HTTP form, use that instead — check their docs for the current key name (`url` vs `endpoint`). #### Gemini CLI Gemini CLI's user config lives at `~/.gemini/settings.json`. Most builds expect a stdio-launched MCP server, so use the `mcp-remote` bridge: ```json { "mcpServers": { "hydrant": { "command": "npx", "args": ["-y", "mcp-remote", "https://hydrant.dev/mcp", "--header", "Authorization: Bearer hyd_pat_…"] } } } ``` #### Generic / unknown harness Print the JSON snippet below and tell the user to consult their harness's MCP server documentation for the right file location and key name. Do not write any files in the generic path — the user opted into manual install by running an unrecognized harness. ```json { "mcpServers": { "hydrant": { "url": "https://hydrant.dev/mcp", "headers": { "Authorization": "Bearer hyd_pat_…" } } } } ``` If their harness only supports stdio, point them at `npx -y mcp-remote https://hydrant.dev/mcp --header "Authorization: Bearer hyd_pat_…"` as the bridge. ### Phase 4: Write the lifecycle section to AGENTS.md (and CLAUDE.md if Claude Code) Now write to `AGENTS.md` at the repo root. 1. **If `AGENTS.md` doesn't exist**: create it with a top-level `# Agents` heading and the lifecycle block as the first section. Do not pull in any other content. 2. **If `AGENTS.md` exists and contains a `` fence**: replace *only* the fenced region (inclusive of both sentinels) **after prompting the user**. Never silently overwrite. Do not touch any line outside the fence. Do not reorder or reflow surrounding content. 3. **If `AGENTS.md` exists but has no fence**: append the fenced block at the end of the file, separated from prior content by a single blank line. 4. **Coexist with `/align`**: the `` fence (written by `/align`) is a separate region with separate sentinels. Do not touch it. Both blocks live in the same `AGENTS.md` peacefully. When the active harness is **Claude Code**, also mirror the same fenced block into `CLAUDE.md` at the repo root using the same rules. Skip this mirror for any other harness — `CLAUDE.md` is Claude-specific memory and other harnesses ignore or actively conflict with it. **Manual-edit safety**. If you detect that the existing fence has a comment line like `# manually edited` *or* the body has been reflowed into prose, pause and ask the user before overwriting: > "The existing lifecycle block has been hand-edited. Overwriting would lose those edits. Do you want to overwrite, keep the existing version, or abort?" Only proceed once the user picks one. ### Phase 5: Verify the connection Call `mcp__hydrant__list_spaces` to confirm the hosted MCP is reachable with the supplied token. Two cases: - **Harness hot-reloaded the MCP config** (some do, some don't): the call succeeds and returns the user's spaces. Confirm that the slug they gave in Phase 2 appears in the result. If it doesn't, surface "I configured the token but the slug `` isn't on the list — typo, or different workspace?" - **Harness needs a restart**: `mcp__hydrant__list_spaces` is not available in the current session because the harness loads MCP config at startup. Tell the user: > "Configuration written. Restart your harness, then run `mcp__hydrant__list_spaces` (or just invoke `/setup verify`) to confirm the connection." Do not pretend the connection is verified when it isn't. If the call fails with a 401 or 403, the token is wrong. Tell the user, ask whether they want to retry Phase 2 with a fresh token, and if yes, loop back. Never leave a known-bad token in place. If the call fails with any other error (5xx, network), surface the raw error and stop — don't guess. ### Phase 6: Confirm Print a short summary back to the user: - Detected harness. - Where the MCP config was written (path + scope). - Whether `AGENTS.md` was created or appended; whether `CLAUDE.md` was mirrored. - Verification result (success, deferred-pending-restart, or failure). - Next-step pointer: > "Run `/align` next so the lifecycle skills know your codebase's conventions (test command, branch naming, PR flow). Then `/create-issue` is the entry point for the lifecycle." ## Edge cases - **User runs `/setup` with no internet** — Phase 5 fails with a network error. The config is still written; tell the user verification will happen on next launch. - **User's harness doesn't support MCP at all** — print the REST endpoint URL (`https://hydrant.dev/mcp`) and the bearer-token header format, and tell them they can drive Hydrant manually via the documented HTTP API. Skip Phases 3–5 for that harness. - **User has multiple harnesses installed simultaneously** (rare but possible: `.claude/` and `.cursor/` both present) — ask which one they want to wire up; do not configure both silently. - **AGENTS.md is huge or owned by a different convention** — only the fenced region belongs to `/setup`. If there's no fence, append; never insert mid-document. - **AGENTS.md is a symlink, read-only, or owned by another user** — stop, tell the user, do not silently fail. - **Re-running `/setup` after a successful first run** — Phase 1 detects the harness again, Phase 2 asks if the user wants to rotate the token (default: no), Phase 3 detects the existing entry and prompts before replacing, Phase 4 prompts before replacing the AGENTS.md fence, Phase 5 verifies. Idempotent end-to-end. - **`npx skills update` ran later and bumped this skill** — the user's `AGENTS.md` lifecycle section is theirs and is never overwritten by an update. Only `/setup` itself touches it, only when the user runs `/setup` themselves. - **User pastes a token with leading/trailing whitespace** — trim before validation. Do not store untrimmed tokens. - **Repo has no `.git` directory** (raw working tree) — fine for `AGENTS.md` write, but warn the user that lifecycle skills like `/yeet` will misbehave without a git repo. ## What this skill never does - Write any file outside `.mcp.json` / `.cursor/mcp.json` / `~/.codex/config.toml` / `opencode.json` / `~/.gemini/settings.json` / `~/.claude.json` (or what the active harness requires), `AGENTS.md`, and `CLAUDE.md` (Claude Code only). - Modify content outside the `` … `` fences. - Touch the `` fence written by `/align`. - Echo the user's PAT in plaintext after capture. - Generate a PAT on the user's behalf — the user gets the token themselves from the Hydrant settings page. - Rotate, revoke, or delete tokens — only writes new entries with prompted overwrites. - Configure any non-Hydrant MCP server. ## Why this matters Without `/setup`, the user finishes `npx skills add` with a directory full of skill files that don't know how to reach Hydrant. The agent has the skill prompts but no `mcp__hydrant__*` tools wired up. Skills fail at the first MCP call and the user gets an unhelpful "tool not found" error — the worst possible first impression. `/setup` makes the install end-to-end functional in one ritual, with one user-visible prompt for the token, on whichever harness the user happens to be running. The fenced AGENTS.md section makes the rest of the catalogue discoverable so the user knows what skills they just installed and when to reach for each.