install Command

Install skills from skill-project.toml [dependencies] section into .claude/skills/. Creates or updates skills.lock for reproducible installations.

Usage

fastskill install [OPTIONS]

Options

Option	Description	Default
`--without <GROUPS...>`	Exclude skills from these groups (like poetry —without dev)	None
`--only <GROUPS...>`	Only install skills from these groups	None
`--lock`	Install from `skills.lock` (exact versions) instead of resolving from `skill-project.toml`	`false`

Examples

Install All Dependencies

Install all skills declared in skill-project.toml:

fastskill install

This:

Reads dependencies from skill-project.toml at project root
Resolves skills from configured repositories
Installs skills into .claude/skills/
Creates or updates skills.lock with exact versions

Install Without Dev Skills

Install production skills only, excluding dev group:

fastskill install --without dev

This is useful for CI/CD pipelines where you want lean production deployments without development dependencies.

Install Only Specific Groups

Install only skills from specific groups:

# Install only production skills
fastskill install --only prod

# Install only development tools
fastskill install --only dev

# Install multiple groups
fastskill install --only prod test

Reproducible Installation

Install exact versions from skills.lock:

fastskill install --lock

Use --lock for production deployments to ensure you install the exact same versions that were used in development.

Combined Example: Production Deployment

Install production skills with exact versions:

# 1. Commit both skill-project.toml and skills.lock
git add skill-project.toml skills.lock
git commit -m "Lock dependency versions"

# 2. Deploy with locked versions
fastskill install --lock --without dev

Behavior

The install command:

Locates Project File: Finds skill-project.toml at project root or walks up directory tree
Loads Dependencies: Reads [dependencies] section from skill-project.toml
Applies Group Filters: Filters dependencies based on --without and --only flags
Resolves Skills: For each dependency:
- If --lock is set: Resolves exact versions from skills.lock
- Otherwise: Resolves latest compatible versions from repositories
Installs Skills: Downloads and installs skills into .claude/skills/
Updates Lockfile: Writes exact versions to skills.lock at project root

Dependency Groups

Skills can be organized into groups for selective installation. Specify groups in skill-project.toml:

skill-project.toml

[dependencies]
# Production skills
web-scraper = { source = "git", url = "https://github.com/user/web-scraper.git", groups = ["prod"] }
data-processor = { source = "registry", id = "data-processor", groups = ["prod"] }

# Development tools
demo-skill = { source = "local", path = "./skills/demo-skill", editable = true, groups = ["dev"] }
test-helper = { source = "git", url = "https://github.com/user/test-helper.git", groups = ["dev", "test"] }

# Testing utilities
mock-skill = { source = "registry", id = "mock-skill", groups = ["test"] }

If no groups are specified, the skill belongs to no groups and will always be installed.

Default Group Behavior

# Without groups - always installed
web-scraper = { source = "git", url = "https://github.com/user/web-scraper.git" }

# With groups - filtered by --without/--only
dev-tool = { source = "git", url = "https://github.com/user/dev-tool.git", groups = ["dev"] }

Skills Lock File

The skills.lock file ensures reproducible installations across environments.

Lock File Structure

skills.lock

# This file is automatically generated by FastSkill
# Do not edit manually

[[skills]]
id = "web-scraper"
version = "1.2.3"
source_type = "git"
source_url = "https://github.com/user/web-scraper.git"
commit_hash = "abc123def456"
fetched_at = "2026-02-02T12:00:00Z"

[[skills]]
id = "data-processor"
version = "2.1.0"
source_type = "registry"
source_url = "https://registry.fastskill.dev/data-processor"
commit_hash = "xyz789"
fetched_at = "2026-02-02T12:05:00Z"

Lock File Usage

Development Mode (with skill-project.toml):

# Install latest compatible versions from skill-project.toml
fastskill install

# This updates skills.lock with resolved versions

Production Mode (with skills.lock):

# Install exact versions from skills.lock
fastskill install --lock

# skill-project.toml is only used for skill metadata, not version resolution

Lock File Workflow

# 1. Development: Install with latest versions
fastskill install

# 2. Lock file is created/updated automatically
cat skills.lock

# 3. Commit lock file for reproducibility
git add skill-project.toml skills.lock
git commit -m "Update dependencies"

# 4. Production: Install with locked versions
fastskill install --lock

# Output shows locked versions:
# ✓ Installing web-scraper v1.2.3 (locked)
# ✓ Installing data-processor v2.1.0 (locked)

Dependency Resolution

The install command resolves dependencies from multiple sources:

Source Types

skill-project.toml

[dependencies]
# Git repository
web-scraper = { source = "git", url = "https://github.com/user/web-scraper.git", groups = ["prod"] }

# Registry ID
data-processor = { source = "registry", id = "data-processor", groups = ["prod"] }

# Local folder (editable)
demo-skill = { source = "local", path = "./skills/demo-skill", editable = true, groups = ["dev"] }

# ZIP file
archive-skill = { source = "zip", url = "https://example.com/archive-skill.zip", groups = ["prod"] }

Repository Priority

Skills are resolved from repositories configured in [tool.fastskill.repositories]:

skill-project.toml

[tool.fastskill.repositories]

[[tool.fastskill.repositories]]
name = "public-registry"
type = "http-registry"
index_url = "https://registry.fastskill.dev"
priority = 0

[[tool.fastskill.repositories]]
name = "team-registry"
type = "git-marketplace"
url = "https://github.com/team/skills.git"
priority = 1

Lower priority numbers take precedence. In this example, public-registry (priority 0) is checked before team-registry (priority 1).

Output Examples

Successful Installation

$ fastskill install
Installing skills...

Resolving dependencies from skill-project.toml...
Found 3 skills to install

Installing web-scraper...
✓ Installed web-scraper v1.2.3 from git
  Source: https://github.com/user/web-scraper.git

Installing data-processor...
✓ Installed data-processor v2.1.0 from registry
  Source: public-registry

Installing demo-skill...
✓ Installed demo-skill v0.1.0 from local (editable)
  Source: ./skills/demo-skill

Updated skills.lock with 3 skill(s)

✓ Installation complete
Run 'fastskill reindex' to update search index

With Group Filters

$ fastskill install --without dev
Installing skills...

Resolving dependencies from skill-project.toml...
Filtering by groups: excluding ['dev']
Found 2 skills to install

Installing web-scraper...
✓ Installed web-scraper v1.2.3 from git

Installing data-processor...
✓ Installed data-processor v2.1.0 from registry

Skipping demo-skill (in 'dev' group)

Updated skills.lock with 2 skill(s)

✓ Installation complete

Reproducible Installation

$ fastskill install --lock
Installing skills...

Installing from skills.lock (reproducible)...
Found 3 skills in lockfile

Installing web-scraper...
✓ Installed web-scraper v1.2.3 (locked)

Installing data-processor...
✓ Installed data-processor v2.1.0 (locked)

Installing demo-skill...
✓ Installed demo-skill v0.1.0 (locked)

✓ Installation complete (reproducible)

Error Handling

Missing Lock File

$ fastskill install --lock
error: skills.lock not found. Run 'fastskill install' first to create it.

Solution: Run fastskill install without --lock to create the lockfile first.

Missing skill-project.toml

$ fastskill install
error: skill-project.toml not found. Create it or use 'fastskill add' to add skills.

Solution: Run fastskill init to create skill-project.toml or use fastskill add to add individual skills.

Unresolved Dependencies

$ fastskill install
Installing skills...

Resolving dependencies from skill-project.toml...
error: Failed to resolve skill 'unknown-skill': not found in any configured repository

Solution: Check the skill ID and ensure repositories are configured correctly with fastskill repos.

Conflicting Group Flags

$ fastskill install --without dev --only prod
error: Cannot use --without and --only together

Solution: Use either --without or --only, but not both at the same time.

Workflow Examples

Initial Project Setup

# 1. Initialize project
fastskill init --yes

# 2. Add dependencies to skill-project.toml
# Edit skill-project.toml:
# [dependencies]
# web-scraper = { source = "git", url = "https://github.com/user/web-scraper.git", groups = ["prod"] }

# 3. Install dependencies
fastskill install

# 4. Reindex for search
fastskill reindex

Development Workflow

# Install all skills including dev tools
fastskill install

# Reindex for search
fastskill reindex

# Test development skills
fastskill search "test utility"

# Commit lockfile
git add skill-project.toml skills.lock
git commit -m "Install dependencies"

Production Deployment

# Install production skills only (no dev dependencies)
fastskill install --without dev --lock

# Reindex
fastskill reindex

# Verify installation
fastskill list

CI/CD Pipeline

# .github/workflows/deploy.yml
name: Deploy Skills
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

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

      - name: Install dependencies
        run: |
          # Install production skills with locked versions
          fastskill install --lock --without dev

      - name: Reindex skills
        run: |
          fastskill reindex
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

      - name: Verify installation
        run: |
          fastskill list

Best Practices

Commit both skill-project.toml and skills.lock

Always commit both files to version control. This ensures all team members install the same versions.

Use groups for environment-specific dependencies

Separate dev, test, and production dependencies into groups. Use --without dev for production builds.

Run fastskill install before committing

Run fastskill install after modifying skill-project.toml to update skills.lock with new versions.

Use --lock for production deployments

Always use --lock flag in production to ensure exact version matches.

Reindex after installation

Run fastskill reindex after installation to update the semantic search index.

​install Command

​Usage

​Options

​Examples

​Install All Dependencies

​Install Without Dev Skills

​Install Only Specific Groups

​Reproducible Installation

​Combined Example: Production Deployment

​Behavior

​Dependency Groups

​Default Group Behavior

​Skills Lock File

​Lock File Structure

​Lock File Usage

​Lock File Workflow

​Dependency Resolution

​Source Types

​Repository Priority

​Output Examples

​Successful Installation

​With Group Filters

​Reproducible Installation

​Error Handling

​Missing Lock File

​Missing skill-project.toml

​Unresolved Dependencies

​Conflicting Group Flags

​Workflow Examples

​Initial Project Setup

​Development Workflow

​Production Deployment

​CI/CD Pipeline

​Best Practices

​See Also

install Command

Usage

Options

Examples

Install All Dependencies

Install Without Dev Skills

Install Only Specific Groups

Reproducible Installation

Combined Example: Production Deployment

Behavior

Dependency Groups

Default Group Behavior

Skills Lock File

Lock File Structure

Lock File Usage

Lock File Workflow

Dependency Resolution

Source Types

Repository Priority

Output Examples

Successful Installation

With Group Filters

Reproducible Installation

Error Handling

Missing Lock File

Missing skill-project.toml

Unresolved Dependencies

Conflicting Group Flags

Workflow Examples

Initial Project Setup

Development Workflow

Production Deployment

CI/CD Pipeline

Best Practices

See Also