Skip to main content

​
Repository Configuration

Repositories allow you to define where FastSkill should look for skills. FastSkill supports multiple repository types, all configured through a unified interface. Important: Repositories are used for skill discovery only. They define where skills come FROM. The storage location (where skills are installed when you run fastskill add) is configured separately in .fastskill/config.yaml via the skills_directory setting.

​
Configuration File

Repository configuration is stored in the [tool.fastskill.repositories] section of skill-project.toml at your project root: 
# skill-project.toml

[dependencies]
# ... skill dependencies ...

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

[[tool.fastskill.repositories]]
name = "public-registry"
type = "http-registry"
index_url = "https://api.fastskill.io/index"
priority = 1
auth = { type = "pat", env_var = "FASTSKILL_TOKEN" }

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

[[tool.fastskill.repositories]]
name = "local-dev"
type = "local"
path = "./local-skills"
priority = 3
Note: Repositories are searched in priority order (lower number = higher priority). If multiple repositories have the same priority, the first one in the file is used.

​
Source Types

​
Git Marketplace Sources

Git marketplace sources reference a Git repository that contains skills: 
[tool.fastskill.repositories]
[[tool.fastskill.repositories]]
name = "team-skills"
type = "git-marketplace"
url = "https://github.com/org/skills.git"
branch = "main"
priority = 0
Requirements:
  • Repository must contain marketplace.json in one of these locations:
    • Claude Code standard: .claude-plugin/marketplace.json (recommended)
    • Root location: marketplace.json (legacy support)
  • Marketplace.json should reference skills available in the repository
Marketplace.json locations (checked in priority order):
  1. {url}/.claude-plugin/marketplace.json (Claude Code standard - tried first)
  2. {url}/marketplace.json (root location - fallback) Both are fetched via raw content API (e.g., raw.githubusercontent.com)

​
http-registry

HTTP-based registries with HTTP-served index and S3 blob storage. The index uses a flat layout structure ({scope}/{skill-name}) and is served directly via HTTP endpoints: 
[tool.fastskill.repositories]
[[tool.fastskill.repositories]]
name = "public-registry"
type = "http-registry"
index_url = "https://api.fastskill.io/index"
priority = 0
auth = { type = "pat", env_var = "FASTSKILL_TOKEN" }
Use fastskill registry list-skills to list skills from HTTP registries. The command calls GET /api/registry/index/skills on the configured registry’s index_url. The registry server serves index files at /index/{skill_id} where skill_id follows the format {scope}/{skill-name} (e.g., dev-user/web-scraper).

​
zip-url

Static hosting where skills are distributed as ZIP files: 
[tool.fastskill.repositories]
[[tool.fastskill.repositories]]
name = "official-skills"
type = "zip-url"
zip_url = "https://example.com/skills.zip"
priority = 0
Requirements:
  • Base URL must serve marketplace.json in one of these locations:
    • Claude Code standard: .claude-plugin/marketplace.json (recommended)
    • Root location: marketplace.json (legacy support)
  • Marketplace.json should include download_url for each skill
Marketplace.json locations (checked in priority order):
  1. {base_url}/.claude-plugin/marketplace.json (Claude Code standard - tried first)
  2. {base_url}/marketplace.json (root location - fallback)

​
local

Local filesystem directories for development and testing: 
[tool.fastskill.repositories]
[[tool.fastskill.repositories]]
name = "local-skills"
type = "local"
path = "./local-skills"
priority = 0
Note: Local sources are not displayed in the registry web UI. They are only available for direct CLI operations.

​
Marketplace.json Requirement

Only Git and Zip URL sources are supported in the registry because they can provide marketplace.json files. The registry will:
  1. Fetch marketplace.json from the source URL
  2. Cache the response for 5 minutes (TTL)
  3. Display skills from the marketplace in the web UI
Sources without marketplace.json will not appear in the registry.

​
Managing Sources

​
Adding a Repository

Add a new repository using the CLI: 
fastskill registry add new-source --type git-marketplace --url https://github.com/user/repo.git --priority 0
Or edit skill-project.toml directly: 
[tool.fastskill.repositories]
[[tool.fastskill.repositories]]
name = "new-source"
type = "git-marketplace"
url = "https://github.com/user/repo.git"
priority = 0

​
Removing a Repository

Remove the repository using fastskill registry remove <name> or edit skill-project.toml directly.

​
Best Practices

  1. Use descriptive names: Repository names should clearly identify the repository
  2. Version control: Keep skill-project.toml in version control (includes repository configuration)
  3. Update marketplace.json: Regularly regenerate marketplace.json when skills change
  4. HTTPS: Use HTTPS URLs for security
  5. Caching: Be aware that marketplace.json is cached for 5 minutes
  6. Priority ordering: Use priority values to control repository search order

​
Troubleshooting

​
Source Not Appearing in Registry

  • Verify marketplace.json exists at the expected URL
  • Check that the source type is git or zip-url (not local)
  • Ensure the URL is accessible and returns valid JSON
  • Check server logs for fetch errors

​
Marketplace.json Not Found

  • Verify the URL is correct
  • Ensure marketplace.json is at the root of the repository (for Git sources)
  • Check that the base URL is correct (for Zip URL sources)

​
See Also