repos Command

Manage skill repositories and browse remote skill catalog.

The repos command is the primary interface for repository management and catalog browsing in FastSkill. Use fastskill search for semantic search of installed skills.

Usage

fastskill repos <SUBCOMMAND>

Subcommands

list

List all configured repositories.

# List repositories in table format
fastskill repos list

# List in JSON format
fastskill repos list --json

Output Format:

Default: Human-readable table with name, type, URL/path, priority
JSON: Machine-readable array with full repository details

Example Output:

Name             Type              URL/Path                     Priority
---------------- ---------------- ---------------------------- ---------
public-registry  http-registry    https://api.fastskill.io    0
team-skills      git-marketplace  https://github.com/team/skills.git 1
local-dev        local             ./skills                    2

add

Add a new repository to your skill sources.

# Add HTTP registry
fastskill repos add public --repo-type http-registry https://api.fastskill.io --priority 0

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

# Add ZIP URL source
fastskill repos add custom --repo-type zip-url https://cdn.example.com/skills/ --priority 2

# Add local directory
fastskill repos add local-dev --repo-type local ./skills --priority 3

# Add with authentication (PAT)
fastskill repos add private-repo --repo-type git-marketplace https://github.com/team/private.git \
  --auth-type pat --auth-env GITHUB_TOKEN

# Add with SSH key
fastskill repos add private-repo --repo-type git-marketplace https://github.com/team/private.git \
  --auth-type ssh-key --auth-key-path ~/.ssh/id_rsa

# Add with basic auth
fastskill repos add registry --repo-type http-registry https://api.example.com \
  --auth-type basic --auth-username admin --auth-env REGISTRY_PASSWORD

# Add with API key
fastskill repos add registry --repo-type http-registry https://api.example.com \
  --auth-type api_key --auth-env API_KEY

Options:

Flag	Short	Type	Default	Description
`--repo-type`	-	string	required	Repository type: `git-marketplace`, `http-registry`, `zip-url`, or `local`
`--priority`	-	number	0	Lower number = higher priority (used for conflict resolution)
`--branch`	-	string	none	Git branch to checkout (for git-marketplace)
`--tag`	-	string	none	Git tag to checkout (for git-marketplace)
`--auth-type`	-	string	none	Authentication type: `pat`, `ssh-key`, `ssh`, `basic`, or `api_key` (use underscore, not hyphen)
`--auth-env`	-	string	none	Environment variable for PAT, password, or API key
`--auth-key-path`	-	path	none	SSH key path for ssh-key or ssh auth
`--auth-username`	-	string	none	Username for basic auth

Repository Types:

git-marketplace: Git repository with marketplace.json for skill discovery
- Supports PAT, SSH Key, SSH, Basic Auth
- Can specify branch or tag
- Scans for skills across repository structure
http-registry: HTTP-based registry with flat skill index
- Supports Basic Auth, API Key
- Fast skill lookup via API
- Best for production registries
zip-url: Base URL for ZIP file downloads
- Supports PAT, Basic Auth
- Downloads skills from {base_url}/{skill-id}-{version}.zip
local: Local filesystem path
- No authentication needed
- Best for development workflows

Priority-Based Conflict Resolution:

When multiple sources provide the same skill ID, the source with lower priority number wins
Priority 0 is highest
Example: If public-registry (priority 0) and team-skills (priority 1) both have pptx, public-registry’s version is used

remove

Remove a repository from your sources.

# Remove a repository
fastskill repos remove team-skills

# Remove multiple repositories
fastskill repos remove team-skills local-dev

Behavior:

Removes repository from configuration file
Does not uninstall skills that were installed from this repository
Skills remain in skills directory until explicitly removed

info

Display detailed information about a specific repository.

# Show repository details
fastskill repos info public-registry

# Show in JSON format
fastskill repos info team-skills --json

Example Output:

Name: team-skills
Type: git-marketplace
URL: https://github.com/team/skills.git
Branch: main
Priority: 1
Auth: pat (GITHUB_TOKEN)

update

Update repository metadata.

# Update branch
fastskill repos update team-skills --branch develop

# Update priority
fastskill repos update public-registry --priority 0

# Update both
fastskill repos update team-skills --branch main --priority 2

Options:

Flag	Short	Type	Default	Description
`--branch`	-	string	none	New branch for git-marketplace repositories
`--priority`	-	number	none	New priority value

test

Test repository connectivity and accessibility.

# Test a repository
fastskill repos test public-registry

# Test git marketplace
fastskill repos test team-skills

What it tests:

HTTP registries: Connectivity to API endpoint
Git marketplaces: Clone/access to repository
ZIP URLs: Accessibility of base URL
Local: Directory exists and is readable

Exit codes:

0: Repository is accessible
1: Cannot connect or access repository
2: Invalid configuration

refresh

Refresh repository cache (re-fetch from source).

# Refresh specific repository
fastskill repos refresh team-skills

# Refresh all repositories
fastskill repos refresh

When to use:

After repository has been updated with new skills
To get latest skill versions
If cache is stale or corrupted

What it does:

Re-fetches repository metadata
Updates local cache
Invalidates stale skill information

skills

List skills in repository catalog.

# List all skills from default repository (table format, default)
fastskill repos skills

# Filter by scope
fastskill repos skills --scope acme

# List all versions
fastskill repos skills --all-versions

# Include pre-release versions
fastskill repos skills --include-pre-release

# JSON output
fastskill repos skills --json

# Grid format
fastskill repos skills --format grid

# Combined options
fastskill repos skills --scope acme --all-versions --json

Options:

--scope <SCOPE>: Filter skills by scope (exact match)
--all-versions: Include all versions for each skill (default: latest only)
--include-pre-release: Include pre-release versions (default: exclude)
--format <table|json|grid>: Output format (default: table)
--json: Shorthand for —format json (mutually exclusive with —format)
--repository <NAME>: Repository name to list skills from (defaults to default repository if not specified)

Output Format:

Grid (default): Human-readable table with columns: scope, name, description (truncated to 50 chars), latest version (or “version” when --all-versions is used), published date
JSON: Machine-readable array with fields: id, scope, name, description, latest_version, published_at, and optionally versions array

show

Display detailed information about a specific skill from the catalog.

# Show skill details by ID
fastskill repos show <skill-id>

# Show skill from specific repository
fastskill repos show <skill-id> --repository my-repo

Parameters:

<skill-id>: Full skill identifier (e.g., acme/web-scraper)
--repository <NAME>: Repository to search (defaults to default repository)

Output Format: Displays comprehensive skill information including:

Skill metadata (name, description, author, version)
Capabilities and tags
Installation instructions
Dependencies and requirements
Documentation links
Change log and release notes

Example Output:

Skill: acme/web-scraper
Version: 2.0.0
Description: A web scraping skill for extracting data from websites
Author: ACME Corp
Tags: web, scraping, data-extraction
Capabilities: scrape_website, extract_data, handle_cookies

Repository: my-registry
Published: 2025-01-15T10:30:00Z
Updated: 2025-01-20T14:00:00Z

Installation: fastskill add acme/web-scraper
Homepage: https://github.com/acme/web-scraper
Documentation: https://docs.acme.com/web-scraper

Requirements:
- Node.js 16+
- Internet access
- User agent headers configured

versions

List all available versions for a specific skill.

# List versions for a skill
fastskill repos versions <skill-id>

# List versions from specific repository
fastskill repos versions <skill-id> --repository my-repo

Parameters:

<skill-id>: Full skill identifier (e.g., acme/web-scraper)
--repository <NAME>: Repository to query (defaults to default repository)

Output Format: Displays a table of versions with:

Version number
Release date
Release notes (if available)
Pre-release status
Compatibility information

Example Output:

Versions for skill: acme/web-scraper

+---------+---------------------+-------------+-------------+
| Version | Published At        | Pre-release | Notes      |
+---------+---------------------+-------------+-------------+
| 2.0.0   | 2025-01-15T10:30:00Z | false       | Major update |
| 1.5.2   | 2025-01-10T08:15:00Z | false       | Bug fixes   |
| 1.5.1   | 2025-01-05T16:45:00Z | false       | Performance |
| 1.5.0   | 2024-12-20T12:00:00Z | false       | New features|
| 1.4.0   | 2024-11-15T09:30:00Z | false       | API changes |
+---------+---------------------+-------------+-------------+

Configuration File Location

Repositories are stored in skill-project.toml at project root:

skill-project.toml

[tool.fastskill.repositories]

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

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

# Authentication is usually configured via CLI flags (--auth-type, --auth-env)
# or your registry provider docs; avoid duplicating secrets in committed files.

Authentication Types

PAT (Personal Access Token)

Use for Git repositories and private registries

Token stored in environment variable

Example:

fastskill repos add private-repo --repo-type git-marketplace https://github.com/team/repo.git \
  --auth-type pat --auth-env GITHUB_TOKEN

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

SSH Key

Use for Git repositories with SSH access

Key path points to private key file

Example:

fastskill repos add private-repo --repo-type git-marketplace git@github.com:team/repo.git \
  --auth-type ssh-key --auth-key-path ~/.ssh/id_rsa

SSH

Use for Git repositories with SSH protocol

Similar to SSH Key but may use system SSH agent

Example:

fastskill repos add private-repo --repo-type git-marketplace git@github.com:team/repo.git \
  --auth-type ssh --auth-key-path ~/.ssh/id_rsa

Basic Auth

Use for HTTP registries with username/password

Password stored in environment variable

Example:

fastskill repos add registry --repo-type http-registry https://api.example.com \
  --auth-type basic --auth-username admin --auth-env REGISTRY_PASSWORD

API Key

Use for HTTP registries with API key authentication

API key stored in environment variable

Example:

fastskill repos add registry --repo-type http-registry https://api.example.com \
  --auth-type api_key --auth-env API_KEY

Multi-Source Skill Resolution

FastSkill supports multiple sources with priority-based resolution:

# Add multiple sources
fastskill repos add public-registry --repo-type http-registry https://api.fastskill.io --priority 0
fastskill repos add team-skills --repo-type git-marketplace https://github.com/team/skills.git --priority 1
fastskill repos add local-dev --repo-type local ./skills --priority 2

Resolution process:

Repositories are consulted in ascending priority order (0 before 1 before 2).
The first repository that satisfies the lookup wins for that skill id.
Lower numeric priority means earlier in that order (0 is tried before 10).

Example:

public-registry (priority 0): pptx v1.0.0
team-skills (priority 1): pptx v1.2.0
Result: pptx v1.0.0 from public-registry is used because priority 0 is consulted first.

Examples

Setting up a development environment

# Add public registry
fastskill repos add public --repo-type http-registry https://api.fastskill.io --priority 0

# Add team repository
fastskill repos add team --repo-type git-marketplace https://github.com/team/skills.git \
  --auth-type pat --auth-env GITHUB_TOKEN --priority 1

# Add local development directory
fastskill repos add local-dev --repo-type local ./skills --priority 2

Creating a Git marketplace

# 1. Create a directory for your marketplace
mkdir my-marketplace
cd my-marketplace

# 2. Add skills (each in its own subdirectory)
git clone https://github.com/org/pptx.git skills/pptx
git clone https://github.com/org/web-scraper.git skills/web-scraper

# 3. Create marketplace.json
fastskill marketplace create \
  --name "My Marketplace" \
  --owner-name "Your Name" \
  --description "Collection of skills" \
  --base-url https://cdn.example.com/marketplace/

# 4. Commit and push
git init
git add .
git commit -m "Initial marketplace"
git remote add origin https://github.com/username/marketplace.git
git push -u origin main

Troubleshooting

Repository not found

Check name: Ensure the repository name matches what you added.

fastskill repos list

Authentication failed

Verify credentials:

# Check environment variable
echo $GITHUB_TOKEN

# Test SSH key
ssh -T git@github.com

# Test basic auth credentials
curl -u username:password https://api.example.com/health

Priority not working

Verify priority values: Lower numbers have higher priority.

fastskill repos list

Priority 0 is highest, priority 10 is lower.

Repositories configuration is stored in skill-project.toml and should be committed to version control. Authentication credentials (environment variables) should never be committed.

Getting Started

Configuration

Skill Management

Evals & Quality

Skill Optimization

CLI Reference

Registry

Advanced Topics

Integration

repos Command

repos Command

Usage

Subcommands

list

add

remove

info

update

test

refresh

skills

show

versions

Configuration File Location

Authentication Types

PAT (Personal Access Token)

SSH Key

SSH

Basic Auth

API Key

Multi-Source Skill Resolution

Examples

Setting up a development environment

Creating a Git marketplace

Troubleshooting

See Also

​repos Command

​Usage

​Subcommands

​list

​add

​remove

​info

​update

​test

​refresh

​skills

​show

​versions

​Configuration File Location

​Authentication Types

​PAT (Personal Access Token)

​SSH Key

​SSH

​Basic Auth

​API Key

​Multi-Source Skill Resolution

​Examples

​Setting up a development environment

​Creating a Git marketplace

​Troubleshooting

​See Also

repos Command

Usage

Subcommands

list

add

remove

info

update

test

refresh

skills

show

versions

Configuration File Location

Authentication Types

PAT (Personal Access Token)

SSH Key

SSH

Basic Auth

API Key

Multi-Source Skill Resolution

Examples

Setting up a development environment

Creating a Git marketplace

Troubleshooting

See Also