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

# Skill Commands

> FastSkill CLI commands for skill management including registration, validation, and lifecycle operations.

## Overview

Skill commands provide comprehensive management of FastSkill skills through command line interface. These commands allow you to register, install, update, remove, and manage skills in your FastSkill ecosystem.

<Note>
  For detailed documentation on specific commands, see the dedicated command pages linked below.
</Note>

## Command Reference

### fastskill init

Initialize `skill-project.toml` for skill authors in current skill directory. This command extracts metadata from `SKILL.md` frontmatter and prompts for additional fields to create a comprehensive metadata file.

<Info>
  See [init Command](/cli-reference/init-command) for complete documentation with all flags and examples.
</Info>

```bash theme={null}
# Create skill-project.toml interactively
fastskill init

# Set version directly
fastskill init --version 1.2.3

# Skip prompts, use defaults
fastskill init --yes

# Force overwrite existing skill-project.toml
fastskill init --force
```

**What it does**:

* Derives skill ID from current directory name (required)
* Extracts available fields from `SKILL.md` frontmatter (name, description, version, author, tags, capabilities)
* Prompts interactively for missing fields (when not using `--yes`)
* Creates `skill-project.toml` with all metadata fields including required `id` and `version`

**Options**:

* `--yes`: Skip interactive prompts and use defaults
* `--force`: Force reinitialization even if skill-project.toml exists
* `--version <VERSION>`: Set version directly
* `--description <DESC>`: Set skill description
* `--author <AUTHOR>`: Set skill author
* `--download-url <URL>`: Set download URL

### fastskill read

Retrieve skill documentation and base directory path in an agent-optimized format. This command is designed for programmatic consumption by AI agents and automation tools.

```bash theme={null}
# Read a skill by ID
fastskill read <skill-id>

# Examples
fastskill read pptx
fastskill read data-analyzer
fastskill read web-scraper
```

**Output Format**:
The command outputs structured text with:

* Skill identifier
* Base directory (absolute path)
* Complete SKILL.md content

**Example Output**:

```
Reading: pptx
Base directory: /home/user/.claude/skills/pptx

---
description: "Presentation creation and editing"
author: "FastSkill Team"
version: "1.2.3"
tags: ["presentation", "powerpoint", "office"]
capabilities: ["create_slides", "edit_content", "export_formats"]
---

# PowerPoint Skill

This skill provides tools for creating and editing PowerPoint presentations programmatically.

## Tools Available

### create_presentation
Creates a new PowerPoint presentation with specified parameters.

**Parameters:**
- `title` (string): Presentation title
- `template` (string, optional): Template to use
- `slides` (array): Array of slide definitions

**Returns:** Presentation file path

### add_slide
Adds a new slide to an existing presentation.

**Parameters:**
- `presentation_path` (string): Path to presentation file
- `slide_type` (string): Type of slide (title, content, etc.)
- `content` (object): Slide content definition

**Returns:** Updated presentation file path
```

**Use Cases**:

* **Agent Integration**: Load skill documentation into agent context
* **Tool Discovery**: Explore available functions and parameters
* **Documentation Access**: Get complete skill information programmatically
* **Debugging**: Verify skill content and structure

**Error Handling**:

* Exit code 0: Success
* Exit code 1: Skill not found or invalid identifier
* Exit code 2: System error (file access, size limit exceeded)

**Limitations**:

* Maximum file size: 500KB for SKILL.md files
* Single skill per invocation
* Read-only operation (does not execute scripts or modify data)
* Only works with already-installed skills

You can also run `fastskill <skill-id>` with no subcommand; it routes to the same read behavior.

### fastskill install

Install skills from `skill-project.toml` to skills storage directory (like `poetry install`). The storage location is configured in `.fastskill/config.yaml` via `skills_directory` (default: `.claude/skills/`).

<Info>
  See [install Command](/cli-reference/install-command) for complete documentation with groups, lockfile, and reconciliation features.
</Info>

```bash theme={null}
# Install all skills from skill-project.toml
fastskill install

# Install without dev group skills
fastskill install --without dev

# Install only production group skills
fastskill install --only prod

# Install from lock file (reproducible)
fastskill install --lock
```

**Options**:

* `--without <GROUPS...>`: Exclude skills from these groups
* `--only <GROUPS...>`: Only install skills from these groups
* `--lock`: Install from skills.lock (exact versions) instead of resolving from skill-project.toml

### fastskill update

Update skills in skills storage directory to their latest versions from source. The storage location is configured in `.fastskill/config.yaml` via `skills_directory` (default: `.claude/skills/`).

<Info>
  See [update Command](/cli-reference/update-command) for complete documentation with strategies and version constraints.
</Info>

```bash theme={null}
# Update all skills
fastskill update

# Update specific skill
fastskill update my-skill-id

# Check for updates without installing
fastskill update --check

# Show what would be updated
fastskill update --dry-run
```

**Options**:

* `<SKILL_ID>`: Skill ID to update (if not specified, updates all)
* `--check`: Check for updates without installing
* `--dry-run`: Show what would be updated without actually updating
* `--version <VERSION>`: Update to specific version
* `--source <SOURCE>`: Update from specific source
* `--strategy <STRATEGY>`: Update strategy: latest, patch, minor, major (default: latest)

### fastskill read (metadata and tree)

Display skill metadata or dependency tree. Use `--meta` for structured metadata and `--tree` for the dependency tree.

```bash theme={null}
# Read full SKILL.md content (default)
fastskill read my-skill-id

# Show structured metadata (replaces `fastskill show <id>`)
fastskill read my-skill-id --meta

# Show dependency tree (replaces `fastskill show <id> --tree`)
fastskill read my-skill-id --tree

# Metadata and tree together
fastskill read my-skill-id --meta --tree

# Metadata as JSON
fastskill read my-skill-id --meta --json

# List all installed skills
fastskill list
```

<Note>
  `fastskill show` has been removed. Use `fastskill read <id> --meta` to view skill metadata or `fastskill list` to enumerate all installed skills.
</Note>

### fastskill add

Add a skill from a source (git URL, local folder, or zip file) and install it to the skills storage directory. Updates both `skill-project.toml` and `skills.lock`.

**Storage Location**: Skills are installed to the directory configured in `.fastskill/config.yaml` via the `skills_directory` setting (default: `.claude/skills/`). Repository configuration is stored in `[tool.fastskill.repositories]` section of `skill-project.toml`.

**Installing from a subdirectory**: Use a GitHub tree URL to add a skill that lives in a subfolder of a repo. Format: `https://github.com/user/repo/tree/<branch>/<path/to/skill>`. The CLI clones the repo and uses the specified path as the skill root.

```bash theme={null}
# Add skill from git URL
fastskill add https://github.com/org/skill.git

# Add skill from a subdirectory (GitHub tree URL)
fastskill add "https://github.com/org/repo/tree/main/path/to/skill"

# Add skill in editable mode (for local development)
fastskill add ./local-skill -e

# Add skill to a group
fastskill add https://github.com/org/skill.git --group dev

# Add editable skill to dev group
fastskill add ./local-skill -e --group dev

# Add all skills under a directory recursively
fastskill add ./skills -r

# Add all skills recursively with editable mode and group
fastskill add ./skills -r -e --group dev
```

**Git URL formats:**

* Standard: `https://github.com/user/repo.git`
* Tree URL (subdirectory): `https://github.com/user/repo/tree/branch/path/to/skill`

**Options:**

* `-e, --editable`: Install skill in editable mode (symlink/reference for local development)
* `-r, --recursive`: Add all skills found under the directory (discovers directories containing SKILL.md). Only valid when source is a local directory
* `--group <GROUP>`: Add skill to a specific group (e.g., "dev", "prod")
* `--branch <BRANCH>`: Git branch to checkout (for git URLs)
* `--tag <TAG>`: Git tag to checkout (for git URLs)
* `--force`: Force registration even if skill already exists

### fastskill remove

Remove a skill from the skills storage directory and update both `skill-project.toml` and `skills.lock`. The storage location is configured in `.fastskill/config.yaml` via `skills_directory` (default: `.claude/skills/`).

```bash theme={null}
# Remove skill (with confirmation)
fastskill remove my-skill-id

# Force removal without confirmation
fastskill remove my-skill-id --force

# Remove multiple skills
fastskill remove skill1 skill2 skill3
```

**Options**:

* `--force`, `-f`: Skip confirmation
* `--skills-dir <PATH>`: Override skills directory

### fastskill repos

Manage skill repositories and browse remote skill catalog for discovering and installing skills.

```bash theme={null}
# Add a repository
fastskill repos add team-tools --repo-type git-marketplace https://github.com/org/team-skills.git

# List all repositories
fastskill repos list

# Remove a repository
fastskill repos remove team-tools

# Update repository metadata
fastskill repos update team-tools --branch develop

# List skills from a repository
fastskill repos skills

# Show skill details
fastskill repos show skill-id
```

### fastskill list

List locally installed skills with reconciliation against project and lock files. Similar to `pip list` or `uv list`.

```bash theme={null}
# List all installed skills (table format, default)
fastskill list

# List in JSON format
fastskill list --json

# Explicitly request grid format
fastskill list --format grid

# XML output for agent consumption
fastskill list --format xml
```

**Output Format**:

* **Table (default)**: Human-readable table with columns: id, name, description, flags
* **Grid**: Simple list format for commands with many columns
* **JSON**: Machine-readable array with same fields plus reconciliation status
* **XML**: Structured XML for agent consumption

**Reconciliation Status**:

* `ok`: Skill is installed and matches project/lock files
* `missing`: Skill is in `skill-project.toml` but not installed
* `extraneous`: Skill is installed but not in `skill-project.toml`
* `mismatch`: Installed version differs from `skills.lock`

**Options**:

* `--format <table|json|grid|xml>`: Output format (default: table)
* `--json`: Shorthand for --format json (mutually exclusive with --format)
* `--details`: Extra columns (version, paths, reconciliation detail)
* `--skills-dir <PATH>`: Override skills directory for this invocation

**Example JSON Output**:

```json theme={null}
[
  {
    "id": "pptx",
    "version": "1.2.3",
    "description": "Presentation creation and editing",
    "source": "registry",
    "installed_path": "/home/user/.claude/skills/pptx",
    "installed_at": "2025-01-15T10:30:00Z",
    "status": "ok"
  }
]
```

**Note**: This command reads installed skill manifests from the skills directory as the source of truth and cross-references `skill-project.toml` (desired) and `skills.lock` (pinned) to report reconciliation status.

## Examples

### Skill Development Workflow

```bash theme={null}
# 1. Add skill from Git repository
fastskill add https://github.com/org/my-skill.git

# 2. List skills to verify installation
fastskill list

# 3. Show skill metadata
fastskill read my-skill --meta

# 4. Update to latest version
fastskill update my-skill

# 5. Remove skill when no longer needed
fastskill remove my-skill --force
```

### Batch Operations

```bash theme={null}
# Install multiple local skills (editable) and install
for dir in ./skills/*; do
  fastskill add "$dir" -e --group dev
done

fastskill install
fastskill reindex
```

### CI/CD Integration

```bash theme={null}
# Install with locked versions for reproducible builds
fastskill install --lock --without dev

# Reindex for search (auto-triggered after add/install/update/remove when embedding is configured)
fastskill reindex

# Check environment readiness
fastskill doctor

# Verify installation
fastskill list
```

<Note>
  Skill commands support both interactive use and automation. Use appropriate options for your workflow. Reindex runs automatically after `add`/`install`/`update`/`remove` when an embedding provider is configured; use `--no-reindex` to suppress or `fastskill doctor` to check environment readiness.
</Note>