quickstart.mdx

title	Quick Start Guide
description	First skills with FastSkill in minutes: install, manifest, add, install, reindex, search, optional serve.

Prerequisites

• The fastskill binary on your PATH (see Installation: Homebrew on macOS/Linux, Scoop on Windows, or release archives)
• OPENAI_API_KEY when you use embedding search or reindex

Five-minute setup (CLI)

1. Install the CLI

Follow Installation, then confirm:

fastskill -V

2. Create a manifest

Create skill-project.toml at your project root:

[dependencies]
demo-skill = { source = "local", path = "./skills/demo-skill", editable = true, groups = ["dev"] }

3. Add a skill

Pick the source that matches your workflow:

# From a public registry ID
fastskill add pptx@1.0.0

# From a local folder (editable for dev)
fastskill add ./skills/demo-skill -e --group dev

# From git with a branch
fastskill add https://github.com/org/skill.git --branch main

4. Install & index

fastskill install
fastskill reindex

5. Search & verify

fastskill search "text processing" --local --format json

You should see JSON results for installed skills. If empty, run `fastskill install`, then `fastskill reindex`, and search again.

6. Optional: serve UI

fastskill serve --port 8080

Browse http://localhost:8080/ for the bundled UI.

The HTTP API is available under /api/v1/…, e.g.:

• GET http://localhost:8080/api/v1/skills — list installed skills
• GET http://localhost:8080/healthz — liveness probe
• GET http://localhost:8080/readyz — readiness probe

Use-case quick recipes

• Install skills from different sources

  • Public registry ID: fastskill add pptx@1.0.0
  • Local folder (editable): fastskill add ./skills/my-skill -e --group dev
  • Git repo with branch: fastskill add https://github.com/org/skill.git --branch main
  • Private Git marketplace:

    fastskill repos add team --repo-type git-marketplace https://github.com/org/skills.git --priority 1
    fastskill install

• Add standard-compliant skills (SKILL.md only)

  # Create minimal skill
  mkdir my-first-skill
  cd my-first-skill
  
  cat > SKILL.md << 'EOF'
  ---
  name: my-first-skill
  description: A simple skill following the AI Agentic Skills Standard
  ---
  
  This is my first skill!
  EOF
  
  # Add it to fastskill
  fastskill add .

  FastSkill will:

  • Extract the skill ID from SKILL.md (name or metadata.id)
  • Extract version from SKILL.md (metadata.version or version, defaulting to 1.0.0)
  • Display a warning suggesting fastskill init to add skill-project.toml

Troubleshooting

• No skills found: ensure skill-project.toml exists at project root and rerun fastskill install.
• Search returns nothing: run fastskill reindex after adding or installing skills.
• Binary not on PATH: reinstall or move the binary to a directory in PATH (e.g., ~/.local/bin).