Skill Registration

Skill Registration publishes a source skill definition (from GitHub, local directories, or package repositories) into the central enterprise Castor Registry, generating multi-modal vector embeddings and updating HNSW vector indexes for real-time semantic discovery.

1. Registering Source Skills (`cstr register`)

Use cstr register <source_uri> to parse a source skill and register it with the central server:

# Register a skill from a remote GitHub repository
cstr register github://google/skills@main/tree/main/skills/cloud/gemini-api

# Register a skill from a local development directory
cstr register file:///path/to/enterprise-skill

When cstr register submits a skill to Castor Registry:

Frontmatter & Asset Parsing:
- Parses YAML frontmatter (name, description, version, category, tags, trigger_phrases, execution_hints).
- Recursively reads text references (references/*.md) and executable examples (examples/*).
- Reads binary multi-modal assets (references/*.png, *.jpg, *.webp, *.pdf, *.wasm, *.proto).
Multi-Chunk Sliding-Window Embedding Generation:
- Generates skill-level embeddings from concatenated metadata and system instructions.
- Offloads granular chunking to non-blocking worker goroutines (CastorService.startBackgroundWorkers), decomposing instructions and references into ≤ 900-character sliding windows with 80-character overlap (embedding.SplitTextIntoChunks).
- Concurrently generates itemized embeddings for each attached reference and example via the active provider (pkg/embedding/vertex or pkg/embedding/alloydb).
- Embeds binary media using the configured multimodal embedding model.
Poly-Column pgvector Persistence:
- Populates vector columns matching the active model dimension (embedding_768, embedding_1408, or embedding_3072).
- Updates PostgreSQL/AlloyDB HNSW index partitions (skills_embedding_768_hnsw_idx, skills_embedding_1408_hnsw_idx).
Canonical URI Assignment:
- Generates deterministic UUID skill_id (e.g. sk-9b1deb4d).
- Allocates canonical URI: castor://skills/{domain}/{category}/{name}/{version}.

sequenceDiagram
    participant CLI as cstr CLI
    participant Config as ~/.castor/.env.toml
    participant Server as Castor Registry
    participant Workers as Worker Goroutines (x4)
    participant Embed as Embedding Provider (Vertex/AlloyDB)
    participant DB as pgvector DB

    CLI->>Config: Load CASTOR_SERVER_URL & CASTOR_API_KEY
    CLI->>CLI: Parse source skill frontmatter, references & assets
    CLI->>Server: POST /api/v1/skills (Header: X-API-Key, Body: SkillCreateRequest)
    Server->>DB: INSERT INTO skills (initial record)
    Server->>Workers: Dispatch embeddingJob to embedJobChan
    Server-->>CLI: 201 Created (SkillResponse with castor:// URI)
    Workers->>Embed: GenerateSkillEmbeddings(900-char sliding chunks)
    Embed-->>Workers: Return 1408d / 768d vector embeddings
    Workers->>DB: SaveSkillEmbeddings(chunks -> skill_embeddings)

3. Server HTTP Endpoint (`POST /api/v1/skills`)

POST /api/v1/skills HTTP/1.1
Host: localhost:8000
X-API-Key: cstr_live_YOUR_API_KEY_HERE
Content-Type: application/json

{
  "name": "gemini-api",
  "description": "Integration skill for Google Gemini API on Vertex AI",
  "instructions": "# Gemini API Skill...",
  "source_uri": "github://google/skills@main/tree/main/skills/cloud/gemini-api",
  "category": "cloud",
  "tags": ["gemini", "vertex", "ai", "llm"],
  "trigger_phrases": ["call gemini", "invoke multimodal model"]
}

Response (201 Created):

{
  "id": "sk-9b1deb4d",
  "name": "gemini-api",
  "uri": "castor://skills/example.com/cloud/gemini-api/1.0.0",
  "source_uri": "github://google/skills@main/tree/main/skills/cloud/gemini-api",
  "version": "1.0.0",
  "created_at": "2026-08-09T17:30:00Z"
}

Skill Registration

Skill Registration

1. Registering Source Skills (cstr register)

2. Multi-Modal Ingestion & Embedding Pipeline

3. Server HTTP Endpoint (POST /api/v1/skills)

1. Registering Source Skills (`cstr register`)

3. Server HTTP Endpoint (`POST /api/v1/skills`)