reinforce-skills

强化技能与 Agent

将压缩后的技能映射和 Agent 映射指令注入项目的 CLAUDE.md 文件，使技能名称、Agent ID 和调用触发条件在整个会话期间持续生效，不会因上下文漂移而丢失。

问题

随着对话上下文不断增长，大模型会忘记技能名称、Agent ID 和调用细节。技能和 Agent 会在会话开始时加载，但在会话中途逐渐淡出工作记忆，导致 Agent 猜测名称、跳过调用，或无法委派给正确的专家。

解决方案

Vercel 的研究发现，嵌入项目文件的被动上下文优于主动检索技能——Agent 评测中的通过率为 100%，而主动检索为 79%。使用相同的指令模式，将压缩后的技能映射直接嵌入 CLAUDE.md。

参考：https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals

详细研究结果请参阅 references/vercel-research.md。

文件放置位置

工具	文件
Claude Code	CLAUDE.md
Cursor	AGENTS.md
其他 Agent	AGENTS.md

对于 Claude Code 项目，请注入到 CLAUDE.md。对于使用多种工具的项目，可考虑同时使用这两个文件。

压缩指令格式

使用两个独立的单行代码块——一个用于技能，一个用于 Agent。两者都使用相同的竖线分隔格式，并用 HTML 注释包裹。

技能映射

STOP. You WILL forget skill names mid-session. Check this map before ANY task.|task-trigger→Skill(exact-skill-name)|another-trigger→Skill(another-skill)

Agent 映射

STOP. You WILL forget agent IDs mid-session. Check this map before delegating any complex task.|task-trigger→Agent(plugin:agent-id)|another-trigger→Agent(plugin:agent-id)

Agent ID 使用 plugin:agent-name 格式，与 Agent 工具的 subagent_type 参数一致（例如 review:code-auditor、web-dev:designer、gemskills:content）。

格式规则（两个代码块均适用）

• 单行——代码块内不得换行
• 竖线 | 用于分隔各个条目
• 箭头 → 用于将触发条件映射到调用方式
• HTML 注释标记支持以编程方式更新
• 开头指令必须强势且具有命令性
• 使用 Skill 工具的 system-reminder 或 Agent 工具的可用 Agent 列表中列出的准确名称／ID
• 技能族使用通配符语法 Skill(namespace:*)（例如 bsv-skills:*）

工作流

步骤 1：盘点可用技能和 Agent（通过子 Agent）

将盘点工作委派给子 Agent，以保持主上下文窗口整洁：

Agent(prompt: "Gather skill and agent inventories from all available sources.

SKILLS — check two sources:
1. The system-reminder skill list (from the Skill tool's available skills in system-reminder messages)
2. ls ~/.claude/skills/ for user-installed skills

AGENTS — check two sources:
1. The system-reminder agent list (Agent tool's available subagent types)
2. ls ~/.claude/plugins/cache/*/agents/ for plugin agents

Cross-reference both sources for each category.

Return two lists:
- SKILLS: name, plugin (if any), one-line description
- AGENTS: plugin:agent-id, one-line description",
subagent_type: "general-purpose")

步骤 2：识别与项目相关的技能和 Agent（通过子 Agent）

将项目分析委派给子 Agent：

Agent(prompt: "Analyze this project and identify which skills and agents are relevant.

1. Read CLAUDE.md — identify tech stack, frameworks, tools
2. Check package.json / go.mod / Cargo.toml — map dependencies to skills
3. Scan recent git history (git log --oneline -20) — identify recurring work patterns
4. Check for past Skill() and Agent() invocations if conversation history is available

Consult references/common-mappings.md for the trigger-to-skill and trigger-to-agent mapping table.

Return two structured lists:
- RELEVANT SKILLS: trigger phrase → Skill(exact-name)
- RELEVANT AGENTS: trigger phrase → Agent(plugin:agent-id)",
subagent_type: "general-purpose")

步骤 3：Next.js codemod（有条件执行）

如果项目使用 Next.js，请运行官方 codemod，以获取框架文档：

npx @next/codemod@canary agents-md --version <version-from-package.json> --output AGENTS.md

这会在 AGENTS.md 中创建单独的压缩版 Next.js 文档索引。技能映射彼此独立，应放在 CLAUDE.md 中。

如果项目不使用 Next.js，请完全跳过此步骤。

步骤 4：构建技能映射

编写压缩后的技能指令。仅包含与项目技术栈相关的技能。完整的触发条件到技能映射参考表请参阅 references/common-mappings.md。

步骤 5：构建 Agent 映射

编写压缩后的 Agent 指令。仅包含与此项目中常见任务类型相关的 Agent。请严格使用 plugin:agent-name 格式。触发条件到 Agent 的映射表请参阅 references/common-mappings.md。

步骤 6：注入到 CLAUDE.md

将两个映射依次放在 CLAUDE.md 顶部附近。如果文件包含 YAML frontmatter（以 --- 分隔），请将两个代码块放在闭合的 --- 之后、首个标题或正文之前。

---
description: Project description
globs: "*.ts"
---

STOP. You WILL forget skill names mid-session. Check this map before ANY task.|trigger→Skill(name)|...
STOP. You WILL forget agent IDs mid-session. Check this map before delegating any complex task.|trigger→Agent(plugin:agent-id)|...

## Project Overview
...

或者，如果没有 frontmatter：

# CLAUDE.md

STOP. You WILL forget skill names mid-session. Check this map before ANY task.|trigger→Skill(name)|...
STOP. You WILL forget agent IDs mid-session. Check this map before delegating any complex task.|trigger→Agent(plugin:agent-id)|...

## Project Overview
...

如果用户只需要一个代码块（例如只需要 Agent 映射，不需要技能映射），则只注入对应的代码块。

步骤 7：验证

1. 每个代码块都是单行（START 和 END 标记之间没有换行）
2. 所有技能名称均准确无误（与 Skill 工具的可用技能列表一致）
3. 所有 Agent ID 均采用准确的 plugin:agent-name 格式（与 Agent 工具可用的子 Agent 类型一致）
4. 每条指令的开头都使用强势的命令式措辞
5. CLAUDE.md 对人类读者仍然清晰易读
6. 如果存在 frontmatter，两个代码块都位于 --- 分隔符之外

更新现有映射

1. 读取现有的 ... 和／或 ... 块
2. 解析当前映射
3. 添加、移除或更新条目
4. 用更新后的单行版本替换整个块

核心原则

1. 被动优于主动 — 为保持调用一致，嵌入内容优于按需检索
2. 强制性指令 — 礼貌的建议在会话中途容易被忽略。祈使命令则会持续生效。
3. 使用准确名称 — 切勿缩写或猜测。使用准确注册的技能名称或 Agent ID。
4. 针对项目 — 仅包含与项目实际工作相关的技能和 Agent
5. 单行 — 压缩格式必须保持在一行，以符合已验证的模式
6. 分开存放 — 将 SKILL-MAP 和 AGENT-MAP 放在不同的块中，以便独立更新

其他资源

参考文件

• references/vercel-research.md — Vercel 的 AGENTS.md 研究详细摘要：方法、评估结果、被动上下文优越性的三个因素，以及压缩技术详情
• references/common-mappings.md — 按类别整理的全面触发词到技能映射表（工作流、质量、前端、视频、营销、身份验证、基础设施、桌面应用）