Reinforce Skills

Reinforce Skills

Inject a compressed skill-mapping directive into a project's CLAUDE.md file so skill names and invocation triggers persist across the entire session without being lost to context drift.

Problem

LLMs lose track of skill names and invocation details as conversation context grows. Skills load at session start but fade from working memory mid-session, causing the agent to guess names, skip invocations, or fail to call skills the user explicitly requested.

Solution

Vercel's research found that passive context embedded in project files outperforms active skill retrieval — 100% vs 79% pass rate in agent evals. Embed a compressed skill map directly in CLAUDE.md using the same directive pattern.

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

For detailed research findings, consult references/vercel-research.md.

File Placement

For Claude Code projects, inject into CLAUDE.md. For multi-tool projects, consider both files.

Compressed Directive Format

Single-line, pipe-delimited block wrapped in HTML comments. Opens with a forceful imperative directive, followed by task-to-skill mappings:

<!-- SKILL-MAP-START -->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)<!-- SKILL-MAP-END -->

Format Rules

• Single line — no line breaks within the block
• Pipe | separates each entry
• Arrow → maps trigger to skill invocation
• HTML comment markers SKILL-MAP-START / SKILL-MAP-END enable programmatic updates
• Opening directive must be forceful and imperative
• Use exact skill names as listed in the Skill tool's available skills (shown in system-reminder messages)
• Wildcard syntax Skill(namespace:*) for skill families (e.g., bsv-skills:*)

Workflow

Step 1: Inventory available skills

Two authoritative sources for installed skills:

1. System-reminder skill list — The Skill tool's available skills appear in system-reminder messages at conversation start. This is the definitive list of all skills including plugin skills.
2. Global skills directory — ls ~/.claude/skills/ shows user-installed skills (subset of the full list).

Cross-reference both sources.

Step 2: Identify project-relevant skills

1. Read CLAUDE.md — Identify tech stack, frameworks, tools
2. Check package.json / go.mod / Cargo.toml — Map dependencies to skills (e.g., better-auth → better-auth-best-practices, ai → ai-sdk, remotion → remotion-best-practices)
3. Scan recent git history — Identify recurring work patterns
4. Check conversation history — Look for past Skill() invocations if available

For a comprehensive trigger-to-skill mapping table, consult references/common-mappings.md.

Step 3: Next.js codemod (conditional)

If the project uses Next.js, run the official codemod for framework docs:

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

This creates a separate compressed Next.js docs index in AGENTS.md. The skill map is independent and goes in CLAUDE.md.

If the project does not use Next.js, skip this step entirely.

Step 4: Build the skill map

Construct the compressed directive. Only include skills relevant to the project's stack. Refer to references/common-mappings.md for the full trigger-to-skill reference table.

Step 5: Inject into CLAUDE.md

Place the skill map near the top of CLAUDE.md. If the file has YAML frontmatter (--- delimiters), place the skill map after the closing --- but before the first heading or content. If no frontmatter, place after the title heading.

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

<!-- SKILL-MAP-START -->STOP. You WILL forget skill names mid-session. Check this map before ANY task.|trigger→Skill(name)|...<!-- SKILL-MAP-END -->

## Project Overview
...

Or without frontmatter:

# CLAUDE.md

<!-- SKILL-MAP-START -->STOP. You WILL forget skill names mid-session. Check this map before ANY task.|trigger→Skill(name)|...<!-- SKILL-MAP-END -->

## Project Overview
...

Step 6: Verify

1. Block is a single line (no breaks between START and END markers)
2. All skill names are exact (match the Skill tool's available skills list)
3. Directive opens with a forceful imperative
4. CLAUDE.md still reads cleanly for humans
5. If frontmatter exists, the block is outside the --- delimiters

Updating an Existing Map

1. Read the existing <!-- SKILL-MAP-START -->...<!-- SKILL-MAP-END --> block
2. Parse current mappings
3. Add, remove, or update entries
4. Replace the entire block with the updated single-line version

Key Principles

1. Passive over active — Embedding beats on-demand retrieval for consistent invocation
2. Forceful directives — Polite suggestions get ignored mid-session. Imperative commands persist.
3. Exact names — Never abbreviate or guess. Use the exact registered skill name.
4. Project-specific — Only include skills relevant to the project's actual stack
5. Single line — The compressed format must stay on one line to match the proven pattern

Additional Resources

Reference Files

• references/vercel-research.md — Detailed summary of Vercel's AGENTS.md research: methodology, eval results, three factors for passive context superiority, and compression technique details
• references/common-mappings.md — Comprehensive trigger-to-skill mapping table organized by category (workflow, quality, frontend, video, marketing, auth, infrastructure, desktop)