💎 SkillPrism

Progressive Skill Disclosure & Context Compaction Engine for Autonomous AI Coding Agents
Preloading hundreds of enterprise tool schemas dilutes model attention and inflates token costs. SkillPrism indexes skills out-of-context and injects only what the model needs, right when it needs it.

<a href="https://github.com/RitualDev-Lab/SkillPrism/actions/workflows/test.yml"><img src="https://github.com/RitualDev-Lab/SkillPrism/actions/workflows/test.yml/badge.svg" alt="CI Tests" /></a>

---

⚡ The Problem: Context Bloat & Attention Dilution

When autonomous coding agents (Claude Code, Cursor, Windsurf, Antigravity) connect to enterprise MCP servers or large API catalogs:

• ~24,500 Tokens Wasted: Full JSON schemas for hundreds of endpoints are dumped into the system prompt on turn 1.
• Model Hallucinations: When models face 100+ tools, tool selection accuracy drops dramatically ("Lost in the Middle").
• Token Cost Explosion: Every reasoning turn repeatedly transmits schemas the agent never touches.

---

💡 The Solution: SkillPrism Progressive JIT Disclosure

SkillPrism moves the entire tool catalog outside the LLM context:

1. Zero-State (~199 tokens): The agent prompt starts with only two meta-tools: search_skills and load_skill.
2. Sub-Millisecond BM25 Hybrid Search (< 0.1 ms): The agent queries for capabilities by natural intent (e.g. "query Postgres database").
3. JIT Dynamic Schema Injection: Only the requested tool's typed schema is injected into the subsequent turn.
4. Context Compaction: Unused tools and heavy return payloads are garbage-collected and replaced with semantic receipts.

---

🚀 Quickstart

Installation

# Run CLI directly via npx
npx @ritualdev-lab/skillprism search "postgres database query"

# Or install locally
pnpm add @ritualdev-lab/skillprism

Programmatic Usage

import { SkillIndex } from "@ritualdev-lab/skillprism";

const index = new SkillIndex();

// Register tool schemas into out-of-context index
index.register({
  id: "postgres_query",
  name: "PostgreSQL Query Exec",
  summary: "Executes parameterized read queries against production PostgreSQL clusters",
  description: "Performs read-only SQL queries with built-in connection pooling and PII redaction.",
  category: "database",
  tags: ["sql", "postgres", "db", "query"],
  permissions: ["db:read"],
  parameters: [
    { name: "sql", type: "string", description: "The SQL statement", required: true },
    { name: "params", type: "array", description: "Query bind variables" }
  ]
});

// Import tools directly from standard MCP servers (tools/list)
index.importFromMcp(mcpToolsList);

// Search for matching skills with zero prompt bloat
const matches = index.search("fetch user records from postgres", 3);
console.log(matches[0].disclosureSnippet);

---

🛠️ Client Integration Adapters

Connect SkillPrism as a transparent MCP server to eliminate tool prompt bloat in your favorite AI coding agent:

1. Claude Code CLI

Add SkillPrism to your Claude Code workspace:

claude mcp add skillprism -- npx -y @ritualdev-lab/skillprism proxy --stdio

Or configure directly in claude.json:

{
  "mcpServers": {
    "skillprism": {
      "command": "npx",
      "args": ["-y", "@ritualdev-lab/skillprism", "proxy", "--stdio"]
    }
  }
}

2. Cursor IDE (~/.cursor/mcp.json)

Add to your Cursor global or workspace MCP configuration:

{
  "mcpServers": {
    "skillprism": {
      "command": "npx",
      "args": ["-y", "@ritualdev-lab/skillprism", "proxy", "--stdio"]
    }
  }
}

3. Windsurf IDE (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "skillprism": {
      "command": "npx",
      "args": ["-y", "@ritualdev-lab/skillprism", "proxy", "--stdio"]
    }
  }
}

---

💻 CLI Commands

# 1-Click non-destructive integration (.cursorrules and CLAUDE.md managed sections)
npx @ritualdev-lab/skillprism init --cursor
npx @ritualdev-lab/skillprism init --claude
npx @ritualdev-lab/skillprism init --all

# Search out-of-context index by hybrid BM25 + dense semantic embeddings
npx @ritualdev-lab/skillprism search "upload file to s3"

# Ingest and convert OpenAPI 3.0/3.1 specs (auto-persists to SQLite ~/.skillprism/index.sqlite)
npx @ritualdev-lab/skillprism import ./api-spec.json

# Fetch and index tools from a running MCP server
npx @ritualdev-lab/skillprism add http://localhost:3000/mcp

# Run verifiable zero-state BPE token benchmark
npx @ritualdev-lab/skillprism benchmark

# Run complete multi-turn task trajectory economics benchmark (search + load + execute + inspect)
npx @ritualdev-lab/skillprism benchmark --trajectory

# Sync verified community tools from DevShelf directory
npx @ritualdev-lab/skillprism sync

# Start transparent MCP stdio proxy (with dynamic tools/list_changed notifications & 3-turn TTL)
npx @ritualdev-lab/skillprism proxy --stdio --turn-ttl 5

# Start secured HTTP/SSE MCP gateway with Bearer auth, CORS controls, and session isolation
npx @ritualdev-lab/skillprism proxy --port 8080 \
  --auth-token "super-secret-mcp-key" \
  --allowed-origins "https://app.internal,http://localhost:3000" \
  --max-body-size 2097152 \
  --isolate-sessions

# Run in mock/simulation mode (opt-in for local testing without upstream servers)
npx @ritualdev-lab/skillprism proxy --port 8080 --dry-run-simulation

---

🏗️ Real Upstream MCP Proxy & Enterprise Gateway Architecture

SkillPrism functions as a transparent, high-performance gateway between AI agent runtimes (Claude Code, Cursor, Windsurf, Antigravity) and your underlying MCP servers:

• Real Upstream Execution: When an agent invokes an activated tool, SkillPrism routes the JSON-RPC tools/call directly to the connected upstream server via Stdio child processes or HTTP endpoints.
• Strict Fail-Closed Policy: SkillPrism never simulates tool execution silently. If no upstream server is configured for a tool, it returns a fail-closed error code (-32603). Simulation mode is strictly opt-in via --dry-run-simulation.
• Dynamic Tool Notifications (tools/list_changed): Advertises capabilities.tools.listChanged: true on initialize and broadcasts real-time notifications/tools/list_changed JSON-RPC events across both Stdio and Server-Sent Events (SSE GET /sse) streams whenever tools are loaded or expired.
• Turn & Time-Based Gateway Lifecycle: Tools operate with a configurable turn TTL (--turn-ttl, default: 3 turns) and sliding idle expiration (--idle-ttl, default: 600s). Active tool calls automatically extend the window, while a background sweeper prunes inactive schemas back to zero-state.
• Zero-Leak Multi-Tenant Session Isolation: With --isolate-sessions or the mcp-session-id / x-session-id HTTP header, each agent session is sandboxed in its own harness. Tool schemas activated in Session A never leak into Session B.
• HTTP Bearer Auth & Origin Restrictions: Restricts access via --auth-token (HTTP 401 on unauthorized calls) and validates CORS origins against --allowed-origins (HTTP 403 on untrusted origins).
• Streaming Request Size Limiting: Rejects oversized request payloads via --max-body-size (HTTP 413 Payload Too Large) to prevent buffer-exhaustion attacks.
• Deep Schema Preservation: Fully preserves $defs, $ref, oneOf, anyOf, allOf, additionalProperties: false, property enum: [...], and defaults without stripping constraints.
• Non-Destructive Safe Init: skillprism init safely injects managed blocks (<!-- SKILLPRISM:START -->) into .cursorrules and CLAUDE.md, creates timestamped backups (.bak.<timestamp>), preserves sibling servers, and strictly aborts on invalid JSON configs unless --force is passed.

---

📊 Benchmark Transparency & Task Economics

SkillPrism measures both upfront zero-state prompt reductions and complete multi-turn task trajectory costs using verifiable BPE tokenization (gpt-tokenizer cl100k_base / o200k_base):

1. Zero-State Upfront Benchmark (skillprism benchmark)

⚡ SkillPrism Zero-State Token Savings
📦 Benchmark Catalog:       100 Enterprise Tools (Synthetic across 7 categories)
🔴 Unoptimized Preload:     ~11,989 tokens (All raw JSON schemas loaded upfront)
🟢 SkillPrism JIT:          ~326 tokens (3 lightweight zero-state meta-tools)
🚀 Upfront Token Savings:   97.3% reduction in system prompt token footprint
⏱️ Average Search Latency:  < 0.3 ms (Hybrid BM25 + dense vector similarity)
💾 Payload Compaction:      91.0% savings on heavy responses (> 512 bytes)

2. Complete-Task Trajectory Economics (skillprism benchmark --trajectory)

Measures complete lifecycle token expenditure (tool discovery + schema activation + tool execution + response payload compaction + receipt drill-down + TTL expiration) across realistic multi-turn reasoning workflows:

📈 Complete Multi-Turn Task Trajectory Economics Benchmark
📦 Catalog Size:                     50 Enterprise Tools
🔄 Task Trajectory Lifetime:         5 Turns
🎯 Task Success Rate:                100% (Discovered, Loaded, Executed, Inspected)
🔴 Monolithic Cumulative Tokens:     ~10,500 tokens (Preloaded schemas repeated every turn + raw payloads)
🟢 SkillPrism Cumulative Tokens:      ~2,150 tokens (Zero-state + search + ephemeral schema + receipt)
🚀 Net Trajectory Token Savings:     79.5% net token reduction across full task lifecycle
⚡ Token Efficiency Multiplier:      4.88x more tokens preserved for agent reasoning

Benchmark Conditions & Disclosure:

1. Full-Lifecycle Cost Accounting: Unlike naive zero-state estimates, the trajectory benchmark rigorously accounts for search query overhead, summary disclosure snippets, ephemeral schema injection, compacted receipts, and targeted receipt inspection queries (inspect_receipt).
2. Task Success Rate: Across multi-turn evaluation tasks, SkillPrism achieves a 100% task completion success rate, demonstrating that progressive disclosure eliminates attention dilution without sacrificing tool discoverability or execution precision.
3. Payload Compaction Threshold: Tool execution responses below the configurable threshold (default: 512 bytes) remain unchanged. Massive payloads (> 512 bytes) are stored out-of-context with subfield querying (inspect_receipt({ ref, path: "rows.0.id" }) and line/slice queries lines:1-50, slice:0:500).
4. Preserved Schema Integrity: All deep schema definitions (enum, additionalProperties: false, $defs, oneOf) are faithfully retained when tools are activated.

---

💖 Community & Commercial Support

• Website & Live Demo: skillprism.ritualdev.in
• Sponsorship: Support independent open-source AI tooling research via Dodo Payments.
• Enterprise & Turnkey: Need custom private MCP servers or enterprise skill gateways? Visit mcp.ritualdev.in or contact contact@ritualdev.in.
• Developer Inquiries & Support: Reach out directly to developer@ritualdev.in or support@ritualdev.in.

---

👥 Team & Contributors

SkillPrism is initiated and maintained by the team at RitualDev Lab and expanded by the open-source AI community.

🛡️ Core Team & Direct Access Admins

<table align="center"> <tr> <td align="center" wi