Installation

The SpecStory CLI is the only thing that can install a skill onto your machine. The cloud delivers a skill as a single SKILL.md body; the CLI writes it to disk and links it into each of your coding agents.

Prerequisites

# Install the CLI (if you haven't)
brew tap specstoryai/tap && brew trust specstoryai/tap && brew install specstory

# Log in (skills require a Pro or Team plan + Cloud login)
specstory login

Make sure at least one terminal agent is installed (Claude Code, Codex, Cursor, Gemini, or Droid). The CLI auto-detects which agents you have and only installs to the ones present.

The interactive way: specstory skills

specstory skills

Opens a Bubble Tea TUI with two tabs — Library and Run Activity — mirroring the web page. In the Library tab you can browse, filter, search, approve/dismiss Review skills, and install Ready skills through a live install panel where you pick:

• Scope — global (~/.agents/skills) or project (<cwd>/.agents/skills).
• Target agents — which of your detected agents to install into (all by default).

Keys are the same idea as the resume TUI: arrow keys to move, enter to expand/act, q to quit.

The direct way: subcommands

Every action is also a non-interactive subcommand with --json output for scripting and editor integration (the VS Code extension drives the same engine by shelling out).

specstory skills pull <name> (the command the web page's Pull button copies) is an alias for install.

Install a skill

# Install to all detected agents, globally
specstory skills install my-skill

# Install to a specific agent only
specstory skills install my-skill --agent claude-code

# Install to the current project instead of globally
specstory skills install my-skill --project

What happens on disk

The install follows the same layout as npx skills, so the two interoperate:

1. Canonical copy — the SKILL.md is written to .agents/skills/<name>/ (global: ~/.agents/skills/, project: <cwd>/.agents/skills/).
2. Symlinked into each agent — a relative symlink (or copy, on filesystems without symlink support) is created in each target agent's skills directory. "Universal" agents (Codex, Cursor) read the canonical store directly, so no symlink is needed.
3. Lock entry — the CLI records the install in a local lock file, capturing the name, scope, target agents, and the cloud contentSha of the installed version.
4. Cloud state flip — the CLI calls the cloud to mark the skill's install state as installed, which is what makes the web page show the green Installed badge.

Supported agents

Only agents whose config directories are detected are targeted — the CLI never creates an agent's config tree just to install a skill.

Uninstall

specstory skills uninstall my-skill

Reverses the install: removes the symlinks, the canonical directory, the lock entry, and flips the cloud install state back to available. The skill returns to Ready in your library.

Drift

If the cloud re-mines and a skill's SKILL.md changes after you installed it, the CLI detects the mismatch (the cloud contentSha no longer matches your lock entry) and surfaces a drift badge in specstory skills status and specstory skills list. The web page shows the same signal as a recommendation on the skill row.

Reinstalling syncs them again:

specstory skills install my-skill

Verify an install

# What's installed locally + drift status
specstory skills status

# Check the skills directory directly
ls .agents/skills/
ls ~/.claude/skills/

Or just ask your agent:

"What SpecStory skills do I have installed?"

Customizing an installed skill

Installed skills are plain SKILL.md files on disk. You can edit them directly in .agents/skills/<name>/SKILL.md to customize for your needs. Note that reinstalling will overwrite local edits with the cloud version — if you've customized a skill, keep a copy or skip reinstalling it.