Skip to main content

​
registry Command

Manage skill repositories and generate marketplace.json files for registry discovery. Note: The repository command has been consolidated into the registry command. Use fastskill registry instead.

​
Usage

fastskill registry <SUBCOMMAND>

​
Subcommands

​
list-skills

List skills from HTTP registry installations. This command calls the configured registry’s HTTP API endpoint to discover available skills. 
# List all skills from default registry (grid format)
fastskill registry list-skills

# Filter by scope
fastskill registry list-skills --scope acme

# List all versions
fastskill registry list-skills --all-versions

# Include pre-release versions
fastskill registry list-skills --include-pre-release

# JSON output
fastskill registry list-skills --json

# Combined options
fastskill registry list-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)
  • --json: Output in JSON format (mutually exclusive with --grid)
  • --grid: Output in grid table format (default, mutually exclusive with --json)
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
HTTP API: The command calls GET /api/registry/index/skills on the configured registry’s index_url with query parameters:
  • scope: Scope filter (from --scope flag)
  • all_versions: Boolean (from --all-versions flag)
  • include_pre_release: Boolean (from --include-pre-release flag)
Authentication: If repository authentication is configured (PAT, basic auth, or API key), credentials are automatically sent in request headers. For private scopes, authentication may be required. Example Output (Grid): 
+--------+-------------+------------------------------------------+---------------+---------------------+
| Scope  | Name        | Description                              | Latest Version | Published At         |
+--------+-------------+------------------------------------------+---------------+---------------------+
| acme   | web-scraper | A web scraping skill for extracting...  | 2.0.0         | 2025-01-15T10:30:00Z |
| dev-user | test-skill | A test skill for validation            | 1.0.0         | 2025-01-20T14:00:00Z |
+--------+-------------+------------------------------------------+---------------+---------------------+
Example Output (JSON): 
[
  {
    "id": "acme/web-scraper",
    "scope": "acme",
    "name": "web-scraper",
    "description": "A web scraping skill for extracting data",
    "latest_version": "2.0.0",
    "published_at": "2025-01-15T10:30:00Z"
  }
]
Error Handling:
  • If registry index path is not configured: Returns clear error message
  • If registry is unreachable: Returns connection error
  • If authentication fails (401/403): Returns clear error indicating auth required for private scopes
  • Empty registry: Returns empty grid/array with success status

​
create

Generate a marketplace.json file from a directory containing skills. 
fastskill registry create [OPTIONS]

​
Options

OptionDescriptionDefault
--path <PATH>Directory to scan for skills. (current directory)
--output <PATH>Output file path.claude-plugin/marketplace.json in scanned directory
--base-url <URL>Base URL for skill download linksNone
--name <NAME>Repository name (required, or inferred from directory name)Directory name
--owner-name <NAME>Owner name (optional)None
--owner-email <EMAIL>Owner email (optional)None
--description <TEXT>Repository description (optional)None
--version <VERSION>Repository version (optional)None

​
Examples

​
Generate from Current Directory

Scan the current directory and create marketplace.json: 
fastskill registry create

​
Scan Specific Directory

Generate marketplace.json from a specific skills directory: 
fastskill repository create --path ./my-skills

​
Custom Output Location

Specify a custom output file: 
fastskill repository create --path ./skills --output ./dist/marketplace.json

​
Include Base URL

Add base URL for download links: 
fastskill repository create \
  --path ./skills \
  --base-url https://skills.example.com/

​
Generate with Metadata

Generate marketplace.json with owner and metadata information: 
fastskill repository create \
  --path ./skills \
  --name my-skills-repo \
  --owner-name "My Team" \
  --owner-email [email protected] \
  --description "Collection of skills" \
  --version "1.0.0"
Note: The output is automatically placed at .claude-plugin/marketplace.json (unless --output is specified).

​
How It Works

The repository create command:
  1. Scans for SKILL.md files: Recursively searches the specified directory for SKILL.md files
  2. Reads skill-project.toml: If present, extracts all metadata fields from skill-project.toml (takes priority)
  3. Extracts metadata from SKILL.md: Reads YAML frontmatter as fallback for missing fields
  4. Applies priority: Uses skill-project.toml values for all fields, falls back to SKILL.md frontmatter
  5. Generates marketplace.json: Creates a JSON file with all discovered skills

​
Marketplace.json Format

The command generates marketplace.json in Claude Code standard format: 
{
  "name": "repository-name",
  "owner": {
    "name": "Owner Name",
    "email": "[email protected]"
  },
  "metadata": {
    "description": "Repository description",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "description": "Plugin description",
      "source": "./",
      "strict": false,
      "skills": [
        "./skill-path-1",
        "./skill-path-2"
      ]
    }
  ]
}
For more details, see Marketplace.json Format.

​
Metadata Priority

When generating marketplace.json, the command uses this priority for all metadata fields (name, description, version, author, tags, capabilities, download_url):
  1. skill-project.toml [metadata] section (highest priority)
    • Fields: id (required, no slashes), version (required), description, author, tags, capabilities, download_url
    • All fields from skill-project.toml take precedence
    • The id field must not contain slashes or scope information
  2. SKILL.md frontmatter (fallback)
    • Used for: name (display only), description, author, tags, capabilities
    • name in SKILL.md is for display purposes only, not for package identification
This field-by-field priority allows skill authors to override or supplement SKILL.md metadata with skill-project.toml values. The id field in skill-project.toml is mandatory and must not contain slashes. Skill names for display come from SKILL.md frontmatter only.

​
Directory Structure

The command expects skills in this structure: 
skills/
├── skill1/
│   ├── SKILL.md
│   └── skill-project.toml (optional)
├── skill2/
│   ├── SKILL.md
│   └── skill-project.toml (optional)
└── ...

​
Publishing to Registry

After generating marketplace.json, you can:
  1. Host it on a web server: Place marketplace.json at the root of your skills repository
  2. Configure as repository: Add your repository to skill-project.toml:
[tool.fastskill.repositories]
[[tool.fastskill.repositories]]
name = "my-skills"
type = "git-marketplace"
priority = 1
url = "https://github.com/user/repo.git"
branch = "main"
  1. Access via registry: Skills will appear in the registry web UI when you run fastskill serve --enable-registry

​
See Also