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

# Cursor Integration

> Integrate FastSkill with Cursor IDE for intelligent skill discovery and tool recommendations.

## Overview

Cursor discovers skills **directly** from the skills directory (`.claude/skills/` by default)
and via the FastSkill MCP server. FastSkill's job is to install the right skills onto disk and
keep them reconciled with your manifest — there is no metadata file to generate or keep in sync.

<Info>
  Modern agents (Cursor, Claude Code, …) read installed skills from the skills directory natively.
  Just `fastskill install` (or `fastskill add`) and the skills are available. Register the MCP
  server below for richer, tool-based access from inside Cursor.
</Info>

## Quick start

```bash theme={null}
# 1. Install the skills declared in skill-project.toml
fastskill install

# 2. Verify what is on disk
fastskill list

# 3. (Optional) Build the local index for semantic search
fastskill reindex --skills-dir .claude/skills/
```

## MCP registration

Register `fastskill` as an MCP server inside Cursor with a single command:

```bash theme={null}
# Register for the current project (stdio transport, recommended)
fastskill mcp install --agent cursor --stdio --scope project --overwrite

# Preview the config change without writing any files
fastskill mcp install --agent cursor --stdio --dry-run
```

After running the command, reload Cursor. The tools exposed by
`fastskill mcp serve --transport stdio` will be callable from the agent.

> **Deprecated:** Manually editing `.cursor/mcp.json` to add a `fastskill` MCP entry is
> deprecated. Use `fastskill mcp install` instead.

## How Cursor uses the skills

When you ask Cursor to perform a task, it:

1. **Reads available skills** from the skills directory (and the FastSkill MCP server, if
   registered).
2. **Matches task requirements** against each skill's `description` frontmatter.
3. **Loads the full `SKILL.md`** for relevant skills to get instructions and parameters —
   the same content `fastskill read <skill-id>` prints.

### Example

**User query:** *"Help me create a PowerPoint presentation for my quarterly review."*

Cursor scans installed skills for presentation-related descriptions, finds a match (e.g.
`pptx`), loads its `SKILL.md`, and follows the skill's instructions to complete the task.

## Configuration

Ensure your project has a `skill-project.toml` and that Cursor and FastSkill agree on the
skills directory. The default is `.claude/skills/`; override it via `skills_directory` in
`.fastskill/config.yaml` or the `--skills-dir` flag.

```bash theme={null}
fastskill install
fastskill list
```

### Multiple skill directories

```bash theme={null}
fastskill reindex --skills-dir .claude/skills/
fastskill reindex --skills-dir ./custom-skills/
```

## Automation

Keep the skills directory reconciled in CI so commits always carry the resolved skill set:

```yaml theme={null}
# .github/workflows/reconcile-skills.yml
name: Reconcile skills
on:
  push:
    paths:
      - 'skill-project.toml'
      - 'skills.lock'

jobs:
  install-skills:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install FastSkill CLI
        run: |
          # Add the steps your org uses to place `fastskill` on PATH (release tarball, package, etc.)
          fastskill -V
      - name: Install skills from lock
        run: fastskill install --lock
      - name: Verify
        run: fastskill list
```

## Troubleshooting

**Cursor doesn't see a skill**

```bash theme={null}
# Confirm it is installed and reconciled
fastskill list

# Confirm its content is readable
fastskill read <skill-id>
```

**Semantic search returns nothing**

```bash theme={null}
# Reindex (requires an embedding provider; see `fastskill doctor`)
fastskill reindex --skills-dir .claude/skills/

# Keyword fallback works without a provider
fastskill search "test query" --local --embedding false
```

**Check environment readiness**

```bash theme={null}
fastskill doctor
```

## Summary

FastSkill's Cursor integration provides:

* **Direct skill discovery** — Cursor reads installed skills from the skills directory, no sync step
* **MCP access** — register the FastSkill MCP server for tool-based access inside Cursor
* **Reproducible installs** — `skill-project.toml` + `skills.lock` keep the skill set consistent across the team
* **Optional semantic search** — `fastskill reindex` + `fastskill search --local` when an embedding provider is configured