Marketplace & Registry
Relevant source files
The following files were used as context for generating this wiki page:
The Marketplace & Registry system is a core component of SkillKit designed to aggregate, index, and distribute AI agent skills from various remote and local sources. It allows developers to discover instruction-based skills that teach AI coding agents how to perform specific tasks, such as following React best practices or implementing security patterns. By centralizing these resources, the marketplace enables cross-agent portability, ensuring that a skill authored for one agent can be discovered and utilized by others.
The system functions by fetching skill metadata from GitHub repositories, caching the results locally, and providing search and recommendation capabilities. It supports both official sources, such as Anthropic's courses, and community-contributed repositories. Users can interact with the marketplace via the CLI, an interactive Terminal User Interface (TUI), or programmatically through the core library.
Sources: README.md:14-20, packages/core/src/marketplace/aggregator.ts:1-10, packages/cli/src/commands/marketplace.ts:11-20
Core Architecture
The architecture is built around the MarketplaceAggregator, which manages the lifecycle of skill discovery and indexing. It coordinates between remote fetchers, local file system caching, and search logic.
Aggregation Logic
The aggregator fetches skills from defined SkillSource objects. It attempts to locate skill definitions through several methods:
- Index Files: Searching for
skills.json,index.json, or.skillkit/skills.jsonin the root or specified path of a repository. - README Parsing: If no index file is found, the system parses the repository's
README.mdfor Markdown links pointing to.mdfiles, inferring skill names and descriptions from the surrounding text. - Fallback: If no individual skills are found, the repository itself is indexed as a single skill source.
Sources: packages/core/src/marketplace/aggregator.ts:88-140, packages/core/src/marketplace/aggregator.ts:182-210
System Component Diagram
The following diagram illustrates the relationship between the Aggregator, Skill Sources, and the Local Cache.
The Aggregator acts as the central hub, fetching data from remote GitHub repositories and storing the structured results in a local JSON cache for performance.
Sources: packages/core/src/marketplace/aggregator.ts:25-50, packages/core/src/marketplace/types.ts:98-110
Data Models
The marketplace relies on standardized interfaces to represent repositories and the skills they contain.
SkillSource
Defines the origin of skills, primarily GitHub repositories.
| Field | Type | Description |
|---|---|---|
owner | string | GitHub repository owner/organization. |
repo | string | Repository name. |
name | string | Human-readable name for the source. |
official | boolean | Flag indicating if the source is officially maintained. |
branch | string | The Git branch to fetch from (defaults to main). |
Sources: packages/core/src/marketplace/types.ts:11-28
MarketplaceSkill
Represents a single discoverable skill within the registry.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (format: owner/repo/path). |
name | string | Human-readable skill name. |
description | string | Brief explanation of the skill's purpose. |
tags | string[] | Categorization tags for search and filtering. |
rawUrl | string | Direct URL to the raw content (usually raw.githubusercontent.com). |
Sources: packages/core/src/marketplace/types.ts:33-60
Caching and Performance
To avoid frequent network requests and hitting API rate limits, the MarketplaceAggregator implements a file-based caching system.
- Cache Location: By default, the index is saved to
~/.skillkit/marketplace/marketplace-index.json. - TTL (Time-to-Live): The cache has a default TTL of 1 hour (3,600,000 ms).
- Refresh Mechanism: Users can force a refresh using
skillkit marketplace refresh, which bypasses the cache and re-fetches all sources in parallel.
The sequence shows the Aggregator checking the local file system before resorting to network requests, ensuring fast response times for subsequent queries.
Sources: packages/core/src/marketplace/aggregator.ts:56-82, packages/core/src/marketplace/aggregator.ts:245-280, packages/core/src/marketplace/types.ts:112-117
Search and Recommendations
The marketplace provides advanced discovery features beyond simple listing.
Search Functionality
The search method supports filtering by:
- Query: Matches against name, description, and tags.
- Tags: Filters for specific technology categories (e.g.,
typescript,react). - Source: Limits results to a specific repository.
- Agent Compatibility: Filters skills based on supported AI agents.
Sources: packages/core/src/marketplace/aggregator.ts:285-320
Recommendation Engine
The RecommendationEngine analyzes the local project context (tech stack, languages, frameworks) and scores marketplace skills based on their relevance.
| Scoring Category | Default Weight | Description |
|---|---|---|
framework | 40 | Matches against project frameworks (e.g., Next.js). |
language | 20 | Matches against primary languages (e.g., TypeScript). |
library | 15 | Matches against installed packages (e.g., Tailwind). |
tag | 10 | Matches general intent and categorization. |
Sources: packages/core/src/recommend/types.ts:68-80, packages/cli/src/commands/recommend.ts:100-120
CLI Usage
The marketplace is primarily interacted with via the marketplace command and its subcommands.
# Browse featured skills
skillkit marketplace
# Search for specific functionality
skillkit marketplace search "testing" --limit 5
# List all configured sources
skillkit marketplace sources
# Show tag cloud and popularity
skillkit marketplace tags
Sources: packages/cli/src/commands/marketplace.ts:15-30, packages/cli/src/commands/marketplace.ts:114-140
Summary
The Marketplace & Registry system provides the infrastructure for a shared ecosystem of AI instructions. By aggregating skills from diverse GitHub repositories and providing a local, searchable index, it enables developers to quickly equip their AI agents with specialized knowledge. The integration with a recommendation engine further enhances this by proactively suggesting skills that align with a project's specific technology stack, making the transition between different AI coding agents seamless.