Using skills with your agent

Skills are agent-neutral behaviors rendered into each agent’s native instruction format. This page covers the per-agent specifics and walks one real change through the loops. Skills are static instructions the agent reads; the Agent Harness is the runtime that actually invokes the CLI on each edit. They write to separate files and never conflict, so you can run skills alone or pair them with the harness.

Per-agent targets

After install, the skills are just there; the agent picks them up from its instruction file on the next session. In Claude Code, shipmoor-review also responds to slash-style triggers like /shipmoor, /shipmoor-changed, /shipmoor-gate, and /shipmoor-explain.

The skills file is separate from the harness adapter files. The harness writes its own managed regions (.claude/settings.json for Claude and .cursor/hooks.json for Cursor), so installing both surfaces never touches the same bytes. See Agent Harness for the runtime side.

The agent needs the shipmoor binary on PATH (skills shell out to it; they contain no detection logic of their own). If your agent runs in a sandbox or CI, install the CLI there too: curl -fsSL https://dl.shipmoor.dev/install.sh | bash.

A worked loop

Here’s the shape of a real session (this mirrors our own end-to-end testing of shipmoor 0.5.1 with Claude Code on a Flask checkout):

1. The task. You ask the agent: “Add a helper that attaches a unique X-Request-ID header to a Flask response.” With shipmoor-agent-guard loaded, the agent checks the manifest before importing anything and avoids placeholder logic from the start.

2. The agent implements, then shipmoor-review kicks in before it declares done:

shipmoor scan --changed --fail-on high
# ✓ gate pass · 0 blockers  exit 0

3. The claim check. shipmoor-intent-contract records the task in .shipmoor/intent.yaml and runs the change-scoped claim check:

shipmoor scan --changed --intent "Add a helper that attaches a unique X-Request-ID header to a Flask response" \
  --json --output .shipmoor/report.json

If the diff backs up the task, the verdict says so. If the agent drifted (say the helper quietly logs request bodies instead of setting the header), Shipmoor catches the change that didn’t earn its claim and names the gap before any human reviews it. Where it has no probe for a part of the task, it says so rather than guessing. See Reading the verdict.

4. If something was found, shipmoor-fix drives the bounded repair loop:

shipmoor explain <finding-id> --from .shipmoor/report.json
# patch → re-scan → report before/after delta

5. Ready to ship. shipmoor-pr-preflight runs the merge-base diff with the gate and produces a PR note:

shipmoor scan --diff main...HEAD --fail-on high --markdown-summary pr-note.md

Agent-specific notes

• Claude Code: the richest target. The skill block in CLAUDE.md, the slash triggers, and (with the Agent Harness) native lifecycle hooks in .claude/settings.json scan after every edit. Skills and harness write separate managed regions and never conflict.
• Cursor: the skill block lives in .cursor/rules/shipmoor.md; the harness adds native afterFileEdit and stop hooks in .cursor/hooks.json for scan-on-change. See Agent Harness with Cursor.
• Codex: same skills bundle via AGENTS.md; the harness adds a wrapped runtime you launch as shipmoor harness codex -- <codex args>, which re-prompts Codex with findings inside a bounded loop.
• Aider: configured through .aider.conf.yml (with the .aider.shipmoor.yml include); the natural pairing is a lint-cmd running shipmoor scan --changed --fail-on high, so exit code 1 on a high finding drives Aider’s own repair loop.

The harness ships inside the shipmoor binary (bundled since 0.5.0) and is invoked as shipmoor harness <cmd>. A standalone shipmoor-harness console script survives as a recognized legacy alias for from-source installs, but shipmoor harness … is the supported entry point.

Next

• The five skills: each behavior in detail.
• Installing skills: the command surface and entitlement gating.
• Agent Harness: from static behavior to a runtime loop.
• Agent Harness with Claude Code: native hooks via .claude/settings.json.
• Agent Harness with Cursor: native hooks via .cursor/hooks.json.