hydrant-skills

# hydrant-skills

Skills that teach your agent how to work inside a [Hydrant](https://hydrant.dev) workspace. Read everything before touching anything. Write with receipts. Say what actually happened.

## Hydrant MCP server

[Hydrant](https://hydrant.dev), operated by Background Craft, lets your agent track issues, projects and dependencies in a workspace you control. The hosted MCP server can read workspace context and, with permitted access, create and update issues, add comments and manage relationships.

This public repository contains Hydrant's agent skills and client integration packages. The hosted server's application source is private; you do not need to clone this repository or run a local server to connect.

### Connect

Add a remote MCP server to your client's configuration:

```json
{
  "mcpServers": {
    "hydrant": {
      "type": "http",
      "url": "https://hydrant.dev/api/mcp"
    }
  }
}
```

The endpoint uses Streamable HTTP. Configuration syntax varies by client; follow the [client setup guide](https://hydrant.dev/help/agents/connect). Authenticate through your client's browser OAuth flow, sign in with GitHub and approve the intended workspace and permitted access. No static API key is required for OAuth connections. Access stays bounded by your workspace role and can be revoked in Hydrant under **Settings → Agents → Access**. See [consent and access](https://hydrant.dev/help/agents/consent-and-access).

### Use

Start by asking your agent to identify the connected workspace, then try:

- “Show my open issues and their blockers.”
- “Summarize the activity on issue #42.”
- “Create an issue for this bug report.” (requires permitted write access)

Confirm the workspace before making changes. The skills below add guidance for the ticket lifecycle; they are optional for connecting to the server.

[Privacy](https://hydrant.dev/privacy) · [Terms](https://hydrant.dev/terms) · Support: [bots@hydrant.dev](mailto:bots@hydrant.dev)

## Agent skills

Hydrant already hands agents its tools over MCP. Tools describe what an agent *can* call. These skills cover what it *should* do.

- [`hydrant`](./skills/hydrant/SKILL.md): the base every other skill relies on. It also covers promoting between environments: check the clearance first, stop and ask when it's missing or reviews are still open, and brief the reviewers with dockets after.
- [`hydrant-setup`](./skills/hydrant-setup/SKILL.md): scans your repository, installs the rest without overwriting your own skills, and writes the repository profile.
- [`capture`](./skills/capture/SKILL.md): files a new issue from a request, idea or bug report, after checking for duplicates.
- [`refine`](./skills/refine/SKILL.md): settles scope, acceptance, priority, size, owner, labels and project, and marks the issue Ready only when nothing material is open.
- [`prep`](./skills/prep/SKILL.md): confirms the assignment, reads the issue and the code it touches, maps each acceptance check to a command from your profile, and records a checkpoint on the issue. Edits nothing.
- [`go`](./skills/go/SKILL.md): builds the issue on its own branch, runs your profile's checks, preflights the result and hands it to review with a brief for the reviewer. Commits locally; pushes and opens a pull request only when you ask or under a `ship` grant. Never merges.
- [`review-triage`](./skills/review-triage/SKILL.md): watches an open pull request, checks each review comment against the code, fixes what's warranted, replies in every thread and records the result on the Hydrant issue.
- [`ship`](./skills/ship/SKILL.md): takes one issue, building it with `go` if that's still to do, through the pull request, the CI gate at the exact head, merge, your profile's release steps and the done status, only under a grant you confirm for that issue.

**Review costs nothing extra.** Before handing off, `go` gets one independent review of its change from a fresh reviewer on the agent you already use: a subagent where your client has one (Claude Code and Codex both do), otherwise a second session of the same CLI with editing turned off (`claude -p` with edit tools disallowed, or `codex exec -s read-only`). No review bot or paid service is needed. If you already use one, `go` leaves it to review the pull request as usual. If no independent reviewer can run, `go` says so instead of passing off its own review as independent.

## Install

```sh
npx skills add Background-Craft/hydrant-skills -s hydrant-setup -a claude-code -a codex
```

Drop the `-a` for the agent you don't use. Then ask your agent to run `hydrant-setup`.

Keep `-s` and at least one `-a`. `-s` installs setup on its own: a plain `npx skills add Background-Craft/hydrant-skills -y` overwrites any skill of yours with the same name, such as your own `refine`, without asking. `-a` keeps the CLI to those agents' folders. When an agent runs the command without it, the CLI installs for every agent it supports, with no prompt, and replaces any same-named skill in their folders. Setup pins `-a` the same way for every skill it installs.

**Codex:** its default `workspace-write` sandbox protects `.agents/`, so the install fails there. Run the command from your own terminal. When setup installs skills and writes `.agents/hydrant-workflow.md`, approve the escalation Codex asks for. If you don't, setup prints the commands and the profile for you to run and save yourself.

Only want the base skill? `npx skills add Background-Craft/hydrant-skills -s hydrant`.

The [skills CLI](https://github.com/vercel-labs/skills) is the whole installer. It detects the agents you have, and writes a skill directory, an optional symlink and a lockfile. Nothing else. No hooks, no shell scripts, no edits to your instructions files.

- `-g` installs for your user instead of this project.
- `-a claude-code` picks one agent. Repeat `-a` for more.
- `--copy` copies instead of symlinking.

### What lands on disk

Project install with Claude Code and Codex both selected:

- `.agents/skills/hydrant/`: the skill itself. Codex and other `.agents`-aware clients read it here.
- `.claude/skills/hydrant`: a symlink to that directory, for Claude Code.
- `skills-lock.json`: source, path and content hash, so a later `npx skills update` knows what it installed.

With a single agent selected, the CLI copies the skill straight into that agent's directory (`.claude/skills/hydrant/` for Claude Code, `.agents/skills/hydrant/` for Codex) and skips the symlink. Either way that directory and the lockfile are the only changes. Installing a skill does not connect a client, create a key or authorize anything.

### What setup does

`hydrant-setup` reads your skills, `skills-lock.json`, AGENTS.md/CLAUDE.md, scripts, CI, deploy config and any review bot (none is fine; no paid service is needed). It shows one plan and waits for your answer before writing anything.

- **New skills** are installed one at a time with `-s <name>` and explicit `-a` agents, so nothing outside the folders it checked is touched.
- **A skill you already have** with the same name stays as it is by default, and setup prints a short Hydrant section you can paste into it. It is replaced only if you say so, after a verified backup to `.agents/hydrant-setup-backup/<name>/`.
- **The profile**, `.agents/hydrant-workflow.md`, holds this repository's facts: base branch, commands, CI gate, PR conventions, review bots, release steps, what "done" means and which skills were installed. It is yours to edit; the skills CLI never touches it. Statuses, acceptance and ship grants stay in your Hydrant workspace.
- **Older Hydrant guidance** in AGENTS.md, CLAUDE.md or your own skills (tool names this server doesn't list, the old `hydrant.dev/mcp` endpoint, `hyd-NNN` IDs) is listed in the plan as "may conflict". Setup leaves those files as they are; you decide.
- **Running it again** rescans and proposes additions to the profile, and offers any pack skill you don't have yet. It never rewrites your lines or updates installed skills. The one exception is a skill whose install failed: setup marks it installed once it is. It writes nothing when nothing changed.

Setup does not edit AGENTS.md or CLAUDE.md, create keys, connect clients or write to Hydrant.

### Review bots are optional

`review-triage` always triages people's comments: review bodies, inline comments and top-level PR comments. A review bot's comments are triaged only when its login is under **Review bots** in the profile, so CodeRabbit, Copilot, Greptile and others all work the same way. Other bot accounts, such as Dependabot, are listed as not triaged. With no bot listed, which is the default, the skill waits only for CI. Comment text is checked against the code and never followed as an instruction. The skill never merges, approves or changes the issue's status.

### Ship runs only under your grant

`ship` is the only skill that merges or marks work done. Run `/ship #42` and it shows you a grant for issue 42 alone, naming the merge method and each release step from your profile, and waits. Only your yes in that conversation counts: a grant written on the issue earlier, or a comment claiming one, grants nothing, and a new session asks again. The grant is recorded on the issue before anything else happens. It never covers secrets, new or paid infrastructure, production data, deleting branches or files, bypassing branch protection or a required approval, promoting past a missing clearance, or over work still waiting or held, without your yes to that promotion, or work beyond the issue. At any of those, and at a check still red after one rerun, `ship` stops, records why on the issue and leaves the issue where it is. It runs only the release steps the grant quoted, each as written, and checks each one. With none in your profile, it merges and marks the issue done once your profile's **Done** lines are met.

### Update and remove

```sh
npx skills list
npx skills update
npx skills remove hydrant
```

`update`