optimize-agents-md

用途

optimize-agents-md 是一个用于优化 AGENTS.md 和规则文件的技能。它应用 Boris Cherny 的压缩原则，目标是实现 token 效率。其优化目标约为 2.5k tokens，文中指出大多数此类文件往往无必要地超过 10k tokens。

适用时机

用户希望改进其 AGENTS.md 或 CLAUDE.md
Agent 指令显得冗长或冗余
规则存在但缺少验证模式
为新项目配置 agent 设置

主要能力：修复的反模式

该技能针对以下反模式及其修复方式：

上下文堆砌（Context stuffing）：重复 agent 已经知道的信息。修复方式：删除显而易见的指令。
静态记忆（Static memory）：没有 Learnings 部分。修复方式：添加带日期的 ## Learnings。
格式漂移（Format drift）：结构不一致。修复方式：使用一致的标题。
缺少验证（Missing verification）：无法检查工作。修复方式：为规则添加 Verify: 模式。
冗长规则（Verbose rules）：用段落而非模式。修复方式：压缩为 pattern + verify + fix。

使用方式（工作流）

阶段 1：分析当前状态

# Count tokens (rough estimate: words × 1.3)
wc -w AGENTS.md

# Find redundancy with project files
grep -l "bun test" AGENTS.md package.json

查找以下内容：

与 package.json 脚本重复的指令
对常见工具（git、npm、bun）的解释
可以用表格表达的冗长描述
没有验证模式的规则

阶段 2：压缩 AGENTS.md

目标结构：

# AGENTS.md

## Overview
[1-2 sentences: what this project is]

## Capabilities  
[Bullet list of key features/commands]

## Structure
[Brief file tree of key paths]

## Commands
[Essential commands only - not everything in package.json]

## Verification
[How to check work is correct]

## Workflow
[Key constraints: plan first, verify incrementally]

## Rules
[Links to rule files or inline compressed rules]

## Learnings
[Dated entries from actual issues encountered]

压缩技术：

用表格代替段落
用项目符号代替句子
删除 package.json 中已有的任何内容
删除工具说明（agent 了解 git、npm、bun）
合并相关章节

阶段 3：优化规则

将冗长规则转换为验证模式。

优化前（冗长）：

## Type Aliases Over Interfaces

In this codebase, we prefer using TypeScript type aliases 
instead of interfaces. This provides better consistency 
and flexibility when working with unions and intersections.

Example:
// Good
type User = { name: string }

// Bad  
interface User { name: string }

优化后（压缩并带验证）：

**Type over interface** - `type User = {` instead of `interface User {`
*Verify:* `grep 'interface [A-Z]' src/`
*Fix:* Replace `interface X {` with `type X = {`

模式格式：

**Rule name** - Brief description with example
*Verify:* Command or tool to check compliance
*Fix:* How to resolve violations

阶段 4：添加活文档特性

Learnings 部分：

## Learnings
- 2024-01-15: Skills use CLI tools, never duplicate logic
- 2024-01-20: Rules need verification patterns for self-checking

更新触发条件：在以下情况下添加学习记录：

某个错误需要纠正
发现了某种模式
澄清了某项约束

验证

优化之后：

Token 数量：wc -w AGENTS.md × 1.3 ≈ tokens（目标：<2.5k）
无冗余：grep 查找 package.json 中重复的信息
规则具备模式：每条规则都有 Verify: 行
存在学习记录：存在 ## Learnings 部分

示例转换

Commands 章节

优化前（340 词）：

## Development Commands

To install dependencies, run the following command...
[lengthy explanation of bun install]

To run tests, you can use...
[explanation of test runner]

优化后（40 词）：

## Commands
```bash
bun install    # Setup
bun run check  # Lint/format
bun test       # Unit tests


### 能力描述

优化前：

```markdown
This package provides TypeScript Language Server Protocol 
integration that allows you to get type information, find 
symbols across your workspace, locate references to symbols,
and perform batch analysis of files.

优化后：

**LSP** (`lsp-*`): Type-aware hover, symbol search, references, batch analysis

限制

资料中未提供该技能的具体运行平台、收费方式或安装命令等细节，这些内容暂未提供。

技能介绍

用途