Skip to main content

​
Registry Index System

FastSkill uses a simple organization/package directory structure for skill distribution. Each skill’s published versions are stored as newline-delimited JSON in a single file.

​
Overview

The registry index is an on-disk NDJSON catalog read by fastskill serve and the registry search endpoints. It is populated externally (for example, by the platform operator that hosts the registry) rather than by a self-hosted CLI write path.

​
Registry Structure

The registry index uses a simple org/package directory structure:

​
Directory Naming

The directory structure is derived from the skill ID (scope/id format):
  • Scope → First directory level (the publishing organization, e.g., “acme”)
  • ID → Second directory level (the package name, must not contain slashes, e.g., “web-scraper”)
Examples:
  • acme/web-scraper → acme/web-scraper/ (scope: “acme”, id: “web-scraper”)
  • myorg/analytics-tool → myorg/analytics-tool/ (scope: “myorg”, id: “analytics-tool”)
  • john/personal-helper → john/personal-helper/ (scope: “john”, id: “personal-helper”)
This structure:
  • Groups skills by organization
  • Provides intuitive navigation
  • Scales well for most use cases
  • Simplifies directory management

​
Version Metadata Format

Each skill has a single file at {scope}/{id} containing newline-delimited JSON entries for all versions. The path is constructed from:
  • scope: The publishing organization (e.g., “acme”)
  • id: The package name from skill-project.toml (must not contain slashes, e.g., “web-scraper”)
Each line is a compact VersionEntry JSON object:

​
Field Descriptions

  • name: Skill identifier
  • vers: Semantic version (e.g., “1.2.3”)
  • deps: Dependencies (currently empty, reserved for future use)
  • cksum: SHA256 checksum of the ZIP artifact
  • features: Feature flags (currently empty, reserved for future use)
  • yanked: Whether this version is yanked (removed from distribution)
  • links: Reserved for future use
  • download_url: URL to download the ZIP artifact
  • published_at: ISO 8601 timestamp of publication

​
Accessing the Registry

​
HTTP Endpoint

The registry index is served over HTTP. Each skill’s index file is accessible at:
Where skill_id follows the format {scope}/{skill-name} (e.g., dev-user/web-scraper). Example:
This returns the newline-delimited JSON entries for all versions of that skill. A browse/search surface is also available:

​
From FastSkill CLI

Skills in a registry can be installed using the standard FastSkill commands:

​
Version Management

​
Version History

All versions are preserved in the registry index. This provides:
  • Complete version history
  • Ability to download any previous version
  • Audit trail of skill evolution

​
Skill Organization

Skills are always stored with an organization prefix:
  • Format: {org}/{package}
  • Organization: The publishing organization (lowercase, filesystem-safe)
  • Package: Skill package name
  • Example: john/my-tool, acme/web-scraper

​
Best Practices

​
Registry Management

  1. Version History: All versions are preserved for audit and rollback
  2. Organization Structure: Skills are organized by publishing organization
  3. Blob Storage: Artifacts are stored securely with checksum verification

​
Security

  1. Checksum Verification: All downloads include SHA256 checksums
  2. Access Control: Registry access is controlled by authentication
  3. Audit Trail: Publishing history is maintained automatically

​
See Also