reinforce-skills

スキルとエージェントを定着させる

圧縮したスキルマッピングとエージェントマッピングの指示をプロジェクトのCLAUDE.mdファイルに挿入します。これにより、スキル名、エージェントID、呼び出しトリガーがセッション全体で保持され、コンテキストのずれによって失われるのを防ぎます。

問題

LLMは、会話のコンテキストが増えるにつれてスキル名、エージェントID、呼び出しの詳細を見失います。スキルやエージェントはセッション開始時に読み込まれますが、セッションの途中で作業メモリから薄れていき、エージェントが名前を推測したり、呼び出しを省略したり、適切な専門家への委任に失敗したりします。

解決策

Vercelの調査では、プロジェクトファイルに埋め込まれた受動的なコンテキストは、能動的なスキル取得を上回ることがわかりました。エージェント評価での合格率は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
その他のエージェント	AGENTS.md

Claude Codeのプロジェクトでは、CLAUDE.mdに挿入します。複数のツールを使うプロジェクトでは、両方のファイルを使用することを検討してください。

圧縮指示の形式

スキル用とエージェント用に、それぞれ独立した1行のブロックを使用します。どちらも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)

エージェントマップ

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)

エージェントIDには、Agentツールのsubagent_typeパラメーターに一致するplugin:agent-name形式を使用します（例：review:code-auditor、web-dev:designer、gemskills:content）。

形式のルール（両方のブロック）

• 1行にする — ブロック内で改行しない
• パイプ|で各エントリーを区切る
• 矢印→でトリガーと呼び出しを対応づける
• HTMLコメントマーカーでプログラムによる更新を可能にする
• 開始時の指示は、強い命令形にする
• Skillツールのsystem-reminderまたはAgentツールで利用可能なエージェント一覧に記載された正確な名前／IDを使用する
• スキルファミリーにはワイルドカード構文Skill(namespace:*)を使用する（例：bsv-skills:*）

ワークフロー

ステップ1：利用可能なスキルとエージェントを一覧にする（サブエージェント経由）

メインコンテキストウィンドウをすっきり保つため、一覧の作成をサブエージェントに委任します。

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(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

これにより、圧縮したNext.jsドキュメントのインデックスがAGENTS.mdに別途作成されます。スキルマップは独立しており、CLAUDE.mdに配置します。

プロジェクトでNext.jsを使用していない場合、このステップは完全に省略します。

ステップ4：スキルマップを作成する

圧縮したスキル指示を作成します。プロジェクトのスタックに関連するスキルのみを含めてください。トリガーとスキルの対応表全体については、**references/common-mappings.md**を参照してください。

ステップ5：エージェントマップを作成する

圧縮したエージェント指示を作成します。このプロジェクトで一般的に発生するタスクの種類に関連するエージェントのみを含めてください。plugin:agent-name形式をそのまま使用します。トリガーとエージェントの対応表については、**references/common-mappings.md**を参照してください。

ステップ6：CLAUDE.mdに挿入する

両方のマップをCLAUDE.mdの上部付近に、続けて配置します。ファイルにYAMLフロントマター（---区切り）がある場合は、閉じる---の後、最初の見出しまたは本文の前に両方のブロックを配置します。

---
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
...

フロントマターがない場合：

# 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
...

ユーザーが一方のブロックのみ（例：スキルではなくエージェントのみ）を希望する場合は、該当するブロックだけを挿入します。

ステップ7：確認する

1. 各ブロックが1行になっている（STARTマーカーとENDマーカーの間に改行がない）
2. すべてのスキル名が正確である（Skillツールで利用可能なスキル一覧に一致する）
3. すべてのエージェントIDが正確なplugin:agent-name形式である（Agentツールで利用可能なサブエージェントタイプに一致する）
4. 各指示の冒頭が、強い命令形になっている
5. CLAUDE.mdが人間にも読みやすい状態である
6. フロントマターがある場合、両方のブロックが---区切りの外にある

既存のマップを更新する

1. 既存の ... および／または ... ブロックを読みます
2. 現在のマッピングを解析します
3. エントリーを追加、削除、または更新します
4. ブロック全体を、更新した単一行のバージョンに置き換えます

重要な原則

1. 受動的な方法を優先する — 一貫した呼び出しには、オンデマンドでの取得より埋め込みが効果的です
2. 強制力のある指示 — 丁寧な提案はセッション中に無視されます。命令形のコマンドは守られ続けます
3. 正確な名前 — 略称や推測は使わないでください。登録済みのスキル名またはエージェント ID を正確に使用してください
4. プロジェクト固有にする — プロジェクトの実際の作業に関連するスキルとエージェントだけを含めてください
5. 単一行にする — 実証済みのパターンに合わせるため、圧縮形式は必ず 1 行にしてください
6. ブロックを分ける — 個別に更新できるよう、SKILL-MAP と AGENT-MAP は別々のブロックにしてください

追加リソース

参考ファイル

• references/vercel-research.md — Vercel の AGENTS.md に関する調査の詳細な要約。手法、評価結果、受動的コンテキストが優れている 3 つの要因、圧縮手法の詳細を含みます
• references/common-mappings.md — ワークフロー、品質、フロントエンド、動画、マーケティング、認証、インフラストラクチャ、デスクトップの各カテゴリ別に整理された、トリガーとスキルの包括的なマッピング表