Przejdź do treści
Biblioteka skilli
Programowanie · Research

token-optimizer

/token-optimizer

Przeszukuje kod i nawiguje architekturą przez analizę AST zamiast grep i find, co zmniejsza zużycie tokenów.

Repozytorium
tokensafe ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Przeszukuje kod i nawiguje architekturą przez analizę AST zamiast grep i find, co zmniejsza zużycie tokenów.

Oryginalny opis (EN)

MANDATORY code inspection and architecture navigation skill. Activate whenever inspecting files, searching code, locating components/functions/classes, reading implementations, analyzing dependencies, or navigating codebase architecture. Replaces wasteful terminal grep/find with zero-loss AST smart slicing (-90% tokens), extracts definitions with 1-hop dependencies, enforces security guards, and tracks token efficiency metrics.

Jak działa

  1. MANDATORY AGENT DIRECTIVES
  2. Core MCP Tools (tokensafe)
  3. Context Governor & History Compactor
  4. LLM Prompt Cache Optimization
  5. Proof-of-Savings Turn Footer (always in English)
Sekcje z nagłówków SKILL.md, w oryginale · 113 linii, 1 276 słów
Podgląd SKILL.md
---
name: token-optimizer
description: >-
  MANDATORY code inspection and architecture navigation skill.
  Activate whenever inspecting files, searching code, locating components/functions/classes,
  reading implementations, analyzing dependencies, or navigating codebase architecture.
  Replaces wasteful terminal grep/find with zero-loss AST smart slicing (-90% tokens),
  extracts definitions with 1-hop dependencies, enforces security guards, and tracks token efficiency metrics.
---

# TokenSafe Optimization & Architecture Intelligence Skill

TokenSafe is the zero-loss token economy, context governor, and security engine for autonomous AI coding agents.
It replaces brute-force terminal crawls (`grep`, `find`, `cat`) with deterministic AST symbol extraction,
folds multi-turn conversation history, slices verbose tool outputs, and guards against secret leaks and destructive actions.

---

## MANDATORY AGENT DIRECTIVES

1. **ZERO RAW TERMINAL GREP / FIND (HARD-BLOCKED & REPLACED BY `scoped_search`)**:
   - Strictly NEVER run `grep`, `egrep`, `ripgrep`, or `find` in `run_command` on source code files (`.ts`, `.tsx`, `.py`, `.js`, `src/`, `views/`, `components/`).
   - Raw code searches via bash burn thousands of context tokens and are blocked by **TokenSafe Guard** (`decision: deny`).
   - **Mandatory Search Tool (`scoped_search`)**: ALWAYS call `tokensafe:scoped_search(query, path=".", scope="code")` to search for text, identifiers, or symbol definitions across unknown files (-90% tokens). The `path` parameter specifies the search directory or project root (e.g. `"."`, `"./src"`). The `scope` parameter filters files (`"code"`, `"config"`, `"all"`), a file extension (`"go"`, `"ts"`), or a subfolder path (`"internal/promo"`).

2. **SYMBOL & COMPONENT EXTRACTION (`smart_read_file`)**:
   - When locating or reading any function, component, class, or handler (e.g. `<LuckyWheelTab>`, `areSectorEqual`, `useWallet`), ALWAYS call `tokensafe:smart_read_file` with `path` (supports relative paths, e.g. `"src/service.ts"`) and `symbol`.
   - **1-Hop Dependency Modes (`dep_mode` & `include_deps`)**: By default (`dep_mode="signature"`), `smart_read_file` returns the full target implementation plus compact 1-line 1-hop dependency signatures and collapsed imports (-95%+ tokens). Pass `"dep_mode": "full"` when full 1-hop dependency bodies are required, or `"include_deps": false` for 0-hop surgical isolation.
   - **Cache Pointer Recovery (`force_full`)**: When repeating an unchanged read in the same MCP session, `smart_read_file` may return a compact pointer referencing the prior output. Reuse that earlier output; only pass `"force_full": true` if your context was compacted or you are a fresh subagent lacking prior turns.
   - **Multi-Symbol Bundles (`smart_bundle`)**: When you need 3+ related symbols across several files, call `tokensafe:smart_bundle(targets=[{path, symbol}])` ONCE instead of chained `smart_read_file` calls (max 8 targets). It merges per-file skeletons, deduplicates shared import/type lines into one block, and unifies 1-hop dependency signatures — one roundtrip instead of many.
   - **Schema Auto-Slicing**: OpenAPI/Swagger, Prisma, GraphQL and SQL files bypass AST skeletonization. Pass the spec path (`/users/{id}`), Prisma model, GraphQL type, or SQL table as `symbol` for a targeted slice with 1-hop references; an empty `symbol` returns a compact overview (paths/models/types/tables index) instead of a 20k-50k token dump.
   - **Result**: Preserves the exact target definition while folding surrounding inert code into clean 1-line signatures without docstrings (-85% to -98% tokens).

3. **ARCHITECTURE SURVEY BEFORE BROWSING (`get_architecture_graph`)**:
   - Before multi-file exploration or asking where things are located, ALWAYS call `tokensafe:get_architecture_graph(project_path=".")` (`project_path` defaults to active workspace).
   - **Result**: Returns top architectural God Nodes, dependency hubs, and centrality rankings in < 250 tokens without file crawling.

4. **API SURFACE INSPECTION (`get_api_surface`)**:
   - Call `tokensafe:get_api_surface(project_path=".")` (`project_path` defaults to active workspace) to get all exported classes, types, interfaces, and function signatures in a single compact markdown map.

5. **DIRECTORY NAVIGATION (`list_dir`)**:
   - NEVER run `ls -la` or `ls -l` in terminal.
   - Call `tokensafe:list_dir(path=".", depth=2)` for clean directory trees without permissions, timestamps, or lockfiles (-90% tokens). Supports relative subfolders (`path="src"`).

6. **SURGICAL FILE EDITS (`edit_file`)**:
   - On existing files with >= 40 lines, wholesale rewrites via `write_file` are blocked by **Output Guard**. Always use `edit_file` with precise `Target` and `Replacement` blocks.

7. **SECRET LEAK PREVENTION (ZERO HARDCODED FALLBACKS)**:
   - Never provide real private keys, API secrets, or credentials as fallback values in `os.environ.get()` or `process.env`. Real credentials must exist strictly in environment variables.

8. **CONTEXT BUDGET BEFORE HEAVY WORK (`context_budget` → `compact_conversation`)**:
   - Before large multi-step tasks, call `tokensafe:context_budget(model=...)` to check the window budget (tools/history/prompts breakdown, 50/80/95% thresholds).
   - When it reports `warning` or `critical`, call `tokensafe:compact_conversation(transcript_path=...)` to fold past turns into a State Ledger before continuing — do not let context exhaustion degrade code quality mid-task.

9. **REPEAT READ DEDUPLICATION & CACHE POINTERS**:
   - Never repeatedly re-read the same file or symbol within an active session.
   - When `smart_read_file` returns a pointer hit (`// [TokenSafe: Pointer Hit for ...]`), reuse earlier context; pass `"force_full": true` only if your context was compacted or you are a fresh subagent lacking prior turns.

10. **ZERO-FLUFF EGRESS & SURGICAL DIFFS**:
    - Eliminate conversational preambles, courtesy fillers, and trailing sign-offs.
    - Never reprint full unmodified files or lengthy boilerplate; cite line ranges and provide targeted diffs.

11. **COMPACT TEST EXECUTION**:
    - Run unit tests with concise flags or via `tokensafe tests [cmd]` so passing test suites emit a single-line summary (`PASS: ...`) rather than flooding `Messages` history with hundreds of verbose log lines. Full traceback is strictly preserved on failure.

---

## Core MCP Tools (`tokensafe`)

The full tool table with efficiency impact, JSON workflow examples, the Guard check matrix, and the CLI reference live in `references/` — read only the file you need:

- [`references/mcp-tools.md`](references/mcp-tools.md) — Core MCP Tools table + Agent Workflow JSON examples
- [`references/guard-checks.md`](references/guard-checks.md) — Security & Hygiene Guard check matrix (deny/ask per operation)
- [`references/cli-reference.md`](references/cli-reference.md) — `tokensafe` CLI command reference

Quick pointers:

- Search: `tokensafe:scoped_search(query, path=".", scope="code")` — safe keyword & symbol search, never raw grep.
- Inspect: `tokensafe:smart_read_file(path, symbol)` — definition + 1-hop deps.
- Bundle: `tokensafe:smart_bundle(targets=[{path, symbol}])` — 3-8 related symbols across files in one call, shared imports deduplicated.
- Navigate: `tokensafe:get_architecture_graph(project_path)` / `tokensafe:get_api_surface(project_path)`.
- Directory: `tokensafe:list_dir(path, depth=2)` — clean tree, never verbose `ls -la`.
- Terminal: `tokensafe:sanitize_command(command, cwd)` — bounded logs/diffs, test runner guards.
- Context: `tokensafe:compact_conversation(transcript_path)` / `tokensafe:context_budget`.

---

## Context Governor & History Compactor

For long-running autonomous sessions, TokenSafe actively manages context bloat:

1. **Multi-Turn History Compaction**:
   - At conversation turn >= 3, automatically compiles past turns into a lean **Consolidated State Ledger**.
   - Preserves active file paths, modified symbols, and pending tasks while discarding transient tool output noise.
   - **Manual trigger**: call `tokensafe:compact_conversation` with the session's `transcript_path` any time you need to shed context between subtasks — it returns the ledger JSON plus exact original/folded token counts.
2. **Subagent Deduplication Firewall**:
   - Caches file reads across subagents and sessions using SHA-256 content hashes. Interactive MCP clients receive self-healing pointer hits on unchanged repeat reads inside the same session; fresh subagents or post-compaction callers recover automatically with `force_full=true`.
3. **Loop Guard**:
   - Detects repeated identical tool calls and triggers `force_ask` to prevent runaway infinite agent loops.
4. **Output Token Guard**:
   - Intercepts wholesale `write_file` calls on existing files with >= 40 lines to prevent expensive output token burn.

---

## LLM Prompt Cache Optimization

TokenSafe actively maximizes provider KV-cache hit rates alongside token compression:

1. **Append-Only Epoch Architecture**: In proxy mode, past messages (`messages[0..N-2]`) are never retroactively mutated within an epoch, preserving prefix cache hits. When cumulative context reaches **80% of the model's window**, an atomic Epoch Rollover consolidates deep history into a State Ledger.
2. **Multi-Breakpoint Cache Control**: `PromptCacheNormalizer` sorts `tools` deterministically and places Anthropic `cache_control: {"type": "ephemeral"}` across tools, static system instructions, and the penultimate completed turn; OpenAI requests receive deterministic `prompt_cache_key`.
3. **Deterministic Prefix Normalization**: Ephemeral timestamps, hit counters, and session IDs are stripped from static prefixes, and `AgentFirewall` headers remain byte-deterministic across hits.
4. **Parametric Prompt Template Caching**: `DistillationCache` extracts file paths and symbols into positional slots (`<FILE_0>`, `<SYM_0>`) so structurally identical prompts hit L1/L2/L3 caches with 0 LLM roundtrips.

---

## Proof-of-Savings Turn Footer (always in English)

At the end of any response where tools were executed, files were inspected, commands were sanitized, or prompts were compacted, append a compact 1-line footer in English:
`⚡ **TokenSafe Turn Savings**: +<tokens> tokens saved on this turn (<breakdown>) | Cumulative Total: <total> tokens (≈$<usd> approx)`

The USD figure is **derived** (tokens × $1.5/M blended rate) — an approximation for planning, never a bill. Cumulative analytics distinguish `measured` (metered I/O delta) from `estimated` (counterfactual baseline) savings — see METRICS.md.
Pliki w paczce (4)
  • SKILL.md 10 KB
  • references/cli-reference.md 2 KB
  • references/guard-checks.md 2 KB
  • references/mcp-tools.md 6 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · tokensafe-dev/tokensafe100MIT
georgekhananaev/claude-skills-vault100MIT
nitinjain999/platform-skills95Apache-2.0
samibajwaisking/Token-Optimizer-Skill95MIT
LeoYeAI/openclaw-master-skills90MIT
LeoYeAI/openclaw-master-skills90MIT

Migawka bazy z 13.11.2026 · wersja paczki bf3cf6becd18 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100ast-grep
    Wyszukuje, analizuje i refaktoryzuje kod za pomocą ast-grep (sg): modyfikacje oparte na AST, wyszukiwanie strukturalne i linting.
  • 100ast-grep
    Szuka i przepisuje kod przez drzewo składni za pomocą CLI ast-grep, gdy dopasowanie zależy od struktury.
  • 95ast-grep-search
    Wyszukuje i zamienia wzorce kodu strukturalnie przez ast-grep, dopasowując kod według drzewa AST, na przykład funkcje o konkretnych sygnaturach lub antywzorce, których nie złapie regex.
  • 95codebase-search
    Przeszukuje duże bazy kodu i pomaga w nawigacji: wzorce kodu, śledzenie wywołań funkcji, struktura kodu i lokalizowanie błędów przez wyszukiwanie semantyczne, grep i analizę AST.
  • 100structural-search
    Wyszukuje kod po strukturze AST przy użyciu ast-grep, na przykład wywołania funkcji, importy lub definicje klas.
  • 100search-code
    Wyszukuje wzorce w kodzie Syncpack, używając ast-grep dla Rust oraz grep i rg w pozostałych przypadkach.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.