docs

Quickstart

Install the skill, point your harness at the production MCP endpoint, authenticate, verify tool discovery, and complete your first useful action — per supported harness.

View as Markdown
On this page

This takes about five minutes. Pick your harness below. Every path ends at the same first useful action: create a Build Brief from a Linear issue. Launch-supported harnesses are Claude Code and Codex; other MCP clients are experimental.

Prerequisites

  • A Semel workspace and browser sign-in.
  • Node.js 20 or newer for the inspectable installer.
  • A launch-supported harness installed locally: Claude Code or Codex.
  • An absolute, operator-chosen path for the skill file. The installer deliberately does not guess it.
  • The stable production MCP endpoint shown below:
Production MCP endpoint
https://mcp.semel.ai/mcp

This stable public resource is also the OAuth audience. Deployment-specific hosts are kept out of public documentation.

Download, inspect, and install the skill

Download and inspect
curl -fsSLo semel-install.mjs https://docs.semel.ai/downloads/semel-install.mjs
less semel-install.mjs
node semel-install.mjs --help
Run one explicit install
node semel-install.mjs --harness codex --path /absolute/path/to/skills/semel/SKILL.md
# Or: --harness claude --path /absolute/path/to/skills/semel/SKILL.md

Do not pipe the installer into Node. The saved installer fetches https://mcp.semel.ai/.well-known/semel-skill.json, verifies the pinned Ed25519 publisher signature, protocol range, SHA-256, and skill metadata, then activates the file atomically. See Install & update for update and rollback behavior.

Claude Code

1. Add Semel as an HTTP MCP server. This registers the endpoint; Claude Code runs the OAuth flow on first use.

Claude Code
claude mcp add --transport http --scope user semel https://mcp.semel.ai/mcp

2. Authenticate. Run claude mcp login semel, finish the Semel consent screen in your browser, and approve only the scopes this journey needs. Registration status is not proof that the running model session has tools.

3. Reload Claude Code after installation or authentication, then verify the live tools below.

Codex

1. Add the MCP server with the canonical OAuth resource:

Codex
codex mcp add semel --url https://mcp.semel.ai/mcp --oauth-resource https://mcp.semel.ai/mcp

2. Authenticate with the minimum first-brief scopes, finish consent in your browser, then restart the Codex session so the live tool inventory enters model context.

Codex OAuth
codex mcp login semel --scopes brief:read,brief:write

Verify tool discovery

Run claude mcp get semel or codex mcp get semel to inspect registration, then start a fresh session and ask the agent to make the live read-only calls project_list and brief_list. Readiness requires MCP initialize, Semel serverInfo, non-empty tools/list, and the needed tools exposed to this model session. The Tool reference shows the current catalog.

An empty or partial tool list means setup is incomplete — usually authentication did not finish or the endpoint is wrong. See Troubleshooting → tools missing after setup.

First action: create a Build Brief from a Linear issue

This is the lowest-friction, visible-value write — it needs brief:read and brief:write. Paste the issue text so the flow is self-contained; a Linear URL works only when your harness already has authorized Linear access.

Say to your agent
Create a Build Brief from this pasted issue.

Title: Retry failed invoice payments
Problem: Customers cannot tell whether a retry is scheduled.
Acceptance: Show the next retry time and send a receipt after success.

The agent first uses project_list to avoid a substantially overlapping effort. After you confirm the new project name and target, it calls project_create and brief_create, binding each later argument from the preceding structuredContent. Open the resulting brief in Semel. Continue with the exact state-aware paths in Recipes.

Other MCP clients

Generic standards-based MCP clients and OpenClaw are experimental at launch. Use the same production endpoint and one of Semel’s two authentication modes, but do not assume install locations, refresh-token behavior, or session reload semantics from the Claude Code and Codex instructions.