relate skill

The relate skill command, which installs, lists, checks and removes the agent skill bundle embedded in the binary, with agents, paths and exit codes.

cliagents

relate skill manages the copies of relate's agent skill The SKILL.md cheat sheet and reference files a coding agent reads before it uses relate; relate skill install writes them. Read more in the glossary in the home directories of coding agents. The skill bundle The set of files that make up the relate skill: SKILL.md and 15 reference files, embedded in the binary and served by the site. Read more in the glossary (SKILL.md and 15 reference files) is embedded in the binary, so every action works offline. The command has four actions: install writes the bundle into each detected agent's skills directory, list prints each agent's install state, check compares installed copies with the binary's bundle, and remove deletes copies relate wrote. It never opens a store.

Synopsis

relate skill install|remove|list|check [--agent NAME] [--force]

Action	Does	Prints on stdout	Exit code on success
`install`	Writes the bundle into `<skills dir>/relate` for each target agent	`installed relate skill into <path>`, one line per agent	0
`list`	Reads each target agent's `<skills dir>/relate` and classifies it	`<agent>: <state> (<path>)`, one line per agent	0
`check`	Compares each installed copy with the binary's bundle, file by file	`<agent>: up to date (<path>)` or `<agent>: drifted (<path>)` with one line per differing file; agents without a copy get their `list` line	0 when every copy matches, 1 when any has drifted
`remove`	Deletes `<skills dir>/relate` for each target agent	`removed relate skill from <path>`, one line per agent	0

Without --agent, an action targets every detected agent. list and check write nothing.

Options

Flag	Argument	Default	Scope	Since	Description
`--agent`	`NAME`	all detected agents	`relate skill`	—	Scope the action to one agent (case-insensitive).
`--force`	—	`refuse`	`relate skill`	—	Clobber `<skills dir>/relate` even when the command would refuse it; a usage error on `list` and `check`.

A — under Since: the data does not record the release that added the flag.

Rule	Behavior
`--agent` names	Matched case-insensitively against the names in the agent table; given twice, the last one applies
`--agent` and detection	A named agent is a target whether or not its directory exists; `install --agent <name>` creates the skills directory
`--force`	Accepted by `install` and `remove` only; with `list` or `check` it is a usage error (exit code 2)

Agents and paths

An agent is detected when the directory in the "Detected when this exists" column exists. The skill goes to relate under the agent's skills directory. The names are the ones the binary prints in its valid agents: line, in its order.

`--agent`	Agent	Detected when this exists	The skill goes to
`claude-code`	Claude Code	`~/.claude`	`~/.claude/skills/relate`
`cursor`	Cursor	`~/.cursor`	`~/.cursor/skills/relate`
`windsurf`	Windsurf	`~/.codeium/windsurf`	`~/.codeium/windsurf/skills/relate`
`copilot`	Copilot	`~/.copilot`	`~/.copilot/skills/relate`
`antigravity`	Antigravity	`~/.gemini/antigravity`	`~/.gemini/antigravity/skills/relate`
`gemini-cli`	Gemini CLI	`~/.gemini`	`~/.gemini/skills/relate`
`cline`	Cline	`~/.cline`	`~/.agents/skills/relate`
`codex`	Codex	`~/.codex`	`~/.codex/skills/relate`
`pi`	Pi	`~/.pi/agent`	`~/.pi/agent/skills/relate`
`opencode`	OpenCode	`$XDG_CONFIG_HOME/opencode`	`$XDG_CONFIG_HOME/opencode/skills/relate`
`junie`	Junie	`~/.junie`	`~/.junie/skills/relate`

~ is $HOME. When XDG_CONFIG_HOME is unset or empty, OpenCode's paths use $HOME/.config in its place. A skills directory inside a project, such as .claude/skills/, is outside every action's reach.

Install states

list and check print one of four states for each agent's <skills dir>/relate. The state decides what install and remove may do without --force.

State	What is at the path	`install`	`remove`
`not installed`	Nothing	Writes the bundle	Succeeds; nothing to delete
`installed`	A directory with relate's `.relate-installed` marker file	Replaces the bundle	Deletes the directory
`installed (legacy bundle)`	A directory without the marker whose `SKILL.md` frontmatter has `name: relate` and a `version:` line: an older or hand-copied bundle	Replaces it and adds the marker	Refused
`foreign (not managed by relate)`	Anything else, including a symbolic link	Refused	Refused

A refusal names the path and exits with exit code The number a relate run returns to the shell; each nonzero value names a class of failure, such as 2 for usage, 5 for conflict, 6 for a rejected statement. Read more in the glossary 1. --force replaces or deletes the directory whatever its state.

What install writes

Item	Content
`SKILL.md`	The bundle's cheat sheet, with the binary's version written into its `version:` frontmatter line
`references/`	The 15 reference files, unchanged
`.relate-installed`	The marker that makes the directory relate's own

The bundle is written into a staging directory beside the destination and then renamed into place, so a reader never sees a half-written bundle; the previous copy is replaced whole, and a reference file the new bundle no longer has does not linger. With several targets, install and remove check every target's state before changing any, so a refusal on one agent leaves the others untouched.

check compares the bytes install would write. Each difference is one indented line: missing: <file>, differs: <file> or extra: <file>, with paths relative to the skill directory.

After relate upgrade replaces the binary, it runs relate skill install from the new binary for the detected agents. When any of them holds a relate copy, this happens without a prompt; when none does, it asks first on a terminal, installs without asking under --yes, and otherwise prints run: relate skill install and installs nothing. A foreign directory is never touched.

Errors and exit codes

Exit code	When
0	The action completed; for `check`, every installed copy matches
1	`check` found drift; no agent detected and no `--agent`; a refused path; a file system error
2	A usage error: no action, an unknown action or flag, `--force` with `list` or `check`, or an unknown `--agent` name

Message on stderr	Exit code	Cause
`Error: skill: no supported agents detected`	1	No `--agent`, and none of the directories in the agent table exists; a second line lists the valid names
`Error: skill: unknown agent: '<name>'`	2	`--agent` names no agent in the table; a second line lists the valid names
`Error: skill: refusing to touch <path>: no .relate-installed marker present (directory was not created by relate); pass --force to override`	1	`install` met a foreign directory, or `remove` met a foreign or legacy one
`Error: skill requires an action (install, remove, list or check)`	2	`relate skill` with no action
`Error: unexpected argument to skill: <argument>`	2	An unknown action or flag, or `--force` with `list` or `check`

The second line of the two agent errors is the same:

valid agents: claude-code, cursor, windsurf, copilot, antigravity, gemini-cli, cline, codex, pi, opencode, junie

The errors reference has the remedies.

Examples

The examples run with a fresh home directory, written <home>. With no agent directory in it, every action that has no --agent stops:

relate skill list
echo "exit=$?"

Error: skill: no supported agents detected
valid agents: claude-code, cursor, windsurf, copilot, antigravity, gemini-cli, cline, codex, pi, opencode, junie
exit=1

--agent installs for one agent, and creates its directory:

relate skill install --agent claude-code

installed relate skill into <home>/.claude/skills/relate

With a Codex directory present too, list reports both detected agents:

mkdir -p "$HOME/.codex"
relate skill list

claude-code: installed (<home>/.claude/skills/relate)
codex: not installed (<home>/.codex/skills/relate)

After a local edit to SKILL.md, check reports the drift and exits 1:

printf 'local note\n' >> "$HOME/.claude/skills/relate/SKILL.md"
relate skill check
echo "exit=$?"

claude-code: drifted (<home>/.claude/skills/relate)
  differs: SKILL.md
codex: not installed (<home>/.codex/skills/relate)
exit=1

remove deletes the copy that carries the marker:

relate skill remove --agent claude-code

removed relate skill from <home>/.claude/skills/relate