---
name: token-saver-skill
slug: token-saver-skill
displayName: "令牌技能"
version: "1.0.0"
summary: "省50-80%AI token用量,不牺牲响应质量"
description: "省50-80%AI token用量,不牺牲响应质量。Code blocks (always kept intact)。Error messages and stack traces。User-marked important messages。支持多种输入格式,输出结构化结果,适用于独立开发者与一人公司效率提升。"
license: "MIT"
tools:
  - Read
  - Write
  - Edit
  - Bash
---

# Token Saver Skill

A token cost optimization skill that helps you save 50-80% on AI token usage without sacrificing response quality.

## When to Use

Use TokenSaver when:

* You have long conversations that consume many tokens
* You want to reduce AI API costs
* You're working with technical discussions that accumulate context
* You notice token usage growing rapidly in long sessions

## Core Capabilities

### 1. Smart Context Compression

Automatically compresses conversation history 基于 message importance.

**How it works:**

* Recent messages (last 3-5) kept fully intact
* Older messages summarized 基于 importance score
* Code blocks and critical decisions never compressed

**Savings:** 50-70% reduction in context tokens

### 2. Semantic Cache

Caches responses to similar queries to avoid reprocessing.

**How it works:**

* L1: Exact query match → 100% savings
* L2: Semantic similarity > 85% → 80% savings
* L3: Pattern match → 50% savings

### 3. Adaptive Optimization

Automatically adjusts compression 基于 token pressure.

**Stages:**

* < 3K tokens: No compression
* 3-6K tokens: Light compression
* 6-10K tokens: Medium compression
* > 10K tokens: Heavy compression + suggest new chat

## Natural Language Commands

When user asks about TokenSaver in natural language, interpret and execute:

### Settings & Configuration

**User says:** "Configure TokenSaver" / "TokenSaver settings" / "Setup TokenSaver"
**Action:** Show current configuration and available options

```text
Current TokenSaver Settings:
- Mode: Adaptive (auto-adjust 基于 token pressure)
- Compression: Balanced
- Cache: Enabled
- Quality Threshold: 85%

You can change mode:
- /tokensave - Aggressive mode (max savings)
- /tokenbalance - Balanced mode (default)
- /tokenquality - Quality priority (min compression)
```

**User says:** "Use aggressive mode" / "Maximize savings" / "Set to save mode"
**Action:** Execute /tokensave command
**Response:** "✅ TokenSaver switched to aggressive save mode. This provides maximum token savings (up to 80%) with slight quality trade-off."

**User says:** "Use balanced mode" / "Default settings" / "Set to balanced"
**Action:** Execute /tokenbalance command
**Response:** "✅ TokenSaver switched to balanced mode. Good savings (50-70%) with quality preserved."

**User says:** "Prioritize quality" / "Keep full context" / "Set to quality mode"
**Action:** Execute /tokenquality command
**Response:** "✅ TokenSaver switched to quality priority mode. Minimal compression, maximum context retention for precision-critical tasks."

**User says:** "Disable TokenSaver" / "Turn off token saving" / "Stop TokenSaver"
**Action:** Execute /tokenoff command
**Response:** "⏸️ TokenSaver temporarily disabled. Re-enable anytime with /tokens or by asking me to turn it back on."

### Usage Reports & Analytics

**User says:** "Show me token usage report" / "TokenSaver statistics" / "Token report"
**Action:** Execute /tokenreport command
**Response format:**

```text
📈 TokenSaver Usage Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This Session:
• Total Original Tokens: 12,450
• Total Optimized Tokens: 4,358
• Tokens Saved: 8,092 (65%)
• Estimated Cost Saved: $0.016
• Cache Hits: 5
• Compressions Applied: 12

Top Savings Sources:
1. Context Compression: -6,200 tokens
2. Semantic Cache: -1,500 tokens
3. Response Optimization: -392 tokens
```

**User says:** "TokenSaver status" / "How much am I saving?" / "Token status"
**Action:** Execute /tokens command
**Response format:**

```text
💰 TokenSaver Status
━━━━━━━━━━━━━━━━━━━━
Current Session:
• Savings: 65%
• Original Tokens: 12,450
• Optimized Tokens: 4,358
• Cache Hits: 5

Current Mode: Balanced (Adaptive)
• Stage 3 compression active
• Quality Score: 95%
```

**User says:** "Clear token cache" / "Reset cache" / "Clear TokenSaver cache"
**Action:** Execute /tokencache clear command
**Response:** "✅ TokenSaver cache cleared. Fresh responses will be generated for subsequent queries."

### Explanation & Help

**User says:** "What is TokenSaver" / "How does token saving work?" / "Explain TokenSaver"
**Response:**

```text
TokenSaver is an intelligent token cost optimization skill that helps you save 50-80% on AI token usage.

Key Features:
1. Smart Context Compression - Summarizes old conversation while keeping recent messages intact
2. Semantic Cache - Reuses responses for similar questions
3. Adaptive Optimization - Automatically adjusts 基于 conversation length
4. Quality Guard - Never compresses code, errors, or important messages

Benefits:
• Save 50-80% on token costs
• Faster responses with caching
• No quality loss for critical content
• Automatic - works in background
```

**User says:** "TokenSaver not working" / "Why no savings?" / "TokenSaver not saving"
**Response:**

```text
TokenSaver may not show savings if:
1. Conversation is too short (< 3000 tokens) - compression starts at 3K
2. Currently in quality priority mode - switch with /tokensave
3. First-time queries - cache builds up over time
4. Code-heavy conversation - code blocks are never compressed

Try starting a longer technical discussion to see significant savings!
```

### Best Practices

**User says:** "TokenSaver best practices" / "How to use TokenSaver effectively?" / "TokenSaver tips"
**Response:**

```text
TokenSaver Best Practices:

1. For Debugging/Code Review:
   Use /tokenquality mode to keep full context

2. For Research/Exploration:
   Use /tokensave mode for maximum savings (up to 80%)

3. For General Chat:
   Balanced mode (default) works best

4. When to Start New Chat:
   If switching major topics, start fresh for better compression

5. Monitor with:
   /tokens - Quick status check
   /tokenreport - Detailed analytics
```

## Slash Commands

For direct command access:

### /tokens

Show current status and statistics

```text
Session Savings: 65%
Original Tokens: 12,450
Optimized Tokens: 4,358
Cache Hits: 3
```

### /tokensave

Enable aggressive save mode

* Maximum compression
* Best for very long technical discussions
* Slight quality trade-off possible

### /tokenbalance

Balanced mode (default)

* Good savings with quality preserved
* Recommended for most use cases

### /tokenquality

Quality priority mode

* Minimal compression
* Maximum context retention
* Use when precision is critical

### /tokenreport

Generate detailed usage report

```text
Total Tokens Saved: 8,092
Estimated Cost Saved: $0.016
Compressions Applied: 12
Cache Hits: 5
```

### /tokencache clear

Clear all cached responses

### /tokenoff

Temporarily disable optimization

## 示例

**Example 1: Long coding session**

```text
User: [20 rounds of Python discussion]
TokenSaver: Optimized 15K → 4.5K tokens (70% saved)
```

**Example 2: Repeated questions**

```text
User: "How do I write to a file in Python?"
User: "Python file write method?"
TokenSaver: L2 cache hit - instant response, 0 tokens used
```

**Example 3: Topic switching**

```text
User: Switching from discussing Python to JavaScript...
TokenSaver: "Detected topic change. Start new chat to keep context clean?"
[Yes] [No]
```

## 核心能力

TokenSaver never compresses:

* Code blocks (always kept intact)
* Error messages and stack traces
* User-marked important messages
* Messages with high cross-references

**Quality Guard:**

* Auto-rollback if quality drops > 15%
* One-click restore to uncompressed version
* Snapshots for every compression

## Configuration

Default configuration:

```json
{
  "mode": "adaptive",
  "compression": "balanced",
  "cache": true,
  "qualityThreshold": 0.85
}
```

## Expected Results

| Conversation Type | Tokens Saved | Quality Impact |
| --- | --- | --- |
| Technical discussion (50 rounds) | 70% | Minimal |
| Code review | 80% | None |
| Casual chat | 75% | None |
| Quick Q&A | 30-50% | None |

## Limitations

* Requires conversation to exceed 3K tokens before compression starts
* First-time queries cannot be cached
* Very short conversations (< 10 messages) see minimal benefit
* Code-heavy conversations benefit most from smart referencing

## Related Skills

* shieldclaw: For security scanning
* browser_visible: For web browsing
* file_reader: For reading local files

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent( Code / Cursor / Codex / Gemini CLI等)
- **操作系统**: Windows / macOS / Linux

### 依赖说明
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent内置LLM提供 |

### API Key 配置
- 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API)

### 可用性分类
- **分类**: MD+EXEC(纯Markdown指令,部分功能需要exec命令行执行能力)
- **说明**: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务

## 适用场景

| 场景 | 输入 | 输出 |
|------|------|------|
| 基础使用 | 用户请求 | 处理结果 |

**不适用于**：需要人工判断的复杂决策场景

## 使用流程

1. 确认运行环境满足依赖说明中的要求
2. 根据适用场景选择合适的使用方式
3. 执行操作并检查输出结果
4. 如遇错误，参考错误处理章节

## 错误处理

| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 检查网络连接后重试，参考国内替代方案 |

## 常见问题

### Q1: 如何开始使用Token Saver Skill？
A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。

### Q2: 遇到错误怎么办？
A: 请参考错误处理章节，按照表格中的处理方式操作。

### Q3: Token Saver Skill有什么限制？
A: 请参考已知限制章节了解具体限制。