> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Install and manage Olostep skills in your AI coding agents

Install Olostep skill folders directly into your AI coding agents from the command line.

* Skills land in a canonical store (`~/.agents/skills`) and are symlinked or copied into each agent's skills directory
* Tracks all installs in a lockfile at `~/.agents/.skill-lock.json`
* Works with Cursor, Claude, Codex, Windsurf, Continue, and more

This feature is available via the [Olostep CLI](/sdks/cli).

## The skills

`olostep add skills` installs all 13. Each is a `SKILL.md` your agent reads to know **what** Olostep can do and **when** to use it.

Skills pair with the [MCP server](/integrations/mcp-server): the MCP server gives the agent the live *tools*, the skills give it the *know-how* for when and how to use them.

### Setup

Start here — teaches the agent how to configure the Olostep MCP server.

| Skill   | What it does                                              |
| ------- | --------------------------------------------------------- |
| `setup` | Configure the Olostep MCP server so all other skills work |

### Core web data

The main Olostep capabilities — use these to give your agent live web access.

| Skill            | What it does                                                  |
| ---------------- | ------------------------------------------------------------- |
| `scrape`         | Turn one URL into clean markdown / HTML / JSON / text         |
| `search`         | Live web search — results, answers, and in-site URL discovery |
| `answers`        | Cited, structured answers from live web data                  |
| `crawl`          | Autonomously crawl a whole site                               |
| `map`            | Discover every URL on a site                                  |
| `batch`          | Scrape up to 10,000 URLs in parallel                          |
| `extract-schema` | Scrape a page into structured JSON matching a schema          |

### Build & integrate

For agents helping developers add Olostep to a codebase or keep up with API changes.

| Skill          | What it does                                     |
| -------------- | ------------------------------------------------ |
| `integrate`    | Auto-install the Olostep SDK into a project      |
| `docs-to-code` | Scrape API docs and write working code from them |
| `migrate-code` | Read a migration guide and update local code     |

### Research & debug

For agents doing research, making decisions, or debugging code errors.

| Skill         | What it does                                             |
| ------------- | -------------------------------------------------------- |
| `research`    | Cited, comparative web research for a decision           |
| `debug-error` | Look up an error message against live GitHub / SO / docs |

### Categories

Every skill belongs to one of three categories, which map to the `--category` flag:

* **`usage`** — use Olostep's features: `scrape`, `search`, `answers`, `crawl`, `map`, `batch`, `extract-schema`.
* **`build`** — install and integrate Olostep into a codebase: `setup` (configure the MCP server) and `integrate` (add the Olostep SDK to a project).
* **`workflow`** — produce a deliverable with Olostep: `research`, `docs-to-code`, `migrate-code`, `debug-error`.

Install just one category:

```bash theme={null}
olostep add skills --category usage      # core web-data skills
olostep add skills --category build      # setup + integration skills
olostep add skills --category workflow   # research + deliverable skills
```

### Hosted copies

Each installed skill also references its hosted copy at `https://www.olostep.com/skills/<name>/SKILL.md` — an agent with web access can fetch the latest version (which may include capabilities added since install) and falls back to the local copy otherwise. Browse all hosted skills at [olostep.com/skills](https://www.olostep.com/skills/index.md).

## Install

```bash theme={null}
npm install -g olostep-cli

# Install all 13 skills into every detected agent
olostep add skills

# Or use the skills subcommand (alias)
olostep skills install
```

Or without installing the CLI:

```bash theme={null}
npx -y olostep-cli@latest add skills
```

## Common usage

```bash theme={null}
# Install all skills
olostep skills install

# Refresh / update to latest
olostep skills update

# See what's installed and where
olostep skills list

# Remove all skills
olostep skills uninstall
```

Filter what gets installed:

```bash theme={null}
# Only core web-data skills
olostep add skills --category usage

# Only setup + integration skills
olostep add skills --category build

# Cherry-pick
olostep add skills --skill scrape --skill search --skill setup

# Specific agents only
olostep add skills --agent cursor --agent claude

# Machine-readable output
olostep add skills --json
```

## Options reference

| Option                              | Default            | Description                                                |
| ----------------------------------- | ------------------ | ---------------------------------------------------------- |
| `--login`                           | —                  | Run browser login before installing                        |
| `--source <path>`                   | CLI bundled skills | Skills source directory                                    |
| `--cli-local-dir <path>`            | CLI/skills         | Directory where source skills are synced for CLI-local use |
| `--agent <name>`                    | —                  | Target a specific agent — repeatable                       |
| `--all-agents` / `--no-all-agents`  | `--all-agents`     | Target all detected agents                                 |
| `--global` / `--no-global`          | `--global`         | Install into global agent skill dirs                       |
| `--canonical-dir <path>`            | `~/.agents/skills` | Canonical storage location                                 |
| `--agent-skills-dir <path>`         | —                  | Custom target dir (requires `--no-global`)                 |
| `--skill <name>`                    | —                  | Include only this skill — repeatable                       |
| `--exclude <name>`                  | —                  | Exclude this skill — repeatable                            |
| `--category`                        | —                  | `usage`, `build`, or `workflow`                            |
| `--overwrite` / `--no-overwrite`    | `--overwrite`      | Replace existing installs                                  |
| `--link-mode <auto\|symlink\|copy>` | `auto`             | `auto` tries symlink first, falls back to copy             |
| `--json`                            | —                  | Machine-readable JSON output                               |

<Note>
  **Validation rules:**

  * `--link-mode` must be `auto`, `symlink`, or `copy`
  * `--agent-skills-dir` requires `--no-global`
  * `--no-global` requires `--agent-skills-dir`
  * Unknown agent names will error
  * An empty skill selection after `--skill` / `--exclude` will error
</Note>

### JSON output shape

When `--json` is passed, the output looks like:

```json theme={null}
{
  "sync": {
    "plugin_source_dir": "/path/to/CLI/skills",
    "cli_local_dir": "/path/to/CLI/skills"
  },
  "selected_skills": ["scrape", "search"],
  "canonical_dir": "~/.agents/skills",
  "lockfile_path": "~/.agents/.skill-lock.json",
  "installed": [
    {
      "skill": "scrape",
      "canonical_path": "~/.agents/skills/olostep-scrape",
      "targets": [
        { "agent": "cursor", "mode": "symlink", "path": "~/.cursor/skills/olostep-scrape" },
        { "agent": "claude", "mode": "symlink", "path": "~/.claude/skills/olostep-scrape" }
      ]
    }
  ]
}
```

## Supported agents

| Agent    | Key        |
| -------- | ---------- |
| Cursor   | `cursor`   |
| Claude   | `claude`   |
| Codex    | `codex`    |
| Windsurf | `windsurf` |
| Continue | `continue` |
| Augment  | `augment`  |
| Roo      | `roo`      |
| Gemini   | `gemini`   |
| Copilot  | `copilot`  |
| Factory  | `factory`  |

Use `--all-agents` (the default) to target all detected agents, or `--agent <key>` for specific ones.

## `olostep list skills`

See which skills are installed and into which agents — without digging through files.

```bash theme={null}
olostep list skills            # human-readable summary
olostep list skills --json     # machine-readable
```

## `olostep remove skills`

Removes Olostep-installed skill folders from the canonical store and agent skill directories, and cleans up the lockfile.

```bash theme={null}
# Remove all Olostep skills from all agents
olostep remove skills

# Remove a specific skill
olostep remove skills --skill research

# Remove from a specific agent only
olostep remove skills --agent cursor

# Machine-readable JSON output
olostep remove skills --json
```

| Option                             | Default            | Description                                      |
| ---------------------------------- | ------------------ | ------------------------------------------------ |
| `--agent <name>`                   | —                  | Remove only from specified agent(s) — repeatable |
| `--all-agents` / `--no-all-agents` | `--all-agents`     | Target all detected agents                       |
| `--canonical-dir <path>`           | `~/.agents/skills` | Canonical skills directory to remove from        |
| `--agent-skills-dir <path>`        | —                  | Custom target skills directory for removal       |
| `--skill <name>`                   | —                  | Remove only matching skill(s) — repeatable       |
| `--json`                           | —                  | Machine-readable JSON output                     |

<Note>
  **Safety:** Only folders with the `olostep-` prefix are touched. Non-Olostep skill folders in agent directories are never modified. Lockfile cleanup only removes `olostep-`-prefixed keys.
</Note>

## Skill discovery and format

Skills are discovered by scanning subdirectories for a `SKILL.md` file. The file must include a YAML frontmatter block with `name` and `description` fields. Duplicate sanitized names are rejected.

```markdown theme={null}
---
name: my-skill
description: What this skill does and when to use it
---

# My Skill

...skill instructions here...
```

## Naming convention

Installed folders always use the `olostep-` prefix — e.g. `research` becomes `olostep-research`. Names are sanitized to lowercase with invalid characters replaced by `-`. This prefix keeps Olostep-managed skills clearly identifiable and prevents conflicts with other tools.

## Related

* [CLI reference](/sdks/cli) — full command documentation
* [MCP Server](/integrations/mcp-server) — give your agent live Olostep tools