Back to Details

prompt-compression

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to use

使用场景

Use this skill when compressing documentation, framework references, API indexes, coding guidelines, or any structured knowledge into a compact format for inclusion in AGENTS.md, CLAUDE.md, or system prompts. The goal is maximum information density with minimum token usage.
当你需要将文档、框架参考、API索引、编码规范或任何结构化知识压缩为紧凑格式，以便纳入AGENTS.md、CLAUDE.md或系统提示词时，可使用此技能。目标是用最少的Token实现最高的信息密度。

Background

背景信息

Vercel's research (January 2026) showed that an 8KB compressed docs index in AGENTS.md achieved a 100% eval pass rate, compared to 53% baseline and 79% for skills with explicit trigger instructions. Passive context (always loaded) beats active retrieval (agent must decide to invoke) because it eliminates the decision point. Compression is the key enabler -- it makes passive context viable without blowing up the context window.
Vercel在2026年1月的研究显示，AGENTS.md中一个8KB的压缩文档索引实现了100%的评估通过率，而基线通过率为53%，带有明确触发指令的技能通过率为79%。被动上下文（始终加载）优于主动检索（Agent必须决定是否调用），因为它消除了决策环节。压缩是关键的促成因素——它让被动上下文无需占用过多上下文窗口即可生效。

Critical Rules

核心规则

1. Use Pipe-Delimited Index Format for File References

1. 针对文件引用使用竖线分隔的索引格式

Wrong (agents do this):
markdown
undefined
错误示例（Agent通常这么做）：
markdown
undefined

Documentation

Documentation

  • Getting Started: See docs/getting-started.md for installation instructions
  • Routing: See docs/routing.md for route definitions
  • API Routes: See docs/api-routes.md for API endpoint documentation

**Correct:**

```markdown
[Docs Index]|root: ./docs |getting-started:{installation.md,project-structure.md}
|routing:{defining-routes.md,dynamic-routes.md,middleware.md}
|api:{endpoints.md,auth.md,validation.md}
Why: The pipe-delimited format cuts tokens by 70-80% while remaining parseable by every major LLM. Agents can still locate and read specific files when needed.
  • Getting Started: See docs/getting-started.md for installation instructions
  • Routing: See docs/routing.md for route definitions
  • API Routes: See docs/api-routes.md for API endpoint documentation

**正确示例：**

```markdown
[Docs Index]|root: ./docs |getting-started:{installation.md,project-structure.md}
|routing:{defining-routes.md,dynamic-routes.md,middleware.md}
|api:{endpoints.md,auth.md,validation.md}
原因： 竖线分隔格式可减少70-80%的Token，同时仍能被所有主流LLM解析。Agent在需要时仍可定位并读取特定文件。

2. Compress Rules into Single-Line Directives

2. 将规则压缩为单行指令

Wrong (agents do this):
markdown
undefined
错误示例（Agent通常这么做）：
markdown
undefined

Coding Standards

Coding Standards

Import Organization

Import Organization

When writing imports, always organize them in the following order:
  1. Built-in Node.js modules (fs, path, etc.)
  2. External dependencies (react, express, etc.)
  3. Internal modules (relative imports)
  4. Type imports
Make sure to separate each group with a blank line.

**Correct:**

```markdown
[Standards] |imports: builtin > external > internal > types (blank line between groups)
Why: Agents don't need conversational explanation. A compressed directive carries the same behavioral instruction in 5% of the tokens.
When writing imports, always organize them in the following order:
  1. Built-in Node.js modules (fs, path, etc.)
  2. External dependencies (react, express, etc.)
  3. Internal modules (relative imports)
  4. Type imports
Make sure to separate each group with a blank line.

**正确示例：**

```markdown
[Standards] |imports: builtin > external > internal > types (blank line between groups)
原因： Agent不需要对话式的解释。一条压缩后的指令仅用5%的Token就能传达相同的行为要求。

3. Strip Explanatory Prose, Keep Only Actionable Content

3. 移除解释性文字，仅保留可执行内容

Wrong:
markdown
undefined
错误示例：
markdown
undefined

Authentication

Authentication

Our application uses JWT-based authentication. When a user logs in, the server generates a JWT token that contains the user's ID and role. This token is sent back to the client and stored in an httpOnly cookie. On subsequent requests, the middleware extracts the token from the cookie, verifies it, and attaches the user object to the request.
The token expires after 24 hours, at which point the user must log in again. Refresh tokens are not currently implemented but are planned for a future release.

**Correct:**

```markdown
[Auth]|JWT in httpOnly cookie|24h expiry|no refresh tokens |middleware: extract token > verify >
attach user to req |login flow: validate creds > generate JWT(id,role) > set cookie
Why: Agents need the behavioral contract (what to do), not the narrative (why it was built this way). Remove history, motivation, and future plans.
Our application uses JWT-based authentication. When a user logs in, the server generates a JWT token that contains the user's ID and role. This token is sent back to the client and stored in an httpOnly cookie. On subsequent requests, the middleware extracts the token from the cookie, verifies it, and attaches the user object to the request.
The token expires after 24 hours, at which point the user must log in again. Refresh tokens are not currently implemented but are planned for a future release.

**正确示例：**

```markdown
[Auth]|JWT in httpOnly cookie|24h expiry|no refresh tokens |middleware: extract token > verify >
attach user to req |login flow: validate creds > generate JWT(id,role) > set cookie
原因： Agent需要的是行为约定（要做什么），而不是叙事内容（为什么这么构建）。移除历史、动机和未来计划相关内容。

4. Use Abbreviated Keys and Symbols

4. 使用缩写键和符号

Wrong:
markdown
- Required: true
- Type: string
- Default value: "production"
- Minimum length: 3
- Maximum length: 50
Correct:
markdown
|env: required string="production" len:3-50
Why: Standard abbreviations (req, opt, str, int, bool, len, min, max, def) are universally understood by LLMs and compress structured metadata by 80%+.
错误示例：
markdown
- Required: true
- Type: string
- Default value: "production"
- Minimum length: 3
- Maximum length: 50
正确示例：
markdown
|env: required string="production" len:3-50
原因： 标准缩写（req、opt、str、int、bool、len、min、max、def）被LLM广泛理解，可将结构化元数据压缩80%以上。

5. Flatten Nested Hierarchies

5. 扁平化嵌套层级

Wrong:
markdown
undefined
错误示例：
markdown
undefined

Project Structure

Project Structure

Source Code

Source Code

Components

Components

UI Components
UI Components
  • Button.tsx
  • Input.tsx
  • Modal.tsx
  • Button.tsx
  • Input.tsx
  • Modal.tsx
Layout Components
Layout Components
  • Header.tsx
  • Footer.tsx
  • Sidebar.tsx

**Correct:**

```markdown
[Structure]|src/ |components/ui:{Button,Input,Modal}.tsx
|components/layout:{Header,Footer,Sidebar}.tsx
Why: Markdown heading hierarchy wastes tokens on whitespace and repetition. Brace expansion and path prefixes are denser and equally readable to agents.
  • Header.tsx
  • Footer.tsx
  • Sidebar.tsx

**正确示例：**

```markdown
[Structure]|src/ |components/ui:{Button,Input,Modal}.tsx
|components/layout:{Header,Footer,Sidebar}.tsx
原因： Markdown标题层级在空白和重复内容上浪费Token。大括号展开和路径前缀更紧凑，且对Agent来说同样易读。

6. Add Retrieval-Led Reasoning Directive

6. 添加检索导向推理指令

Always include this directive when the compressed context references retrievable files:
markdown
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any [DOMAIN] tasks.
Why: Without this, agents default to training data (which may be stale). This single line shifts behavior from "guess from memory" to "look it up," which was the key factor in Vercel's 100% pass rate.
当压缩后的上下文引用可检索文件时，务必包含以下指令：
markdown
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any [DOMAIN] tasks.
原因： 如果没有这条指令，Agent会默认使用训练数据（可能已过时）。这一行内容将Agent的行为从“凭记忆猜测”转变为“查阅资料”，这也是Vercel实现100%通过率的关键因素。

7. Preserve Structural Boundaries

7. 保留结构边界

Wrong:
markdown
routingdefiningdynamicmiddlewareapiendpointsauthvalidation
Correct:
markdown
|routing:{defining,dynamic,middleware} |api:{endpoints,auth,validation}
Why: Over-compression destroys parseability. Keep logical grouping with delimiters (pipes, braces, colons). The agent must be able to navigate to a specific file or section.
错误示例：
markdown
routingdefiningdynamicmiddlewareapiendpointsauthvalidation
正确示例：
markdown
|routing:{defining,dynamic,middleware} |api:{endpoints,auth,validation}
原因： 过度压缩会破坏可解析性。使用分隔符（竖线、大括号、冒号）保留逻辑分组。Agent必须能够导航到特定文件或章节。

8. Target 8-15KB for Complete Framework Indexes

8. 完整框架索引的目标大小为8-15KB

A full framework docs index (file tree pointing to retrievable docs) should compress to 8-15KB. This is the sweet spot where:
  • It fits comfortably in AGENTS.md alongside project-specific context
  • Token cost per request stays under 2-4K tokens
  • Agent accuracy reaches near-perfect on framework-specific tasks
If the compressed output exceeds 15KB, split into a primary index (most-used APIs) and a secondary index that the agent can read on demand.
一个完整的框架文档索引（指向可检索文档的文件树）应压缩至8-15KB。这是一个平衡点：
  • 可轻松与项目特定上下文一起放入AGENTS.md
  • 每个请求的Token成本保持在2-4K以内
  • Agent在框架特定任务上的准确率接近完美
如果压缩后的输出超过15KB，可拆分为主索引（最常用的API）和Agent可按需读取的二级索引。

Compression Process

压缩流程

  1. Identify the source - docs directory, API reference, coding guidelines, framework docs
  2. Extract actionable content - strip prose, motivation, history, examples that duplicate the rule
  3. Choose format - pipe-delimited index for file trees, single-line directives for rules, abbreviated keys for config/schema
  4. Compress - apply abbreviations, brace expansion, path prefixes, symbol shorthand
  5. Add retrieval directive - if output references readable files
  6. Validate - check that an agent can still locate any specific piece of information
  7. Measure - compare token count before/after, target 70-80% reduction
  1. 确定来源 - 文档目录、API参考、编码规范、框架文档
  2. 提取可执行内容 - 移除与规则重复的文字、动机、历史和示例
  3. 选择格式 - 文件树使用竖线分隔索引，规则使用单行指令，配置/Schema使用缩写键
  4. 压缩 - 应用缩写、大括号展开、路径前缀、符号简写
  5. 添加检索指令 - 如果输出引用了可读取的文件
  6. 验证 - 检查Agent是否仍能定位到任何特定信息
  7. 测量 - 比较压缩前后的Token数量，目标是减少70-80%

Output Formats

输出格式

File Index (for docs directories)

文件索引（用于文档目录）

markdown
[Topic Index]|root: ./path |IMPORTANT: Prefer retrieval-led reasoning over pre-training-led
reasoning for [TOPIC] |section-a/subsection:{file1.md,file2.md,file3.md}
|section-b:{file1.md,file2.md}
markdown
[Topic Index]|root: ./path |IMPORTANT: Prefer retrieval-led reasoning over pre-training-led
reasoning for [TOPIC] |section-a/subsection:{file1.md,file2.md,file3.md}
|section-b:{file1.md,file2.md}

Rules/Standards (for coding guidelines)

规则/标准（用于编码规范）

markdown
[Standards] |naming: camelCase vars, PascalCase components, UPPER_SNAKE constants |imports:
builtin > external > internal > types |errors: always use Result<T,E>, never throw in library code
|tests: colocate with source, name: \*.test.ts, min coverage 80%
markdown
[Standards] |naming: camelCase vars, PascalCase components, UPPER_SNAKE constants |imports:
builtin > external > internal > types |errors: always use Result<T,E>, never throw in library code
|tests: colocate with source, name: \*.test.ts, min coverage 80%

API Reference (for endpoint documentation)

API参考（用于端点文档）

markdown
[API]|base: /api/v2 |GET /users?page,limit -> User[]|auth:bearer |POST /users {name,email,role?} ->
User|auth:admin |DELETE /users/:id -> void|auth:admin
markdown
[API]|base: /api/v2 |GET /users?page,limit -> User[]|auth:bearer |POST /users {name,email,role?} ->
User|auth:admin |DELETE /users/:id -> void|auth:admin

Config/Schema (for structured metadata)

配置/Schema（用于结构化元数据）

markdown
[Config] |db: host=localhost port=5432 pool:5-20 timeout:30s |cache: redis ttl:5m max:1000
prefix:"app:" |auth: jwt secret=$JWT_SECRET exp:24h algo:HS256
markdown
[Config] |db: host=localhost port=5432 pool:5-20 timeout:30s |cache: redis ttl:5m max:1000
prefix:"app:" |auth: jwt secret=$JWT_SECRET exp:24h algo:HS256

Anti-Patterns

反模式

  • Compressing content that agents already know well (basic language syntax, standard library)
  • Removing code examples that demonstrate non-obvious API usage
  • Compressing error messages or edge case documentation (agents need these verbatim)
  • Creating compression so aggressive that a human can't review or maintain it
  • Putting full documentation content in AGENTS.md instead of an index pointing to files
  • Forgetting the retrieval-led reasoning directive
  • 压缩Agent已熟知的内容（基础语言语法、标准库）
  • 移除展示非显而易见API用法的代码示例
  • 压缩错误消息或边缘情况文档（Agent需要这些原始内容）
  • 压缩过度以至于人类无法审查或维护
  • 将完整文档内容放入AGENTS.md而非指向文件的索引
  • 忘记添加检索导向推理指令