init Command

Initialize skill-project.toml for skill authors. This command creates a project manifest file for managing skill metadata, dependencies, and version information.

Usage

fastskill init [OPTIONS]

Options

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

Examples

Interactive Initialization

Run interactively with prompts for all required fields:

fastskill init

The command will prompt for:

Version (defaults to 1.0.0)
Description (optional)
Author (optional)
Download URL (optional)

Non-Interactive Initialization

Use --yes to skip prompts and use defaults:

fastskill init --yes

Set All Fields Non-Interactively

Set all fields via command-line options:

fastskill init \
  --version "1.0.0" \
  --description "My awesome skill" \
  --author "Your Name" \
  --download-url "https://github.com/user/my-skill"

Force Reinitialization

Overwrite existing skill-project.toml:

fastskill init --force

Using --force will overwrite your existing skill-project.toml file. Make sure to backup if you need to preserve any custom configurations.

Behavior

The init command:

Detects Context: Determines if you’re in a skill directory (with SKILL.md) or a project directory
Extracts Metadata: If SKILL.md exists, extracts version, description, and author from YAML frontmatter
Prioritizes Inputs: Uses values in this priority order:
- CLI arguments (highest priority)
- SKILL.md frontmatter
- Interactive prompts
- Default values (lowest priority)
Generates Skill ID: Uses the current directory name as the skill ID
Validates Format: Validates skill ID format and semantic version format
Creates File: Writes skill-project.toml with basic structure and commented examples

Generated File Structure

The init command creates a skill-project.toml file with the following structure:

skill-project.toml

[metadata]
id = "my-skill"
version = "1.0.0"
description = "My awesome skill"
author = "Your Name"
download_url = "https://github.com/user/my-skill"

[dependencies]
# Add your skill dependencies here
# example-skill = { source = "git", url = "https://github.com/user/example-skill.git" }

# Optional: FastSkill configuration
# Uncomment and configure as needed

# [tool.fastskill]
# skills_directory = ".claude/skills"
#
# [tool.fastskill.embedding]
# openai_base_url = "https://api.openai.com/v1"
# embedding_model = "text-embedding-3-small"
#
# [[tool.fastskill.repositories]]
# name = "default"
# type = "http-registry"
# index_url = "https://registry.fastskill.dev"
# priority = 0

Skill ID Detection

The skill ID is automatically derived from the current directory name:

# In directory: /path/to/my-skill
# → Skill ID: my-skill

cd my-skill
fastskill init
# Creates: [metadata] id = "my-skill"

If you’re in a project directory (no SKILL.md), the skill-project.toml can still be used to declare dependencies for installation via fastskill install.

Context Detection

The command automatically detects the project context:

Skill Context (with SKILL.md)

When SKILL.md exists in the current directory:

my-skill/
├── SKILL.md
└── (skill files)

cd my-skill
fastskill init
# → Creates skill-project.toml for this skill

The skill-project.toml includes metadata that augments or overrides SKILL.md frontmatter for publishing.

Project Context (without SKILL.md)

When no SKILL.md exists:

my-project/
├── skill-project.toml
├── skills/
│   └── ...
└── (project files)

cd my-project
fastskill init
# → Creates skill-project.toml for declaring dependencies

Use fastskill install to install skills declared in [dependencies] section.

SKILL.md Frontmatter Integration

When SKILL.md exists, the command extracts metadata from YAML frontmatter:

SKILL.md

---
name: My Skill
description: An awesome skill
version: "1.0.0"
author: Your Name
license: MIT
---

Skill content here...

If you provide --version, --description, or --author flags, they will override the values from SKILL.md frontmatter.

Version Validation

The command validates semantic version format: Valid versions:

1.0.0
2.1.3
0.0.1
10.20.30

Invalid versions:

1.0 (missing patch)
1 (missing minor and patch)
v1.0.0 (v prefix not allowed)
1.0.0-beta (pre-release not supported in init)

Skill ID Validation

The skill ID (directory name) must meet these requirements:

Must start with a letter
Can contain letters, numbers, hyphens, and underscores
Cannot contain spaces or special characters
Cannot start or end with hyphen or underscore

Valid IDs:

my-skill
data_processor
web-scraper-v2

Invalid IDs:

my skill (contains space)
-skill (starts with hyphen)
skill_ (ends with underscore)
123skill (doesn’t start with letter)

Workflow Examples

Creating a New Skill

# 1. Create skill directory
mkdir my-new-skill
cd my-new-skill

# 2. Create SKILL.md
cat > SKILL.md << 'EOF'
---
name: My New Skill
description: A brief description
version: "1.0.0"
author: Your Name
---

Skill content here...
EOF

# 3. Initialize project
fastskill init --yes

# 4. Add to skill-project.toml dependencies (if needed)
# Edit skill-project.toml to add dependencies

Creating a Multi-Skill Project

# 1. Create project directory
mkdir my-project
cd my-project

# 2. Initialize project manifest
fastskill init --yes \
  --version "1.0.0" \
  --description "My multi-skill project" \
  --author "Your Name"

# 3. Add skills
fastskill add https://github.com/user/skill-a.git
fastskill add https://github.com/user/skill-b.git

# 4. Install skills
fastskill install

Updating Metadata for Existing Skill

cd my-existing-skill

# Update metadata in skill-project.toml
fastskill init \
  --version "2.0.0" \
  --description "Updated description" \
  --force

Use Cases

For Skill Authors

Use fastskill init to:

Create project metadata for publishing skills
Track skill versions independent of SKILL.md
Override SKILL.md frontmatter for publishing
Add download URLs for distribution

For Project Maintainers

Use fastskill init to:

Declare skill dependencies in [dependencies] section
Configure repositories in [tool.fastskill.repositories]
Set up reproducible installations via fastskill install

For CI/CD Pipelines

Use fastskill init --yes to:

Create manifests without interactive prompts
Generate consistent metadata across environments
Automate project setup

Getting Started

Configuration

Skill Management

Evals & Quality

Skill Optimization

CLI Reference

Registry

Advanced Topics

Integration

init

init Command

Usage

Options

Examples

Interactive Initialization

Non-Interactive Initialization

Set All Fields Non-Interactively

Force Reinitialization

Behavior

Generated File Structure

Skill ID Detection

Context Detection

Skill Context (with SKILL.md)

Project Context (without SKILL.md)

SKILL.md Frontmatter Integration

Version Validation

Skill ID Validation

Workflow Examples

Creating a New Skill

Creating a Multi-Skill Project

Updating Metadata for Existing Skill

Use Cases

For Skill Authors

For Project Maintainers

For CI/CD Pipelines

See Also

​init Command

​Usage

​Options

​Examples

​Interactive Initialization

​Non-Interactive Initialization

​Set All Fields Non-Interactively

​Force Reinitialization

​Behavior

​Generated File Structure

​Skill ID Detection

​Context Detection

​Skill Context (with SKILL.md)

​Project Context (without SKILL.md)

​SKILL.md Frontmatter Integration

​Version Validation

​Skill ID Validation

​Workflow Examples

​Creating a New Skill

​Creating a Multi-Skill Project

​Updating Metadata for Existing Skill

​Use Cases

​For Skill Authors

​For Project Maintainers

​For CI/CD Pipelines

​See Also

init Command

Usage

Options

Examples

Interactive Initialization

Non-Interactive Initialization

Set All Fields Non-Interactively

Force Reinitialization

Behavior

Generated File Structure

Skill ID Detection

Context Detection

Skill Context (with SKILL.md)

Project Context (without SKILL.md)

SKILL.md Frontmatter Integration

Version Validation

Skill ID Validation

Workflow Examples

Creating a New Skill

Creating a Multi-Skill Project

Updating Metadata for Existing Skill

Use Cases

For Skill Authors

For Project Maintainers

For CI/CD Pipelines

See Also