# Install & update the skill

Download the canonical Semel skill, install it into your harness, verify its checksum, and keep it current with fail-closed managed updates.

The Semel skill (`semel-bootstrap`) teaches your agent the workflow. The supported path downloads a small installer from the public docs site, lets you inspect it before execution, and installs a content-addressed skill only after its signed release identity and bytes pass verification.

## Download
<a id="download"></a>

Save the public installer, inspect the saved file, and read its help before running it. Do not use a `curl | node` pipeline: inspection is part of the supported trust path.

**Public installer**

```bash
curl -fsSLo semel-install.mjs https://docs.semel.ai/downloads/semel-install.mjs
less semel-install.mjs
node semel-install.mjs --help
```

The installer reads the production manifest at `https://mcp.semel.ai/.well-known/semel-skill.json`. That manifest names the immutable skill URL, version, protocol range, SHA-256, signed release statement, and key ID. The installer accepts only HTTPS artifact URLs and a publisher key pinned in its own source.

## Install into your harness
<a id="install-location"></a>

Choose the absolute `SKILL.md` path your harness loads, then pass it explicitly. The same installer supports exactly `codex` and `claude`; it never guesses a home directory or copies into several harnesses at once. `--manifest-url` names the signed release to install; omit it and the installer defaults to production.

**Install to Codex or Claude Code**

```bash
node semel-install.mjs --harness codex --path ~/.codex/skills/semel/SKILL.md --manifest-url https://mcp.semel.ai/.well-known/semel-skill.json
node semel-install.mjs --harness claude --path ~/.claude/skills/semel/SKILL.md --manifest-url https://mcp.semel.ai/.well-known/semel-skill.json
```

Run one line for the harness and path you chose (substitute your real skills directory if you use a custom location). After installation, start a new harness session, invoke `/semel`, and as a first check ask it to list your Semel briefs to confirm the connection. OpenClaw, Cursor, generic MCP clients, and guessed shared install locations are outside this installer’s launch-supported contract.

## Codex recovery helper
<a id="recovery-helper"></a>

Codex users should also install the `semel-codex-reauth` recovery helper, which re-establishes Codex/Conductor authentication when it lapses. Unlike the skill, the helper is **not** part of the signed release — it is distributed over HTTPS and verified by its published SHA-256, so verify it explicitly before use. Download it over HTTPS, compare its checksum to the `cliSha256` value in the app manifest, then place it on your PATH. Do not run any shell installer for this — a shell installer would overwrite the signed `SKILL.md`.

**Install the recovery helper (Codex)**

```bash
curl -fsSLo semel-codex-reauth.mjs https://app.semel.ai/semel/semel-codex-reauth.mjs
shasum -a 256 semel-codex-reauth.mjs
# Compare with "cliSha256" in https://app.semel.ai/semel/manifest.json, then:
install -m 0755 semel-codex-reauth.mjs ~/.local/bin/semel-codex-reauth
```

## Version & protocol compatibility
<a id="compatibility"></a>

The skill declares the protocol majors it supports. Semel’s protocol is at **major 1** today. A skill outside the supported major fails discovery with `PROTOCOL_VERSION_UNSUPPORTED`; update it via the managed updater below. The [Versioning & changelog](https://docs.semel.ai/changelog) page tracks the current skill and protocol versions.

## Verify the checksum
<a id="verify"></a>

The installer performs the required verification itself: Ed25519 signature over the release statement, statement/manifest identity, supported protocol major, downloaded-byte SHA-256, and a skill frontmatter smoke check. For an independent byte check, compare the installed file to the manifest:

**Verify SHA-256**

```bash
curl -fsSLo semel-skill-manifest.json https://mcp.semel.ai/.well-known/semel-skill.json
shasum -a 256 /absolute/path/to/skills/semel/SKILL.md
# Compare with the manifest "sha256" after also verifying its publisher signature.
```

## Managed updates, uninstall & rollback
<a id="updates"></a>

Managed updates are fail-closed. A verified candidate is written to a staging file and activated atomically. An existing installer-managed copy is backed up; a custom local copy is refused unless an operator deliberately passes `--allow-custom` after preserving changes. Signature, network, hash, compatibility, smoke, or activation failure keeps or restores the prior copy. `--active-pinned-session` defers without network or filesystem changes. `--preference` accepts `update_now`, `always_current`, `snooze`, or `disabled`. To uninstall, remove the chosen `SKILL.md` plus its adjacent `.semel-release.json` and `.semel-update-preference.json` metadata after ending active sessions.

> **Caution:** A `failed_restore` outcome needs operator attention and reports the preserved backup paths. Do not delete those files or retry with `--allow-custom`; restore the last verified copy first.

Canonical page: https://docs.semel.ai/install