Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uniskill.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Every request to /v1/execute (or /v1/execute/:skillName) passes through 8 sequential gates before a response is returned. All gates after ⑦ are non-blocking via ctx.waitUntil. 
① Key Format Check     → Must start with "us-", else 401
② Identity Resolution  → SHA-256(key) → KV auth:hash:{hash} → User UID
                         miss: Supabase DB fallback + KV write-back (TTL=30d)
③ Profile Load         → KV profile:{uid} → legacy key migration → DB fallback
                         contains: credits, tier, username (self-healing write-back)
④ Skill Lookup         → Private KV → Official KV → Market KV
                         full miss: 400 "Skill not registered"
⑤ Rate Limit Check     → Tier-based RPM quota, KV atomic counter, 429 on exceed
⑥ Credit Pre-check     → currentCredits < creditsPerCall → 402 (no charge)
⑥.₅ Experience Inject  → Vectorize input via Voyage AI → Supabase RPC similarity search
                         match ≥ 0.85: fetch preventionPatch, inject into request
⑦ Execute              → isHardcoded? Native Handler : Generic Executor
                         Native fail: Tactic B — append patch to error text
                         LLM skill: Tactic C — inject into messages[-1].content
⑧ Bill + Telemetry     → ctx.waitUntil (non-blocking):
                         a. deductCredit → KV write-back + Vercel Webhook → Supabase
                         b. recordSkillCall → Supabase RPC record_skill_usage
                         c. saveInvocationLog → POST /rest/v1/invocations

​
Native vs. Generic Execution

​
Native Skills (Hardcoded)

Eight official skills bypass the Generic Executor and use dedicated TypeScript handlers:
Skill IDHandlerUpstream
uniskill_weatherroutes/weather.tsOpen-Meteo
uniskill_scraperoutes/scrape.tsJina AI Reader
uniskill_mathroutes/math.tsLocal engine
uniskill_timeroutes/time.tsSystem timezone
uniskill_georoutes/geo.tsMapbox Geocoding
uniskill_crypto_utilroutes/crypto_util.tsWeb Crypto API
uniskill_github_trackerroutes/github-tracker.tsGitHub API
uniskill_smart_chartroutes/uniskill-smart-chart.tsQuickChart.io

​
Generic Executor (engine/executor.ts)

All registry/market/private skills run through the declarative template engine:
  • {{param}} placeholders — resolved in URL, headers, and request body
  • {{SECRETS.KEY}} — decrypted from user’s AES-256 encrypted KV secrets
  • Declarative template detection — suppresses auto-appending when {{...}} is present
  • Response mapping — JSONPath extraction via response_mapping
  • 10s hard timeout via AbortController
  • Fail-fast circuit breaker — missing SECRETS placeholder → immediate error, no upstream call

​
Experience Injection Detail

Before execution (step ⑥.₅), the gateway performs a semantic similarity search:
  1. Noise keys (session_id, trace_id, etc.) are pruned from params
  2. Remaining params are vectorized via Voyage AI (voyage-code-3, 1024-dim)
  3. Vector queried against skill_learnings table via match_learnings_by_input RPC (threshold: 0.85)
  4. On match: preventionPatch string is retrieved and injected via:
    • Tactic B (native handlers): appended as plaintext suffix to error response body
    • Tactic C (LLM skills): injected into messages[-1].content in the request body