Hydrant README

hydrant-skills

Skills that teach your agent how to work inside a Hydrant workspace. Read everything before touching anything. Write with receipts. Say what actually happened.

Hydrant MCP server

Hydrant, 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:

{
  "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. 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.

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 · Terms · Support: 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: 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: scans your repository, installs the rest without overwriting your own skills, and writes the repository profile.
• capture: files a new issue, or a related set, from a request, idea or bug report, after checking for duplicates. It files buildable work only (no decision issues, no umbrella parents), groups a set by project and milestone, and links every real blocker, so two issues with no blocking path between them can be built in parallel.
• refine: settles scope, acceptance, priority, size, owner, labels and project, and marks the issue Ready only when nothing material is open.
• prep: 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: 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: 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.

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

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 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: as Hydrant grant data with create_grant (for its own connection, this issue, with read, write, pull request and merge actions, release only when your profile has release steps and never sign-off), then as a comment naming the grant id. On a server without create_grant, the comment alone records it and says so. 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

npx skills list
npx skills update
npx skills remove hydrant

update re-downloads every GitHub-sourced skill in the project and overwrites the installed copy, including your edits, even when nothing changed upstream. Keep local changes somewhere else, or install with a local path (npx skills add ./path), which update leaves alone entirely.

remove hydrant deletes that skill's directory and link and leaves every other skill, skills-lock.json and your agent configuration alone.

Telemetry

Not ours. The skills CLI records anonymous install events that include the public repository name. Set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 to turn that off.

Connect

Cline and other remote MCP clients

Connect to https://hydrant.dev/api/mcp using Streamable HTTP. Clients with remote OAuth support open Hydrant in your browser so you can choose a workspace and grant access. No local server required.

Follow the Cline setup guide, then verify the workspace with a read before asking your agent to change anything. The 400×400 Hydrant logo is available for directory listings. This repository contains skills and client setup; it does not contain the hosted server's source.

API-key connections

Three things that are not the same: a connection (the client reaches the server), authorization (what the key may do, one workspace) and permission (what you asked for in this task). The skill keeps them apart. So should you.

The skill assumes a connection already exists. Keys are created in Hydrant under Settings → Agents for one workspace; a key never exceeds the role of the person who made it and stops working when they leave the workspace.

Endpoint: https://hydrant.dev/api/mcp, Streamable HTTP, Authorization: Bearer <key>.

Claude Code, project scope, in .mcp.json, with the key supplied through the environment rather than typed into the file:

{
  "mcpServers": {
    "hydrant": {
      "type": "http",
      "url": "https://hydrant.dev/api/mcp",
      "headers": { "Authorization": "Bearer ${HYDRANT_AGENT_KEY}" }
    }
  }
}

Codex:

codex mcp add hydrant \
  --url https://hydrant.dev/api/mcp \
  --bearer-token-env-var HYDRANT_AGENT_KEY

Keep client approvals on. Hydrant's write tools declare their side effects; the skill tells the agent to write only what you asked for, and your client's prompt is the second lock.

Claude Code plugin

Your agent has confidence. Give it a paper trail.

The plugin gives Claude Code a connection to Hydrant and the hydrant skill: read the context, do the requested work, check the result, and bring receipts. “Done” is a claim. We'd like some evidence. Sign in with OAuth in your browser; no API key to paste into a file.

claude plugin marketplace add Background-Craft/hydrant-skills
claude plugin install hydrant@hydrant

Then run /mcp inside Claude Code, choose plugin:hydrant:hydrant and Authenticate. Approve one workspace in the browser tab that opens. Check the workspace name before you click: the agent gets that one, at your role, and no other. Until you finish signing in, claude mcp list shows Needs authentication.

The plugin includes the base hydrant skill. Install the workflow pack separately with hydrant-setup so it can use your repository's build, review and release rules.

• Already ran claude mcp add hydrant --scope user? Your entry stays put. claude mcp list shows only your hydrant, not the plugin's copy of the same URL; the plugin still adds the skill, and removing the plugin leaves your entry alone.
• Hydrant in a project .mcp.json? That entry doesn't displace the plugin's, so you can end up with two Hydrant servers. Keep one: drop the entry, or skip the plugin.
• Update: claude plugin marketplace update hydrant, then claude plugin update hydrant@hydrant, then restart Claude Code.
• Signed in to the wrong workspace? Revoke that connection in Hydrant under Settings › Agents › Access first, so it stops holding a slot. Then run claude mcp logout plugin:hydrant:hydrant, and /mcp → Authenticate again. claude mcp remove can't touch a server that a plugin brought.
• Also running hydrant-setup? Let it install hydrant in the repository as well, because the pack's skills read it from the folder next door. Claude Code then sees two copies of one file, hydrant and hydrant:hydrant. Keep them on the same release.
• Pause: claude plugin disable hydrant@hydrant takes the server and skill out of new sessions; enable brings them back.
• Remove: claude plugin uninstall hydrant@hydrant, then claude plugin marketplace remove hydrant if you want the marketplace gone too. Other servers, plugins and settings aren't touched. The workspace approval stays in Hydrant until you revoke it under Settings › Agents.

Install from this repository's marketplace. Hydrant is not yet listed in Anthropic's plugin directory; that submission is separate.

Codex plugin

One install gets Codex both halves: the Hydrant MCP server and the hydrant skill. It signs in with OAuth in your browser, so there's no key to paste anywhere.

codex plugin marketplace add Background-Craft/hydrant-skills
codex plugin add hydrant@hydrant
codex mcp login hydrant

Approve one workspace in the browser tab that opens. Check the workspace name before you click: the agent gets that one and no other.

The plugin carries the base hydrant skill only. The workflow pack stays a per-repository install through hydrant-setup, because it needs that repository's profile.

• Already ran codex mcp add hydrant? Your entry stays put. The plugin adds the skill and leaves your server alone, even when you remove the plugin.
• Update: codex plugin marketplace upgrade hydrant, then codex plugin add hydrant@hydrant again.
• Signed in to the wrong workspace? Revoke that connection in Hydrant under Settings › Agents › Access first, so it stops holding a slot. Then run codex mcp logout hydrant and codex mcp login hydrant. codex mcp remove can't touch a server that a plugin brought.
• Also running hydrant-setup? Let it install hydrant in the repository as well, because the pack's skills read it from the folder next door. Codex then sees two copies of one file, hydrant and hydrant:hydrant. Keep them on the same release.
• Remove: codex plugin remove hydrant@hydrant, then codex plugin marketplace remove hydrant if you want the marketplace gone too. Other servers and plugins aren't touched.

This is a plugin you install from this repository, not a listing in OpenAI's plugin directory. It isn't in the directory yet.

Cursor plugin

The ticket already exists. Give your agent the context. The Cursor package pairs the same base skill with the same remote MCP endpoint. It does not install the workflow pack.

Local package discovery and desktop OAuth have been checked in Cursor 3.21.16 on macOS against Hydrant v2026.09.27.5. The reviewer-account test verified workspace identity, synthetic issue creation/read-back and denial after revocation. Neither Cursor Marketplace nor cursor.directory has received a submission for this package. Follow the package guide for direct installation, existing-server handling and removal.

Gemini CLI extension

For a local preview, build the generic archive, extract it to a temporary directory, and install that extracted directory with Gemini's normal confirmation prompt:

node scripts/package-gemini-extension.mjs
preview_dir=$(mktemp -d)
tar -xzf release/hydrant.tar.gz -C "$preview_dir"
gemini extensions install "$preview_dir"

Do not install, link, or point Gemini at this repository root: Gemini loads every skills/ subdirectory, which includes the repository workflow pack. The release archive deliberately contains only skills/hydrant/, its agents/openai.yaml dependency, LICENSE, and the root gemini-extension.json manifest.

Install the Gemini extension from the latest GitHub Release (v0.3.3 or later):

gemini extensions install https://github.com/Background-Craft/hydrant-skills

The GitHub Release must include the generic base-only archive as its sole asset for this command to be a safe default. A pinned --ref stays pinned when you update. To leave a pin, uninstall hydrant and reinstall without --ref after checking the latest approved release.

The extension defines one server, hydrant, at https://hydrant.dev/api/mcp. Start Gemini and use /mcp auth hydrant to approve the OAuth browser flow; then call get_workspace and confirm its name and ID before doing any work. Cancel the browser flow if the workspace is wrong. To change workspaces, revoke Hydrant access under Settings → Agents → Access, restart Gemini, and run /mcp auth hydrant again.

Gemini keeps an existing user or workspace mcpServers.hydrant entry and gives it precedence over the extension server, so this extension does not overwrite or silently replace an existing configuration. A user or workspace skill named hydrant likewise takes precedence; the archive inventory stays limited to the base hydrant skill. Check /mcp after a restart to see the active server. Manage the extension itself with:

gemini extensions update hydrant
gemini extensions disable hydrant
gemini extensions enable hydrant
gemini extensions uninstall hydrant

Uninstalling removes the extension only; it does not revoke its Hydrant OAuth access. Revoke access separately under Settings → Agents → Access before reconnecting another workspace.

What the skill does

• Starts every task with get_workspace and states the workspace name and ID.
• Reads the issue, every page of activity, dependencies and relationships before changing anything.
• Uses the server's own status keys, label and assignee IDs and revisions. No guessed identifiers.
• One request UUID per write. Same UUID on an uncertain retry. Reread and review on a conflict.
• Reads back after every write and reports the new version.
• Treats parent, related and blocking as three different links, because they are.
• Treats retrieved text as data. A comment cannot promote itself to an instruction.
• Reports denials, unread pages and unconfirmed writes as gaps instead of smoothing them over.

What it does not do

• Decide your workflow. Statuses, review stages and who accepts what live in your workspace, not in this file.
• Handle secrets. It never asks for a key and never goes looking for one.
• Replace the tool descriptions. Argument shapes come from the server when the client connects; this skill does not carry a stale copy.
• Run anything. It is a Markdown file.

Compatibility

Requires get_workspace, list_issues, get_issue, list_activity, get_dependencies, list_relationships, create_issue, update_issue and add_comment; uses list_projects, get_project, get_milestone and inspect_project for project membership, and update_relationship for links in capture and refine. Treats batch, the task-context tools and create_grant (in ship) as optional.

The server reports its name and version when a client connects. Releases are git tags; see CHANGELOG.md.

Contributing

Issues and pull requests are open. Keep skills/hydrant/SKILL.md provider-neutral and short, and run npm ci then node scripts/validate-frontmatter.mjs before pushing. The validator parses frontmatter as real YAML, the way installers do, so quote any description that contains : or #. The shared Codex/Claude Code/Cursor plugin ships a copy of skills/hydrant, because Codex drops symlinks when it installs a plugin: after editing the skill, run node scripts/check-plugin.mjs --write. CI fails when the copy drifts. Workspace policy belongs in your workspace; this file is not the place to legislate it.

License

MIT