> ## 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.

# install

# install Command

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

## Usage

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
fastskill install --without dev
```

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

### Install Only Specific Groups

Install only skills from specific groups:

```bash theme={null}
# 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`:

```bash theme={null}
fastskill install --lock
```

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

### Combined Example: Production Deployment

Install production skills with exact versions:

```bash theme={null}
# 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:

1. **Locates Project File**: Finds `skill-project.toml` at project root or walks up directory tree
2. **Loads Dependencies**: Reads `[dependencies]` section from `skill-project.toml`
3. **Applies Group Filters**: Filters dependencies based on `--without` and `--only` flags
4. **Resolves Skills**: For each dependency:
   * If `--lock` is set: Resolves exact versions from `skills.lock`
   * Otherwise: Resolves latest compatible versions from repositories
5. **Installs Skills**: Downloads and installs skills into `.claude/skills/`
6. **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`:

```toml skill-project.toml theme={null}
[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"] }
```

<Info>
  If no `groups` are specified, the skill belongs to no groups and will always be installed.
</Info>

### Default Group Behavior

```toml theme={null}
# 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

```toml skills.lock theme={null}
# 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`):

```bash theme={null}
# Install latest compatible versions from skill-project.toml
fastskill install

# This updates skills.lock with resolved versions
```

**Production Mode** (with `skills.lock`):

```bash theme={null}
# Install exact versions from skills.lock
fastskill install --lock

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

### Lock File Workflow

```bash theme={null}
# 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

```toml skill-project.toml theme={null}
[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]`:

```toml skill-project.toml theme={null}
[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

```bash theme={null}
$ 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

```bash theme={null}
$ 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

```bash theme={null}
$ 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

```bash theme={null}
$ 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

```bash theme={null}
$ 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

```bash theme={null}
$ 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

```bash theme={null}
$ 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Install production skills only (no dev dependencies)
fastskill install --without dev --lock

# Reindex
fastskill reindex

# Verify installation
fastskill list
```

### CI/CD Pipeline

```yaml theme={null}
# .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

<Steps>
  <Step title="Commit both skill-project.toml and skills.lock">
    Always commit both files to version control. This ensures all team members install the same versions.
  </Step>

  <Step title="Use groups for environment-specific dependencies">
    Separate dev, test, and production dependencies into groups. Use `--without dev` for production builds.
  </Step>

  <Step title="Run fastskill install before committing">
    Run `fastskill install` after modifying `skill-project.toml` to update `skills.lock` with new versions.
  </Step>

  <Step title="Use --lock for production deployments">
    Always use `--lock` flag in production to ensure exact version matches.
  </Step>

  <Step title="Reindex after installation">
    Run `fastskill reindex` after installation to update the semantic search index.
  </Step>
</Steps>

## See Also

* [Update Command](/cli-reference/update-command) - Update skills to latest versions
* [Add Command](/cli-reference/skill-commands#add) - Add individual skills to project
* [repos Command](/cli-reference/repository-command) - Manage skill repositories
* [Manifest System](/skill-management/manifest-system) - Understanding skill-project.toml