Why Skill Proof?

As your SKILL.md library grows across coding agents, two compounding bottlenecks emerge:

1. Fragmented Multi-Folder Chaos: Skills get duplicated across .agents/skills, .claude/skills, .cursor/skills, .codex/skills, .gemini/skills, and ~/.hermes/skills — wasting disk space and drifting out of sync whenever you improve a skill.
2. System Prompt Bloat & Routing Uncertainty: Stuffing 100+ skill descriptions into every system prompt burns thousands of tokens per turn, while calling a secondary LLM to pick a skill adds latency, cost, and nondeterministic guesses.

Skill Proof solves both problems 100% locally and in-process:

• Global Skill Vault (~/.skill-proof/skills): Consolidates dispersed physical skills into one canonical global vault (vault.json) and links them cleanly into legacy client folders via NTFS junctions or POSIX symlinks.
• Deterministic Zero-LLM Routing: Scores every skill in < 1 ms using a pre-computed inverted index, rapidfuzz C++ token alignment, character n-grams for spaceless scripts (Thai, CJK), contrastive clause splitting ("use X instead of Y"), 6-language negation vetoes ("do not use TDD"), and confidence-gated local embeddings (model2vec / ONNX).
• Tamper-Evident Audit & Tool Gates: Emits SHA-256 hash-chained selection receipts (audit.jsonl) storing derived numbers only (never prompts or secrets) and optionally enforces tool gates until the required skill is loaded.

Live Routing Showcase

1. Explicit Negation Veto + Contrastive Routing + Fleet Agent Hint

Notice how "do not use TDD" vetoes test-driven-development before ranking, selects github-code-review, attaches github-pr-workflow as a companion skill, and recommends the altima reviewer agent:

$ skill-proof select --query "Review this pull request for syntax bugs, but do not use TDD"
decision: selected (lexical_match)
suggested fleet agent: altima
selected: github-code-review score=0.940715 reasons=alias_phrase,name_terms,tag_terms,alias_terms,description_terms companions=github-pr-workflow
candidate: github-code-review score=0.940715 reasons=alias_phrase,name_terms,tag_terms,alias_terms,description_terms
candidate: code-review score=0.876008 reasons=alias_phrase,name_terms,alias_terms,description_terms
candidate: github-pr-workflow score=0.852364 reasons=alias_phrase,tag_terms,alias_terms

2. Natural-Language Symptom Routing (Zero Exact Skill-Name Tokens)

Even when the user describes a symptom ("my page keeps crashing after login") without naming any skill, synonym bridges and morphology routing resolve the exact debugging playbook and companion test skill:

$ skill-proof select --query "my page keeps crashing after login"
decision: selected (lexical_match)
suggested fleet agent: sora
selected: systematic-debugging score=0.796145 reasons=alias_phrase,alias_terms companions=test-driven-development
candidate: systematic-debugging score=0.796145 reasons=alias_phrase,alias_terms
candidate: planning-with-files score=0.076061 reasons=description_terms
candidate: caveman score=0.035353 reasons=description_terms

The Global Skill Vault (~/.skill-proof/skills)

Instead of scattering skill copies across every IDE and CLI, Skill Proof places ~/.skill-proof/skills at the top of the root discovery hierarchy (vault root):

flowchart TD
    Roots["Dispersed Agent Roots<br/>• ~/.agents/skills<br/>• ~/.claude/skills<br/>• ~/.cursor/skills<br/>• ~/.gemini/skills<br/>• ~/.hermes/skills"] -->|"skill-proof vault migrate"| Vault[("Global Skill Vault<br/>~/.skill-proof/skills<br/>(Canonical Single Source of Truth)")]

    Vault -->|"Direct MCP Discovery"| MCP["MCP Clients<br/>(skill_select / skill_search / skill_read)"]
    Vault -->|"skill-proof vault pin / link-all<br/>(NTFS Junctions / Symlinks)"| Legacy["Legacy Folder-Based Agents"]

# 1. Migrate all physical skills from detected agent roots into ~/.skill-proof/skills
skill-proof vault migrate

# 2. Inspect global vault inventory and per-client linkage health
skill-proof vault status

# 3. Pin a specific skill (or link all vault skills) into a client directory via NTFS junction / symlink
skill-proof vault pin --skill systematic-debugging --to ~/.claude/skills
skill-proof vault link-all --to ~/.cursor/skills

Quick Start

1. Universal One-Command Auto-Install (Recommended)

Install skill-proof, register its stdio MCP server across all detected AI coding clients, and consolidate your skills into the global vault:

pip install skill-proof-router
skill-proof install
skill-proof vault migrate

skill-proof install detects and atomically updates:

• Claude Code (~/.claude.json) & Claude Desktop (claude_desktop_config.json)
• Google Antigravity & Antigravity IDE (~/.gemini/config/mcp_config.json, ~/.gemini/antigravity/mcp_config.json)
• Gemini CLI (~/.gemini/settings.json) & Codex CLI (~/.codex/config.toml)
• Cursor (~/.cursor/mcp.json), Windsurf, VS Code (Copilot), OpenCode, and Cline

Verify client registration and catalog state:

skill-proof clients
skill-proof status
skill-proof scan

2. Hermes Agent Native Plugin

# Linux / macOS
git clone https://github.com/Stxyu-p/skill-proof.git ~/.hermes/plugins/skill-proof

# Windows (PowerShell)
git clone https://github.com/Stxyu-p/skill-proof.git "$env:LOCALAPPDATA\hermes\plugins\skill-proof"

hermes plugins enable skill-proof

How Two-Tier Routing Works

flowchart LR
    Q(["User Request"]) --> Dialogue["1. Dialogue & Negation Layer<br/>• Session focus ('same skill')<br/>• Contrastive split ('X not Y')<br/>• 6-language negation veto"]
    Dialogue --> Lex["2. Inverted-Index Lexical + Fuzzy Ranker<br/>• IDF token & phrase overlap<br/>• Thai/CJK character n-grams<br/>• rapidfuzz C++ similarity"]
    Lex --> FastGate{"3. Clear Winner?<br/>score >= 0.55 &<br/>margin >= 0.18"}
    FastGate -- "Yes (lexical_fastpath)" --> Decide["4. Three-State Decision<br/>• selected (score >= min_score, margin >= min_margin)<br/>• ambiguous (shortlist top-k)<br/>• no_match (abstain cleanly)"]
    FastGate -- "Borderline & Vectors Enabled" --> Vec["Confidence-Gated Embeddings<br/>(local ONNX / model2vec / gateway)<br/>+ RRF Fusion"]
    Vec --> Decide

Three-State Decision Rules

• selected (Clear Winner): Top candidate meets min_score (default 0.28) AND leads the runner-up by at least min_margin (default 0.05). When score >= 0.55 and margin >= 0.18, the embedding layer is bypassed entirely (provider_used=lexical_fastpath).
• ambiguous (Close Runner-Up): Multiple candidates cluster within min_margin. Skill Proof returns a shortlist of up to max_candidates (default 3) instead of guessing.
• no_match (Clean Abstention): Nothing clears threshold. Skill Proof abstains so an unrelated skill is never forced onto a turn.

Architecture & Key Modules

System Footprint & Speed

MCP Server & Universal Client Installer

When registered via skill-proof install, any MCP-capable host gains five deterministic tools:

CLI, Hermes & Configuration Reference

plugins:
  enabled:
    - skill-proof
  entries:
    skill-proof:
      settings:
        mode: nudge                       # nudge (default), observe, or enforce-tools
        reduce_skill_prompt: false        # opt-in; confident selection replaces the full index
        embedding_provider: off           # off (default), local, or gateway
        embedding_model: Xenova/multilingual-e5-small
        min_score: 0.28
        min_margin: 0.05
        catalog_cache_ttl_ms: 1000        # reuse host-filtered catalog within TTL window
        block_modified_hub_skills: false  # exclude hub skills whose bundle SHA-256 changed
        session_memory: true              # resolve follow-ups like "use the same skill"
        audit_log: true                   # append derived-numbers hash-chained audit records

Recommended Ecosystem Combo

While Skill Proof works standalone as your skill vault and deterministic router, pairing it with MemCore and trimtok completes the Global Agent Trinity — uniting every AI coding client on your machine (Claude Code, Cursor, Antigravity, Gemini CLI, Codex, VS Code Copilot, Windsurf, OpenCode, Cline, and Hermes) around three shared local hubs:

flowchart LR
    Task(["Developer Request"]) --> SP["Skill Proof<br/>~/.skill-proof/skills<br/>(Deterministic Skill Router)"]
    SP --> MC["MemCore<br/>~/.memcore<br/>(Governed Bitemporal Memory)"]
    MC --> Agent["Any AI Coding Agent"]
    Agent --> TT["trimtok<br/>~/.trimtok<br/>(88.3% Context Compression + CCR #c1)"]
    TT --> Agent

# Install & link the complete Global Agent Trinity across all your IDEs and CLIs
pip install skill-proof-router memcore trimtok
skill-proof install && memcore init && memcore install && trimtok install
skill-proof vault migrate

Verification & License

# Run the complete 383-test offline verification suite + routing & latency gates
pytest -q
python routing_benchmark.py --gate
python phase3_gates.py

Distributed under the MIT License. Designed and maintained by P Choke & SORA.