Skill Registry

Three-Tier Priority

Skills are stored in Cloudflare KV under three namespaced layers, resolved with strict priority:

Priority	KV Key Prefix	Scope
1 (highest)	`skill:private:{uid}:{skillId}`	Per-user custom skills
2	`skill:official:{skillId}`	UniSkill curated tools
3	`skill:market:{skillId}`	Community-published skills

Resolution stops at the first hit. A private skill always shadows an official skill of the same name.

Unified JSON Format

Every skill entry is stored as a single JSON blob:

{
  "id": "uniskill_weather",
  "source": "official",
  "skill_uid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "meta": {
    "name": "Global Weather",
    "description": "...",
    "emoji": "🌤",
    "tags": ["weather", "forecast"],
    "parameters": {
      "type": "object",
      "properties": {
        "location": { "type": "string", "description": "City name or coordinates" }
      },
      "required": ["location"]
    }
  },
  "config": {
    "endpoint": "https://api.open-meteo.com/v1/forecast",
    "method": "GET",
    "plugin_hook": "weather"
  },
  "credits_per_call": 1
}

Full KV Namespace

Key Pattern	Purpose
`skill:official:{skillId}`	Official skills
`skill:private:{uid}:{skillId}`	Private skills (UID-isolated)
`skill:market:{skillId}`	Market skills
`auth:hash:{keyHash}`	Key hash → User UID (TTL=30d)
`profile:{uid}`	User profile JSON (credits + tier + username)
`skill:secrets:{uid}`	User global secrets (AES-256 encrypted)
`skill:secrets:{uid}:{skillId}`	Skill-level secrets (AES-256 encrypted)
`ratelimit:{keyHash}:{minute}`	Per-minute request counter
`mcp_registry:tools_cache`	MCP tools/list cache (manual invalidation)
`mcp_broadcast:tools_changed`	Global tool refresh broadcast timestamp

Deprecated (self-healing migration in progress): credits:{uid}, tier:{uid}, user:uid:{hash}

Parsing

engine/parser.ts (SkillParser.parse()) handles two formats:

Unified JSON (primary) — detected by input.trim().startsWith('{'), parsed directly
Legacy Markdown (fallback) — H1 as name, YAML block as implementation, JSON block as parameters

The parser normalizes both formats into a standard SkillSpec struct before execution.

Admin Sync

Skills are pushed into KV by uniskill-web via:

POST /v1/admin/sync_skill — single skill upsert (accepts ADMIN_KEY or INTERNAL_API_SECRET)
POST /v1/admin/sync_cache — bulk cache invalidation
POST /v1/admin/refresh-tools — writes mcp_broadcast:tools_changed to trigger global MCP tool list refresh

Getting Started

Core Concepts

Skill Catalog

Internals

Three-Tier Priority

Unified JSON Format

Full KV Namespace

Parsing

Admin Sync

​Three-Tier Priority

​Unified JSON Format

​Full KV Namespace

​Parsing

​Admin Sync

Three-Tier Priority

Unified JSON Format

Full KV Namespace

Parsing

Admin Sync