Skip to main content

​
Overview

FastSkill integrates seamlessly with Cursor IDE to provide AI agents with access to a comprehensive skill registry. This enables Cursor’s AI to discover and utilize specialized tools and workflows automatically.
Cursor integration works through automatically generated markdown files that Cursor can read and understand for tool discovery.

​
How It Works

​
1. Skill Indexing

FastSkill indexes your skill repository: 
# Index skills with embeddings
fastskill reindex --skills-dir .claude/skills/

​
2. Markdown Generation

Creates Cursor-compatible documentation: 
# Generates: .claude/skills/.fastskill/skills.md
fastskill reindex --skills-dir .claude/skills/

​
3. Cursor Integration

Cursor reads the generated markdown file to understand available skills.

​
Configuration

​
Basic Setup

Create .fastskill.yaml in your project root: 
embedding:
  openai_base_url: "https://api.openai.com/v1"
  embedding_model: "text-embedding-3-small"

markdown_export:
  enabled: true
  output_path: ".cursor/rules/skills.md"
  header_instructions: |
    Skills are modular packages in `.claude/skills/<category>/<skill-name>/SKILL.md`
    that provide specialized workflows, tool integrations, and domain knowledge.
    Each SKILL.md contains YAML frontmatter (shown here: name, description) and
    full instructions with optional scripts/references/assets.
    Use the `description` field to identify relevant skills, then read the full
    SKILL.md at the path shown.
  fastskill_usage_instructions: |
    Use `fastskill search "query"` to search for skills semantically using embeddings.
    Use `fastskill reindex` to update the skill index and regenerate this file.

​
Cursor Rules File

Update your Cursor rules file (.cursor/rules/skills.mdc): 
---
alwaysApply: true
---
# Skills Registry

See `.cursor/rules/skills.md` for the complete list of available skills.

This file is automatically generated by FastSkill after running `fastskill reindex`.

​
Generated Output Format

​
File Location

The markdown export creates: 
.cursor/rules/skills.md

​
Content Structure

# Skills Registry

[Your header instructions from config]

[Your FastSkill usage instructions from config]

## Available Skills

| ID | Path | Description |
|----|------|-------------|
| airflow-ops | /workspaces/cogni/.claude/skills/dataops/airflow-ops | Comprehensive operational management for Airflow 3.1.0... |
| pptx | /workspaces/cogni/.claude/skills/product-management/pptx | Create professional PowerPoint presentations from text... |
| k8s-monitoring | /workspaces/cogni/.claude/skills/infra/k8s-monitoring | Monitor Kubernetes clusters and applications... |

​
Example Output

# Skills Registry

Skills are modular packages in `.claude/skills/<category>/<skill-name>/SKILL.md`
that provide specialized workflows, tool integrations, and domain knowledge.
Each SKILL.md contains YAML frontmatter (shown here: name, description) and
full instructions with optional scripts/references/assets.
Use the `description` field to identify relevant skills, then read the full
SKILL.md at the path shown.

Use `fastskill search "query"` to search for skills semantically using embeddings.
Use `fastskill reindex` to update the skill index and regenerate this file.

## Available Skills

| ID | Path | Description |
|----|------|-------------|
| airflow-ops | /workspaces/cogni/.claude/skills/dataops/airflow-ops | Comprehensive operational management for Airflow 3.1.0 including DAG monitoring, triggering DAGs with parameters, checking run status, filtering DAGs by tags, managing failed runs, scheduling queries, pause/unpause operations, and troubleshooting. Use this skill for any Airflow operational tasks (not DAG development/coding). |
| dag-development | /workspaces/cogni/.claude/skills/dataops/dag-development | Guidelines and best practices for creating Airflow DAGs including task dependencies, scheduling, error handling, testing strategies, and performance optimization. Use this skill for DAG development and coding tasks. |
| infra_k8s_ops | /workspaces/cogni/.claude/skills/infra/infra_k8s_ops | Comprehensive Kubernetes operational management including pod monitoring, deployment management, service discovery, ingress configuration, resource optimization, troubleshooting, and cluster administration. |

​
Setup Process

​
Step 1: Configure FastSkill

Create .fastskill.yaml: 
embedding:
  openai_base_url: "https://api.openai.com/v1"
  embedding_model: "text-embedding-3-small"

markdown_export:
  enabled: true
  output_path: ".cursor/rules/skills.md"
  header_instructions: |
    Skills are modular packages in `.claude/skills/<category>/<skill-name>/SKILL.md`
    that provide specialized workflows, tool integrations, and domain knowledge.
    Each SKILL.md contains YAML frontmatter and full instructions.
    Use the `description` field to identify relevant skills.
  fastskill_usage_instructions: |
    Use `fastskill search "query"` to search for skills semantically.
    Use `fastskill reindex` to update the skill index.

​
Step 2: Set API Key

export OPENAI_API_KEY="your-openai-api-key"

​
Step 3: Index Skills

fastskill reindex --skills-dir .claude/skills/

​
Step 4: Verify Output

# Check that file was created
ls -la .cursor/rules/skills.md

# View content
head -20 .cursor/rules/skills.md

​
Step 5: Update Cursor Rules

Create or update .cursor/rules/skills.mdc: 
---
alwaysApply: true
---
# Skills Registry

See `.cursor/rules/skills.md` for the complete list of available skills.

This file is automatically generated by FastSkill after running `fastskill reindex`.

​
How Cursor Uses the Skills

​
Tool Discovery

When you ask Cursor to perform a task, it:
  1. Reads the skills registry from .cursor/rules/skills.md
  2. Matches task requirements against skill descriptions
  3. Identifies relevant skills for the task
  4. Provides access to the full SKILL.md content

​
Example Usage

User Query: “Help me create a PowerPoint presentation for my quarterly review” Cursor Process:
  1. Scans skills registry for “presentation” or “powerpoint” related skills
  2. Finds relevant skills (pptx, presentation-tools, etc.)
  3. Accesses full SKILL.md content for implementation details
  4. Provides step-by-step guidance using the skill

​
Context Awareness

Cursor can now understand:
  • Available tools: What skills are installed
  • Skill capabilities: What each skill can do
  • Usage patterns: How to combine multiple skills
  • Implementation details: Specific instructions and parameters

​
Advanced Configuration

​
Custom Output Location

markdown_export:
  output_path: "docs/skills-registry.md"  # Custom location

​
Multiple Skill Directories

# Index multiple directories
fastskill reindex --skills-dir .claude/skills/
fastskill reindex --skills-dir ./custom-skills/

# Or use different output files
# Configure separate exports for each directory

​
Selective Export

Filter which skills to export: 
markdown_export:
  enabled: true
  output_path: ".cursor/rules/skills.md"
  # Add filtering options (future feature)
  include_categories: ["dataops", "infra"]  # Only export specific categories
  exclude_tags: ["deprecated"]              # Exclude certain tags

​
Automation

​
GitHub Actions Integration

Automatically update skills registry on changes: 
# .github/workflows/update-skills.yml
name: Update Skills Registry
on:
  push:
    paths:
      - '.claude/skills/**'
      - '.fastskill.yaml'
  pull_request:
    paths:
      - '.claude/skills/**'

jobs:
  update-skills:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install FastSkill
        run: cargo install --path tools/fastskill/rust/

      - name: Update skills registry
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: fastskill reindex --skills-dir .claude/skills/

      - name: Commit updated registry
        run: |
          git config --global user.name 'github-actions[bot]'
          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
          git add .cursor/rules/skills.md
          git commit -m 'Update skills registry' || echo "No changes to commit"
          git push

​
Pre-commit Hooks

Auto-update skills before commits: 
#!/bin/bash
# .git/hooks/pre-commit

# Update skills registry if skills changed
if git diff --cached --name-only | grep -q ".claude/skills/"; then
    echo "Skills changed, updating registry..."
    fastskill reindex --skills-dir .claude/skills/
    git add .cursor/rules/skills.md
fi

​
Troubleshooting

​
Common Issues

​
Skills file not generated

# Check configuration
cat .fastskill.yaml

# Verify API key
echo "API Key set: $(if [ -n "$OPENAI_API_KEY" ]; then echo 'Yes'; else echo 'No'; fi)"

# Run refresh manually
fastskill reindex --skills-dir .claude/skills/

​
Cursor not recognizing skills

# Check file exists and is readable
ls -la .cursor/rules/skills.md

# Verify content format
head -10 .cursor/rules/skills.md

# Check Cursor rules file
cat .cursor/rules/skills.mdc

​
Outdated skills registry

# Force refresh
fastskill reindex --skills-dir .claude/skills/ --force

# Check timestamps
ls -la .cursor/rules/skills.md

​
Debug Commands

# Check FastSkill configuration
fastskill --help

# Test search functionality
fastskill search "test query" --embedding false

# Verify index exists
ls -la .claude/skills/.fastskill/index.db

# Check generated file
wc -l .cursor/rules/skills.md

​
Performance Considerations

​
File Size

  • Small repositories: < 10KB
  • Medium repositories: 50-200KB
  • Large repositories: 500KB+

​
Generation Time

  • Small: < 5 seconds
  • Medium: 10-30 seconds
  • Large: 1-5 minutes

​
Update Frequency

  • On-demand: Update when skills change
  • Scheduled: Daily/weekly regeneration
  • Event-driven: Update on git push to skills directory

​
Integration Patterns

​
Multi-Environment Setup

# Development
markdown_export:
  output_path: ".cursor/rules/skills-dev.md"

# Production
markdown_export:
  output_path: ".cursor/rules/skills-prod.md"

​
Team Collaboration

Share skills registry across team: 
# Generate team-wide registry
markdown_export:
  output_path: "docs/team-skills.md"
  header_instructions: |
    Team Skills Registry - Updated $(date)
    This file contains all skills available to the development team.

​
Documentation Integration

Include in project docs: 
# Generate for docs site
markdown_export:
  output_path: "docs/skills/index.md"
  header_instructions: |
    # Available Skills

    This page lists all skills available in the project.

​
Future Enhancements

​
Planned Features

  • Filtered exports: Export only skills relevant to specific projects
  • Version tracking: Track skill versions and changes
  • Dependency mapping: Show skill relationships and dependencies
  • Usage analytics: Track which skills are most used
  • Collaborative editing: Allow team members to contribute skill updates

​
Custom Templates

Allow custom markdown templates: 
markdown_export:
  template: "custom-template.md"
  variables:
    project_name: "My Project"
    team: "Engineering"

​
Summary

FastSkill’s Cursor integration provides: ✅ Automatic skill discovery for AI agents ✅ Seamless integration with existing workflows ✅ Up-to-date documentation through automated generation ✅ Performance optimized for large skill repositories ✅ Flexible configuration for different use cases The integration bridges the gap between static skill definitions and dynamic AI agent capabilities, enabling Cursor to provide more intelligent and context-aware assistance.