Skip to main content

​
Marketplace.json Format

marketplace.json is a standardized JSON file that describes available skills in a repository. It enables the FastSkill registry to discover and display skills without scanning repository contents.

​
File Location

For sources to be discoverable in the registry, marketplace.json must be accessible at:
  • Git sources: {repository_url}/marketplace.json (via raw content API)
  • Zip URL sources: {base_url}/marketplace.json

​
Schema

{
  "version": "1.0",
  "skills": [
    {
      "id": "skill-id",
      "name": "Skill Name",
      "description": "Skill description",
      "version": "1.0.0",
      "author": "Author Name",
      "tags": ["tag1", "tag2"],
      "capabilities": ["capability1"],
      "download_url": "https://example.com/skills/skill-id.zip"
    }
  ]
}

​
Fields

​
Root Object

FieldTypeRequiredDescription
versionstringYesMarketplace format version (currently “1.0”)
skillsarrayYesArray of skill definitions

​
Skill Object

FieldTypeRequiredDescription
idstringYesUnique identifier for the skill
namestringYesDisplay name of the skill
descriptionstringYesDescription of what the skill does
versionstringYesVersion identifier (semver, date, branch, etc.)
authorstringNoAuthor name or organization
tagsarrayNoArray of tag strings for categorization
capabilitiesarrayNoArray of capability strings
download_urlstringNoURL to download the skill (ZIP file)

​
Generating marketplace.json

Use the fastskill repository create command to generate marketplace.json from a directory of skills: 
fastskill repository create --path ./skills
The command:
  • Scans for SKILL.md files
  • Extracts metadata from YAML frontmatter
  • Uses skill-info.toml version if present
  • Generates the marketplace.json file

​
Example

{
  "version": "1.0",
  "skills": [
    {
      "id": "pdf-processor",
      "name": "PDF Text Extraction",
      "description": "Extract and process text from PDF documents using OCR",
      "version": "1.2.0",
      "author": "FastSkill Team",
      "tags": ["pdf", "ocr", "text-extraction"],
      "capabilities": ["extract_text", "parse_pdf", "ocr_processing"],
      "download_url": "https://skills.example.com/pdf-processor-1.2.0.zip"
    },
    {
      "id": "data-analyzer",
      "name": "Data Analysis Tool",
      "description": "Analyze structured data and generate insights",
      "version": "2.0.0",
      "author": "Data Team",
      "tags": ["data", "analysis", "statistics"],
      "capabilities": ["analyze_data", "generate_charts"],
      "download_url": "https://skills.example.com/data-analyzer-2.0.0.zip"
    }
  ]
}

​
Version Priority

When generating marketplace.json, the version is determined in this order:
  1. skill-info.toml [metadata] version (highest priority)
  2. SKILL.md frontmatter version field
  3. “unknown” if neither is found

​
Validation

The registry validates marketplace.json files:
  • All required fields must be present
  • id, name, and description must not be empty
  • Skills with invalid data are skipped

​
Caching

Marketplace.json files are cached for 5 minutes to reduce network requests. To force a refresh:
  1. Wait 5 minutes for cache expiry
  2. Restart the server
  3. Clear cache manually (future feature)

​
Best Practices

  1. Keep it updated: Regenerate marketplace.json when skills change
  2. Use semantic versioning: Use clear version identifiers
  3. Include all metadata: Provide tags, capabilities, and author information
  4. Test accessibility: Verify the URL is accessible from your environment
  5. Version control: Commit marketplace.json to your repository

​
See Also