Skip to content

installation.mdx

Latest commit

 

History

History
232 lines (162 loc) · 8.27 KB

installation.mdx

File metadata and controls

232 lines (162 loc) · 8.27 KB
Raw
title Installation Guide
description Install the FastSkill CLI: package manager and operational toolkit for Agent AI Skills (releases, installers, optional source build).

System Requirements

Before installing FastSkill, ensure your system meets these requirements:

Component Minimum Version Recommended
OS macOS, Linux, or Windows Latest stable release
Memory 512MB 2GB+
Storage 100MB 500MB+
OpenAI API Key Optional Required for embedding search / reindex with embeddings

CLI Installation

Pick one method. Homebrew (macOS and Linux) and Scoop (Windows) stay updated with releases; use GitHub Releases or the install script if you prefer a standalone binary.

<Tabs items={['Homebrew (macOS & Linux)', 'Scoop (Windows)', 'Install script (Linux & macOS)', 'GitHub Releases']}>

Homebrew installs a pre-built fastskill on both Apple Silicon and Intel Macs, and on Linux where the tap ships bottles.

brew install gofastskill/cli/fastskill
fastskill -V

Details and formula updates live in the gofastskill/homebrew-cli tap repository.

If `brew install` fails with a tap error, run `brew update` and try again, or use the **GitHub Releases** or **install script** tab.

Scoop installs fastskill.exe and keeps it on your PATH.

scoop bucket add gofastskill https://github.com/gofastskill/scoop-bucket
scoop install fastskill
fastskill -V

See gofastskill/scoop-bucket for manifest details.

One-liner from the repository (detects OS, downloads a release binary, installs to /usr/local/bin or ~/.local/bin if sudo is not available):

curl -fsSL https://raw.githubusercontent.com/gofastskill/fastskill/main/scripts/install.sh | bash

Options (run ./install.sh --help after downloading the script): --user, --prefix DIR, --force, and a version argument such as ./install.sh v0.9.16.

Download a pre-built binary from GitHub Releases. Replace VERSION with the tag you want (for example 0.9.16; assets use v${VERSION} in the URL).

1. macOS (Apple Silicon)

VERSION="0.9.16"
curl -fL "https://github.com/gofastskill/fastskill/releases/download/v${VERSION}/fastskill-aarch64-apple-darwin.tar.gz" -o fastskill.tgz
tar -xzf fastskill.tgz
sudo mv fastskill /usr/local/bin/
fastskill -V

Asset name: fastskill-aarch64-apple-darwin.tar.gz.

2. macOS (Intel)

VERSION="0.9.16"
curl -fL "https://github.com/gofastskill/fastskill/releases/download/v${VERSION}/fastskill-x86_64-apple-darwin.tar.gz" -o fastskill.tgz
tar -xzf fastskill.tgz
sudo mv fastskill /usr/local/bin/
fastskill -V

Asset name: fastskill-x86_64-apple-darwin.tar.gz.

3. Linux (x86_64, glibc, with git support)

VERSION="0.9.16"
curl -fL "https://github.com/gofastskill/fastskill/releases/download/v${VERSION}/fastskill-x86_64-unknown-linux-gnu.tar.gz" -o fastskill.tgz
tar -xzf fastskill.tgz
sudo mv fastskill /usr/local/bin/
fastskill -V

Requires a recent glibc (see release notes). For maximum portability (static binary, no bundled git2), use fastskill-x86_64-unknown-linux-musl.tar.gz instead and rely on system git for Git URLs.

4. Windows (zip)

Download fastskill-x86_64-pc-windows-msvc.zip from the release page, extract it, add the folder to PATH, then run:

fastskill.exe -V
Prefer a user-local path on macOS or Linux? Move `fastskill` to `~/.local/bin/` and ensure that directory is on your `PATH` instead of using `sudo`.

Skills Directory Resolution:

The CLI automatically discovers the skills directory in this priority order:

  1. skills_directory setting in .fastskill/config.yaml
  2. Walk up directory tree to find existing .claude/skills/
  3. Default to .claude/skills/ in current directory

Manifests and lockfiles:

  • Declare skills in skill-project.toml at project root (with [dependencies] section)
  • Install with fastskill install (use --without/--only for groups)
  • Lockfile is written to skills.lock at project root after installs
  • Repository configuration is stored in [tool.fastskill.repositories] section of skill-project.toml

Configuration

After installation, configure FastSkill by creating .fastskill/config.yaml:

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

# Optional: Custom skills directory
skills_directory: ".claude/skills"

Note: Service-level configuration (embedding settings) is stored in .fastskill/config.yaml. Project-level configuration (skill dependencies and repositories) is stored in skill-project.toml at your project root.

Set your OpenAI API key:

export OPENAI_API_KEY="your-key-here"

Docker (optional)

If you run tools in containers, install the same release archive inside your image (see the Linux steps above) or copy the fastskill binary into a minimal base image. Mount your project directory and set OPENAI_API_KEY when you use embedding search.

Platform notes

macOS

  • Recommended: Homebrew tab above (brew install gofastskill/cli/fastskill) for both Apple Silicon and Intel.
  • Without Homebrew: use the GitHub Releases tab for aarch64 vs x86_64 darwin archives, or the install script tab.

Linux

  • Recommended: Homebrew on Linux if you already use it, otherwise the GitHub Releases tab (gnu vs musl per release notes) or the install script.

Windows

  • Recommended: Scoop tab above.
  • Without Scoop: download the zip from GitHub Releases, extract, add to PATH.
  • WSL: install inside Ubuntu using the Linux or install-script options above.

Verify the CLI

fastskill -V
fastskill --help

If you already have a project with skill-project.toml, try fastskill list or fastskill install from that directory.

Troubleshooting

**Homebrew**: If the tap is missing, install with `brew install gofastskill/cli/fastskill`. See [homebrew-cli](https://github.com/gofastskill/homebrew-cli) for issues. **Scoop**: Ensure the bucket was added (`scoop bucket list` should show `gofastskill`). See [scoop-bucket](https://github.com/gofastskill/scoop-bucket) if `scoop install fastskill` fails. **Binary not found in PATH**: After extracting a release archive, move `fastskill` (or add the folder containing `fastskill.exe`) to a directory on your PATH (`/usr/local/bin`, `~/.local/bin`, or Windows user PATH). **Permission denied (Linux)**: If you get permission errors, use `sudo` when moving to `/usr/local/bin/`, or install to `~/.local/bin/` instead and ensure it's in your PATH. **Windows security warning**: Windows may show a security warning for unsigned binaries. Click "More info" and then "Run anyway" if you trust the source. **Embedding configuration required**: Create `.fastskill/config.yaml` with OpenAI API configuration. **OpenAI API key not found**: Set `OPENAI_API_KEY` environment variable or configure in `.fastskill/config.yaml`. **macOS security**: If you get security warnings, go to System Settings > Privacy & Security and allow the binary. **Windows antivirus**: If Windows blocks the downloaded binary, add an exception for the folder where you keep `fastskill.exe`. Still having issues? Check the [troubleshooting section](/troubleshooting).