skill-scout

🧭 Skill Scout Suite

Universal JIT Skills & Hierarchical Context Tiering Engine (L1 / L2 / L3) for AI Coding Agents

Eliminate up to 92% of input token waste (Context Bloat) and restore sharp reasoning across your AI coding agents through L1 / L2 / L3 hierarchical context tiering, sub-80ms Just-In-Time (JIT) skill routing, and native 7-harness transpilation.

The Problem • L1/L2/L3 Architecture • 2026 Models Benchmark • Quickstart & CLI • 7-Harness Matrix • Security

🚨 The Problem: Context Bloat & "Lost in the Middle"

In modern AI-assisted software engineering (Google Antigravity, Cursor, Claude Code, Windsurf, GitHub Copilot, OpenAI Codex, OpenCode), developers routinely install 30 to 50 skills, .mdc rules, and system instructions globally. This creates three severe bottlenecks:

1. Financial & Rate-Limit Drain: Keeping 40 global skills active silently injects ~24,000 input tokens into every single conversation turn—even when you only ask to rename a variable. Over a 100-turn coding session, that burns 2.4 million wasted input tokens.
2. Cognitive Degradation (Lost in the Middle): When an LLM receives simultaneous instructions for React, Rust, Kubernetes, OWASP Pentesting, and SQL optimization in the same system prompt, its attention dilutes—causing API hallucinations, conflicting rule behavior, and slower Time-to-First-Token (TTFT).
3. Blind Static Installation & Context Drift: Conventional tools dump static files into global folders with zero usage telemetry, zero per-project isolation, and zero drift detection when a repository's stack changes.

🏛️ 3-Tier Context Architecture (L1 / L2 / L3)

Inspired by CPU cache hierarchies and progressive disclosure (pbakaus/impeccable), Skill Scout Suite organizes agent knowledge into three strict tiers:

• ⚡ L1 Tier — Global (Ultra-Light): Keeps only the 3 Core Orchestration Meta-Skills (skill-scout, skill-project, skill-curator) active globally. Residual overhead is minimal (~1,200 tokens total).
• 📦 L2 Tier — Project Workspace (Isolated & Transpiled): Contains strictly the 3 to 6 domain skills matching the active repository's stack, natively transpiled into your AI harness (.agents/skills/, .cursor/rules/*.mdc, .claude/skills/, CLAUDE.md, .windsurfrules, .github/instructions/*.instructions.md, or AGENTS.md) and tracked by the atomic manifest .agents/skills/project-skills.json.
• 🧊 L3 Tier — Cold Storage Vault (JIT Catalog): Indexes 100 to 5,000+ specialized skills offline (catalog.json) at 0 resting tokens, searched in < 80ms and streamed Just-In-Time (JIT) into memory only when a task requires them.

flowchart TD
    Dev["👩‍💻 Developer / AI Coding Agent"] --> Engine["🧭 Skill Scout Suite CLI & Root Router"]

    subgraph CoreMeta["L1 Tier: 3 Global Meta-Skills (~1.2k tokens)"]
        Scout["🔍 1. skill-scout<br/>(Tokenized Fuzzy Search & Ephemeral JIT Read)"]
        Project["📦 2. skill-project<br/>(L2 Isolation, 7-Harness Transpiler & Drift Doctor)"]
        Curator["🧠 3. skill-curator<br/>(Grill-Me Interview & SHA-256 Garbage Collector)"]
    end

    Engine --> Scout
    Engine --> Project
    Engine --> Curator

    subgraph Tiers["Execution & Storage Tiers"]
        JIT["⚡ Ephemeral JIT Session<br/>(stdout / Zero Disk Residue)"]
        L2["📂 L2 Tier: Active Project Workspace<br/>(.agents | .cursor/.mdc | CLAUDE.md | .windsurfrules | .github | AGENTS.md)"]
        L3["🧊 L3 Tier: Cold Storage Vault<br/>(Indexed Catalog @ 0 Resting Tokens)"]
    end

    Scout -- "Mode A: One-Off Task (scout read)" --> JIT
    Scout -- "Sub-80ms Query (scout search / recommend)" --> L3
    Project -- "Mode B: Native Transpilation (scout install)" --> L2
    Project -- "Bounded Drift Audit (scout doctor)" --> L2
    Curator -- "SHA-256 Verified Archive (scout curate)" --> L3
    Curator -- "Smart Stack Migration" --> L2

💰 2026 Frontier Models Benchmark: Token & Financial Savings

Real-world comparison between an unoptimized setup (40 Global Skills = ~24,000 tokens/turn) vs. Skill Scout Suite L1/L2/L3 Architecture (3 L1 Meta-Skills + 2 L2 Project Skills = ~1,920 tokens/turn, saving 2,208,000 input tokens per 100-turn session — a 92% reduction in context bloat):

[!TIP] Run npx skill-scout stats at any time to compute exact token and USD savings based on your actual directories and the active AI model auto-detected on your machine.

🚀 Quickstart & CLI Reference

Skill Scout Suite provides a Dual Experience: rich terminal output for human developers and strictly typed JSON output (--json) for autonomous execution by AI coding agents.

1. One-Command Setup (setup)

Install the 3 core Meta-Skills (skill-scout, skill-project, skill-curator) into your active AI harness or via the Agent Skills ecosystem registry:

# Interactive / One-Command Setup
npx skill-scout setup

# Or via the Agent Skills ecosystem registry
npx skills add rysumo/skill-scout

2. Index Your L3 Skills Vault (index)

Automatically scans and indexes your local skill library (auto-detects ~/.gemini/config/skills_library, SKILL_SCOUT_VAULT, or ~/.skill-scout/vault):

npx skill-scout index
npx skill-scout index --vault "~/.skill-scout/vault" --json

3. Tokenized Fuzzy Search with Bilingual Synonym Graph (search)

Searches your catalog in < 80ms using formal relevance weights (100 pts exact match, 80 pts exact token, 50 pts prefix, 40 pts synonym/category) with zero substring false positives. The built-in Synonym Graph natively supports bilingual EN + PT-BR intent queries (e.g., "db" or "banco" matches postgres, prisma, sql, sqlite):

npx skill-scout search "postgres"
npx skill-scout search "security" --category security --limit 5 --json

4. Ephemeral Just-In-Time Reading (read)

Streams a skill's instructions directly into session memory (stdout) for one-off tasks without creating any files in your project repository:

npx skill-scout read "zod-validation-expert"
npx skill-scout read "playwright-testing" --json

5. Bounded Context Verification & Stack Recommendation (doctor & recommend)

Scans your repository's manifests (package.json, pyproject.toml, Cargo.toml, go.mod, docker-compose.yml, Dockerfile), recommends high-impact skills from the L3 Vault, and performs read-only drift detection (CONTEXT_STALE_MISSING_SKILL, ORPHANED_MANIFEST_ENTRY, GLOBAL_BLOAT_HIGH) without modifying files as an unasked side effect:

npx skill-scout doctor
npx skill-scout recommend --json

6. L2 Workspace Installation & 7-Harness Transpilation (install, list, remove)

Installs a skill into the L2 (Workspace) tier, transpiles it into your AI harness's native rule format, and records it atomically in .agents/skills/project-skills.json:

# Auto-detects the repository's AI harness or transpiles explicitly for the chosen target
npx skill-scout install "typescript-pro"
npx skill-scout install "nextjs-app-router" --target cursor
npx skill-scout install "security-audit" --target copilot
npx skill-scout install "architecture-patterns" --target claude --claude-mode claude_md --force

# List and remove active workspace skills
npx skill-scout list
npx skill-scout remove "nextjs-app-router"

7. Grill-Me Interactive Context Curation (curate)

Conducts a bounded diagnostic interview of your global skills (primary domain, daily vs. occasional stacks, idle days threshold) and migrates excess skills from L1 (Global) to L2 (Project) or L3 (Vault) with cryptographic SHA-256 verification:

# Interactive terminal interview
npx skill-scout curate

# Safe dry-run simulation (no files modified)
npx skill-scout curate --dry-run --json

# Non-interactive automated archival for skills idle > 14 days
npx skill-scout curate --yes --idle-days 14

8. Token Calculator & 2026 Model Detector (stats & config)

Displays L1, L2, and L3 token weights, context bloat reduction percentage, and USD savings across 2026 models:

npx skill-scout stats
npx skill-scout stats --model claude-opus-5-5 --json

# Configure default model, target harness, or Vault path
npx skill-scout config set model gemini-4-argon
npx skill-scout config set vault "~/.gemini/config/skills_library"
npx skill-scout config get

🌐 Multi-Harness Compatibility Matrix (7 Platforms)

The Universal Target Engine auto-detects repository markers or accepts --target <platform>, transpiling a single Vault skill into any of the 7 supported AI coding harnesses:

🛡️ Security & Defensive Engineering

Engineered under Spec-Driven Development (SDD) and Defense-in-Depth principles:

• 🔒 Strict Path Traversal Prevention: Every skill identifier and file path undergoes canonical validation (path.resolve + base directory prefix check). No read or write operation can escape the Vault or Workspace root.
• 🧬 SHA-256 Verified Archiving: When migrating a skill from L1 Global to L3 Vault, the engine performs a physical copy, computes the SHA-256 cryptographic digest of source and destination files, and only removes the global original if the hashes match bit-for-bit. Zero reliance on OS symlinks or Windows Administrator privileges.
• ⚛️ Atomic Manifest Writes (project-skills.json): State mutations write to a process-isolated temporary file followed by an atomic OS rename, preventing JSON corruption even when parallel subagents install skills concurrently.
• 📐 Schema-First Executable Contracts (Zod): Every CLI input, configuration file (config.json), telemetry record (state.json), and catalog index (catalog.json) is validated at the boundary using strict Zod schemas (z.object(...).strict()) with zero any types.

📄 License

Distributed under the MIT License. Crafted with focus on software craftsmanship and context efficiency by Lucas Andrioli (rysumo).