Skills Manifest System

FastSkill uses a declarative manifest system inspired by modern package managers like Poetry and npm. This system allows you to define which skills should be installed in your project, manage their versions, and ensure reproducible installations.

Overview

The manifest system consists of three key files:

skills.toml - Declarative manifest defining desired skills (like pyproject.toml)
skills-lock.toml - Lock file recording exact installed state (like poetry.lock)
.claude/sources.toml - Configuration for skill sources (repositories)

skills.toml - Declarative Manifest

The skills.toml file is the source of truth for which skills should be installed in your .claude/skills/ registry.

Basic Structure

[metadata]
version = "1.0.0"

[[skills]]
id = "web-scraper"
source = { type = "git", url = "https://github.com/org/repo.git", branch = "main" }

Source Types

Skills can come from various sources: Git Repository:

[[skills]]
id = "web-scraper"
source = { type = "git", url = "https://github.com/org/repo.git", branch = "main" }
# Optional: tag = "v1.0.0", subdir = "skills/scraper"

Local Path:

[[skills]]
id = "my-local-skill"
source = { type = "local", path = "./local-skills/my-skill", editable = true }

ZIP URL:

[[skills]]
id = "versioned-skill"
source = { type = "zip-url", base_url = "https://skills.example.com/", version = "1.2.3" }

Source Repository:

[[skills]]
id = "team-skill"
source = { type = "source", name = "team-tools", skill = "monitoring", version = "2.1.0" }

Groups

Skills can be organized into groups (like Poetry groups):

# Default skills (installed in all cases)
[[skills]]
id = "web-scraper"
source = { type = "git", url = "https://github.com/org/repo.git" }

# Development group skills
[[skills]]
id = "pytest"
source = { type = "source", name = "team-tools", skill = "pytest" }
groups = ["dev"]

# Production group skills
[[skills]]
id = "monitoring"
source = { type = "source", name = "team-tools", skill = "monitoring" }
groups = ["prod"]

Install commands:

fastskill install - Installs all skills (default + all groups)
fastskill install --without dev - Installs all except dev group
fastskill install --only prod - Installs only prod group

Editable Installs

For local development, you can mark skills as editable:

[[skills]]
id = "my-local-skill"
source = { type = "local", path = "./local-skills/my-skill", editable = true }
groups = ["dev"]

Editable skills are installed as symlinks (on Unix) or references, allowing you to edit them in place without reinstalling.

skills-lock.toml - Lock File

The skills-lock.toml file records the exact installed state of all skills for reproducibility.

Structure

[metadata]
version = "1.0.0"
generated_at = "2024-01-01T12:00:00Z"
fastskill_version = "0.1.0"

[[skills]]
id = "web-scraper"
name = "Web Scraper"
version = "1.2.3"
source = { type = "git", url = "https://github.com/org/repo.git", branch = "main" }
commit_hash = "abc123def456789"
fetched_at = "2024-01-01T12:00:00Z"
groups = []
editable = false

Key Differences from skills.toml

Feature	skills.toml	skills-lock.toml
Purpose	Declarative (what should be)	Exact state (what is installed)
Editable	Yes (user edits)	No (auto-generated)
Versions	Flexible (branches, ranges)	Exact (specific commits/versions)
Commit Hashes	No	Yes (for Git sources)
Timestamps	No	Yes (fetched_at)
Groups	Yes	Yes (from manifest)

When Lock File is Updated

The lock file is automatically updated when you:

Run fastskill install
Run fastskill add <skill>
Run fastskill update
Run fastskill remove <skill>

Never edit the lock file manually - it’s generated automatically to ensure accuracy.

Workflow Examples

Development Workflow

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

# 2. Install all skills
fastskill install

# 3. Commit both files
git add skills.toml skills-lock.toml
git commit -m "Add development skill"

Production Deployment

# 1. Install from lock file (reproducible)
fastskill install --lock

# 2. Only production skills
fastskill install --without dev

Team Collaboration

# Developer 1: Adds a skill
fastskill add --group dev pytest

# Developer 2: Gets updates
git pull
fastskill install

# Both have identical skill installations

Version Management

Semantic Versioning

Skills can use semantic versioning when distributed as ZIP files:

[[skills]]
id = "versioned-skill"
source = { type = "zip-url", base_url = "https://skills.example.com/", version = "1.2.3" }

Git-Based Versioning

For Git sources, FastSkill tracks:

Branch: The branch being tracked
Commit Hash: Exact commit installed
Tag: Optional tag reference

# In skills.toml (declarative)
[[skills]]
id = "web-scraper"
source = { type = "git", url = "...", branch = "main" }

# In skills-lock.toml (exact state)
[[skills]]
id = "web-scraper"
source = { type = "git", url = "...", branch = "main" }
commit_hash = "abc123def456789"  # Exact commit

skill-info.toml

Skill authors can provide version metadata:

# In skill directory: skill-info.toml
[metadata]
version = "1.2.3"

This is used by fastskill for version tracking and can be included in lock files.

Best Practices

1. Commit Both Files

Always commit both skills.toml and skills-lock.toml:

git add skills.toml skills-lock.toml
git commit -m "Add skills"

2. Use Groups for Environments

Separate development and production skills:

# Development tools
[[skills]]
id = "pytest"
groups = ["dev"]

# Production monitoring
[[skills]]
id = "monitoring"
groups = ["prod"]

3. Lock File for Production

Use --lock flag for reproducible production deployments:

fastskill install --lock

4. Regular Updates

Keep skills up to date:

# Check for updates
fastskill update --check

# Update all skills
fastskill update

# Update specific skill
fastskill update my-skill-id

5. Editable for Local Development

Use editable installs for skills you’re developing:

fastskill add ./my-skill -e --group dev

Comparison with Other Package Managers

FastSkill’s manifest system is inspired by modern package managers:

Feature	FastSkill	Poetry	npm
Declarative manifest	`skills.toml`	`pyproject.toml`	`package.json`
Lock file	`skills-lock.toml`	`poetry.lock`	`package-lock.json`
Groups	`groups = ["dev"]`	`--group dev`	`devDependencies`
Editable installs	`editable = true`	`-e` flag	`npm link`
Source tracking	Git, ZIP, local	PyPI, Git, local	npm registry, Git

Troubleshooting

Lock File Out of Sync

If your lock file doesn’t match installed skills:

# Regenerate lock file
fastskill install

Missing Skills

If skills are missing after git pull:

# Install from lock file
fastskill install --lock

Version Conflicts

If you see version conflicts:

# Check what's installed
fastskill show

# Update to resolve conflicts
fastskill update

Getting Started

Configuration

Skill Management

Discovery & Routing

Tool Calling

Progressive Loading

API Reference

CLI Reference

Registry

Examples & Tutorials

Advanced Topics

Integration

Community

​Skills Manifest System

​Overview

​skills.toml - Declarative Manifest

​Basic Structure

​Source Types

​Groups

​Editable Installs

​skills-lock.toml - Lock File

​Structure

​Key Differences from skills.toml

​When Lock File is Updated

​Workflow Examples

​Development Workflow

​Production Deployment

​Team Collaboration

​Version Management

​Semantic Versioning

​Git-Based Versioning

​skill-info.toml

​Best Practices

​1. Commit Both Files

​2. Use Groups for Environments

​3. Lock File for Production

​4. Regular Updates

​5. Editable for Local Development

​Comparison with Other Package Managers

​Troubleshooting

​Lock File Out of Sync

​Missing Skills

​Version Conflicts