Repository Architecture

Overview

FastSkill implements a flexible, multi-source repository system that allows you to discover and install skills from various sources including Git repositories, HTTP registries, ZIP files, and local filesystem paths.

Repository configuration is stored in [tool.fastskill.repositories] section of skill-project.toml or in .claude/repositories.toml for backward compatibility.

Repository Types

Git Marketplace

A Git repository containing a marketplace.json file that lists all available skills. Configuration:

skill-project.toml

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

# Optional authentication
auth_type = "pat"
auth_value = "ghp_xxxxxxxxxxxxxxxxxxxx"

# Optional subdirectory
source_subdir = "skills"

marketplace.json Format:

marketplace.json

{
  "version": "1.0",
  "skills": [
    {
      "id": "web-scraper",
      "name": "Web Scraper",
      "description": "Scrape web content efficiently",
      "version": "1.2.3",
      "author": "FastSkill Team",
      "license": "MIT",
      "tags": ["web", "scraping", "data"],
      "capabilities": ["http_requests", "file_io"],
      "file_path": "web-scraper/SKILL.md"
    },
    {
      "id": "data-processor",
      "name": "Data Processor",
      "description": "Process and analyze data",
      "version": "2.1.0",
      "author": "Data Team",
      "license": "Apache-2.0",
      "tags": ["data", "analysis", "python"],
      "capabilities": ["file_processing", "statistics"],
      "file_path": "data-processor/SKILL.md"
    }
  ]
}

How it works:

Clones Git repository to local cache
Parses marketplace.json for skill metadata
Provides skill search and discovery via FastSkill

Use cases:

Team skill sharing via private Git repository
Version-controlled skill catalogs
Multi-skill repositories with metadata
Custom skill discovery with rich metadata

HTTP Registry

An HTTP API that provides a flat index of available skills. Configuration:

skill-project.toml

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

# Optional authentication
auth_type = "api-key"
auth_value = "registry-api-key-xxxxxxxx"

Registry Index Format:

{
  "version": "1.0",
  "skills": [
    {
      "id": "pptx",
      "name": "PowerPoint Generator",
      "description": "Create PowerPoint presentations",
      "version": "1.2.3",
      "author": "FastSkill Team",
      "source": "https://registry.fastskill.dev/skills/pptx.zip"
    },
    {
      "id": "json-utils",
      "name": "JSON Utilities",
      "description": "JSON manipulation and validation",
      "version": "2.0.1",
      "source": "https://registry.fastskill.dev/skills/json-utils.zip"
    }
  ]
}

How it works:

Fetches index from HTTP endpoint
Provides skill metadata and download URLs
Skills downloaded as ZIP files when installed

Use cases:

Public skill registries
Centralized skill distribution
Versioned skill releases
Skill search and discovery at scale

ZIP URL

A base URL pattern for ZIP file downloads. Configuration:

skill-project.toml

[[tool.fastskill.repositories]]
name = "skill-archive"
type = "zip-url"
base_url = "https://example.com/skills"
priority = 0

Download Pattern: Skills are downloaded as: {base_url}/{skill_id}-{version}.zip Use cases:

Simple file servers with ZIP archives
Static skill hosting
Minimal infrastructure requirements

Local

Local filesystem path for skill discovery. Configuration:

skill-project.toml

[[tool.fastskill.repositories]]
name = "local-skills"
type = "local"
path = "./local-skills"
priority = 0

How it works:

Scans local filesystem for SKILL.md files
Each directory containing SKILL.md is treated as a skill
Skills installed via filesystem copy or symlinks

Use cases:

Local skill development
Shared network storage
Offline skill repositories
Testing local skills before publishing

Authentication Types

PAT (Personal Access Token)

For Git repositories requiring token authentication.

auth_type = "pat"
auth_value = "ghp_xxxxxxxxxxxxxxxxxxxx"

Use cases:

GitHub repositories (classic PAT)
GitLab repositories
Generic Git servers with token auth

SSH Key

Path to SSH private key file.

auth_type = "ssh-key"
auth_value = "/home/user/.ssh/id_ed25519"

Use cases:

GitHub/GitLab repositories with SSH keys
Automated deployments without interactive auth
Multi-environment setups

SSH

SSH connection without key file (uses system SSH agent).

auth_type = "ssh"
auth_value = "git@github.com:org/skills.git"

Use cases:

Systems with SSH agent
Automated deployments
Development environments with SSH config

Basic Auth

Username and password authentication.

auth_type = "basic"
auth_value = "username:password"

Basic auth stores credentials in plain text. Use only for test environments or secure configuration management.

Use cases:

Simple HTTP registries
Development and testing
Internal tool registries

API Key

API key for HTTP registry access.

auth_type = "api-key"
auth_value = "registry-api-key-xxxxxxxx"

Use cases:

Public HTTP registries with access control
Rate limiting and usage tracking
Commercial skill marketplaces

Priority-Based Conflict Resolution

When a skill ID is available from multiple repositories, priority determines which repository is used: Priority Rules:

Lower priority numbers are checked first
Default priority: 0
Higher priority values are checked later
First match wins (short-circuit)

Example:

skill-project.toml

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

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

[[tool.fastskill.repositories]]
name = "experimental"
type = "http-registry"
index_url = "https://experimental.fastskill.dev/index"
priority = 2  # Lowest priority

Resolution flow for skill “web-scraper”:

Check public-registry (priority 0) → Found! → Use this one
If not found, check team-skills (priority 1) → Continue searching
If not found, check experimental (priority 2) → Continue searching
Return error if skill not found in any repository

Skill Resolution Process

The skill resolution workflow: Detailed steps:

Parse dependency specification - Extract skill ID from skill-project.toml [dependencies]
Query repositories - Check all configured repositories in priority order
Search for skill - Look for skill in each repository
Check installed - Verify if skill is already installed in .claude/skills/
Download if needed - Clone/fetch skill from repository if not installed
Install - Register skill in FastSkill storage
Update lockfile - Record exact version in skills.lock

Repository Configuration

skill-project.toml (Recommended)

Project-level configuration with repository definitions:

skill-project.toml

[dependencies]
web-scraper = { source = "registry", id = "pptx" }
data-processor = { source = "git", url = "https://github.com/team/data-tools.git" }

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

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

Advantages:

Single file with project configuration
Repository and dependencies together
Version control of entire project setup
Easy to share and maintain

.claude/repositories.toml (Legacy)

Backward-compatible configuration file:

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

Note: This format is supported for backward compatibility but skill-project.toml is preferred.

CLI Commands for Repository Management

fastskill repos

Primary command for repository management:

# List all repositories
fastskill repos list

# Add new repository
fastskill repos add team-tools --repo-type git-marketplace \
  https://github.com/team/skills.git \
  --priority 1

# Remove repository
fastskill repos remove team-tools

# Show repository details
fastskill repos info team-tools

# Update repository
fastskill repos update team-tools --priority 0

# Test repository connectivity
fastskill repos test team-tools

# Refresh repository cache
fastskill repos refresh

# Create marketplace.json from directory
fastskill marketplace create ./skills --output marketplace.json

Catalog browsing

# Add repository
fastskill repos add team-tools --repo-type git-marketplace \
  https://github.com/team/skills.git

# List skills from repository
fastskill repos skills

# Show skill from repository
fastskill repos show pptx

# List available versions
fastskill repos versions pptx

Repository Authentication Examples

GitHub with PAT

# Set up GitHub PAT repository
fastskill repos add github-skills \
  --repo-type git-marketplace \
  https://github.com/user/skills.git \
  --auth-type pat \
  --auth-env GITHUB_TOKEN

Private Registry with API Key

# Configure private registry
fastskill repos add private-registry \
  --repo-type http-registry \
  https://private.example.com \
  --auth-type api-key \
  --auth-env PRIVATE_REGISTRY_TOKEN

Git with SSH

# Set up SSH key repository
fastskill repos add gitlab-skills \
  --repo-type git-marketplace \
  git@gitlab.com:team/skills.git \
  --auth-type ssh-key \
  --auth-key-path /home/user/.ssh/id_ed25519

Skill Discovery and Installation

From Registry ID

skill-project.toml

[dependencies]
web-scraper = { source = "registry", id = "pptx" }

# Install skill from registry ID
fastskill install
# Resolves to public-registry and downloads pptx

From Git Repository

skill-project.toml

[dependencies]
data-tools = { source = "git", url = "https://github.com/org/data-tools.git" }

# Install skill from git repository
fastskill install
# Clones git repository and installs skill

From Local Path

skill-project.toml

[dependencies]
local-skill = { source = "local", path = "./skills/my-skill" }

# Install skill from local path
fastskill install
# Copies/symlinks skill to .claude/skills/

Multi-Repository Configuration

Mixed Sources

Configure multiple repositories with different sources:

skill-project.toml

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

[[tool.fastskill.repositories]]
name = "team-skills"
type = "git-marketplace"
url = "https://github.com/team/skills.git"
priority = 1  # Check if public-registry doesn't have skill

[[tool.fastskill.repositories]]
name = "legacy-skills"
type = "git-marketplace"
url = "https://github.com/org/legacy-skills.git"
priority = 2  # Check last

Environment-Specific Repositories

Configure different repositories for development, staging, and production:

skill-project.toml

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

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

Use environment-specific repositories or branch parameters to control which skills are used.

Troubleshooting

Skill not found in any repository

Repository priority: Verify skill ID is spelled correctly and exists in at least one repository.

Resolution: Use fastskill repos list to see all repositories and fastskill repos test <name> to verify connectivity.

Check marketplace.json: For git-marketplace repositories, verify marketplace.json contains the skill ID.

Authentication failures

Invalid credentials: Check auth_type and auth_value are correct.

Token expired: PATs and API keys may expire. Generate new credentials and update configuration.

Resolution: Test authentication with fastskill repos test <name>.

Priority not working as expected

Wrong priority: Lower numbers have higher priority. Check your priority values.

Resolution: Use fastskill repos info <name> to verify repository priority.

Best Practices

Use skill-project.toml for repository configuration

Prefer skill-project.toml [tool.fastskill.repositories] section over .claude/repositories.toml for better project organization.

Set appropriate priorities

Use priority to control repository search order. Lower numbers are checked first (0, 1, 2, …).

Use authentication for private repositories

Secure private repositories with PAT, SSH keys, or API keys. Never commit credentials to version control.

Test repositories before use

Use fastskill repos test <name> to verify repository connectivity and authentication before relying on it.

Keep repositories minimal

Only configure repositories you actively use. Remove or comment out unused repositories to speed up resolution.

Use git-marketplace for team skills

For team skill sharing, use git-marketplace type with marketplace.json for comprehensive skill metadata and search.

Version control repository configuration

Commit repository configuration to version control along with skill dependencies for reproducible setups.

Refresh repositories after changes

Use fastskill repos refresh to update repository caches after remote changes.

​Overview

​Repository Types

​Git Marketplace

​HTTP Registry

​ZIP URL

​Local

​Authentication Types

​PAT (Personal Access Token)

​SSH Key

​SSH

​Basic Auth

​API Key

​Priority-Based Conflict Resolution

​Skill Resolution Process

​Repository Configuration

​skill-project.toml (Recommended)

​.claude/repositories.toml (Legacy)

​CLI Commands for Repository Management

​fastskill repos

​Catalog browsing

​Repository Authentication Examples

​GitHub with PAT

​Private Registry with API Key

​Git with SSH

​Skill Discovery and Installation

​From Registry ID

​From Git Repository

​From Local Path

​Multi-Repository Configuration

​Mixed Sources

​Environment-Specific Repositories

​Troubleshooting

​Best Practices

​See Also

Overview

Repository Types

Git Marketplace

HTTP Registry

ZIP URL

Local

Authentication Types

PAT (Personal Access Token)

SSH Key

SSH

Basic Auth

API Key

Priority-Based Conflict Resolution

Skill Resolution Process

Repository Configuration

skill-project.toml (Recommended)

.claude/repositories.toml (Legacy)

CLI Commands for Repository Management

fastskill repos

Catalog browsing

Repository Authentication Examples

GitHub with PAT

Private Registry with API Key

Git with SSH

Skill Discovery and Installation

From Registry ID

From Git Repository

From Local Path

Multi-Repository Configuration

Mixed Sources

Environment-Specific Repositories

Troubleshooting

Best Practices

See Also