refresh-context-map
/refresh-context-map
USE WHEN AIDEV anchors / per-dir AGENTS.md / ADRs have changed in this repo and the smart-context-surfacing PreToolUse hook needs an updated manifest. Rebuilds `.claude-leverage-context-map.json` at the repo root by running `scripts/build-context-map.py`. Read-only on source — only writes the manifest.
- Author
- filip-podstavec ↗
- Repository
- claude-leverage ↗
- Licence
- MIT
- Last repository change
- 03.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 03.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
USE WHEN AIDEV anchors / per-dir AGENTS.md / ADRs have changed in this repo and the smart-context-surfacing PreToolUse hook needs an updated manifest. Rebuilds `.claude-leverage-context-map.json` at the repo root by running `scripts/build-context-map.py`. Read-only on source — only writes the manifest.
Original author description
USE WHEN AIDEV anchors / per-dir AGENTS.md / ADRs have changed in this repo and the smart-context-surfacing PreToolUse hook needs an updated manifest. Rebuilds `.claude-leverage-context-map.json` at the repo root by running `scripts/build-context-map.py`. Read-only on source — only writes the manifest.
How it works
- When to invoke
- When NOT to invoke
- What it does
- Hard rules
- If the rebuild fails
- Verifying the rebuild
- Opting out per-session
- Verbose mode
SKILL.md preview
---
name: refresh-context-map
description: USE WHEN AIDEV anchors / per-dir AGENTS.md / ADRs have changed in this repo and the smart-context-surfacing PreToolUse hook needs an updated manifest. Rebuilds `.claude-leverage-context-map.json` at the repo root by running `scripts/build-context-map.py`. Read-only on source — only writes the manifest.
---
# refresh-context-map
Rebuild the smart-context-surface manifest used by the PreToolUse hook
(`scripts/hooks/context-surface.sh`). See
[`docs/adr/0008-smart-context-surfacing-via-pretooluse-hook.md`](../../docs/adr/0008-smart-context-surfacing-via-pretooluse-hook.md)
for the design rationale.
## When to invoke
- After adding / moving / deleting `AIDEV-NOTE` / `AIDEV-TODO` / `AIDEV-QUESTION` anchors.
- After adding / removing per-directory `AGENTS.md` files.
- After adding new ADRs in `docs/adr/` that reference specific source files.
- After a `git merge` that touched anchor-bearing files (`.gitattributes` keeps
the local manifest on conflict via `merge=ours`, but it'll be stale relative
to the merged tree until rebuilt).
- When `/stack-check` flags drift between the manifest and `git ls-files`.
- Once per significant refactor that moved a lot of files.
## When NOT to invoke
- On every commit — opt-in pre-commit hook (`.githooks/`) does it automatically
if enabled. If you've enabled it, manual `/refresh-context-map` is redundant.
- When you have not adopted the smart-context-surfacing stack in this repo
(no `.claude-leverage-context-map.json` present means the PreToolUse hook
silently no-ops — nothing to refresh).
## What it does
Runs:
```bash
python ${CLAUDE_PLUGIN_ROOT}/scripts/build-context-map.py
```
from the repo root. The script:
1. Walks every git-tracked file (via `git ls-files`), skipping binaries (NUL-byte sniff).
2. For each file with `AIDEV-*` anchors, indexes:
- Anchors inside the file
- Anchors in sibling files (same directory)
- The chain of `AGENTS.md` from `dirname(file)` to repo root
- ADR files (`docs/adr/*.md`) that mention this file path verbatim (word-boundary match)
3. Writes `.claude-leverage-context-map.json` at the repo root, **atomically** (`.tmp` + rename).
The PreToolUse hook reads this manifest on every `Read/Edit/Write/MultiEdit`
and injects a per-file context slice via `hookSpecificOutput.additionalContext`.
## Hard rules
- **Never hand-edit `.claude-leverage-context-map.json`.** It's generated. Edit
the source (anchors, per-dir `AGENTS.md`, ADRs) and rebuild. A hand-edited
manifest drifts from the tree, and the next rebuild silently overwrites it.
- **The manifest IS committed — it is not gitignored.** Unusual for a generated
artifact, but deliberate: every clone and every session gets a fresh-enough
copy with no build step. `.gitattributes` sets `merge=ours` so merge conflicts
on it auto-resolve to local — rebuild afterward (see "When to invoke").
- **Read-only on source.** This skill only ever writes the manifest; it never
touches the files it indexes.
## If the rebuild fails
A failed rebuild is safe. If `python` is missing or the script errors, the
manifest is simply not updated — the PreToolUse hook then reads a stale (or
absent) manifest and **no-ops gracefully**, surfacing slightly less context. It
never blocks a tool call. So a failed rebuild degrades the feature; it does not
break your session. Fix the Python environment and re-run when convenient.
## Verifying the rebuild
After running, the script prints a summary line:
```
Wrote ./.claude-leverage-context-map.json (234 files, 89 anchors)
```
Higher numbers than last time → you've added anchors / ADR references.
Lower numbers → anchors were deleted or files removed from `git ls-files`.
To check drift without writing (CI use):
```bash
python scripts/build-context-map.py --check
# exit 0 if up to date, exit 1 with "DRIFT:" line on stderr if regen would differ
```
## Opting out per-session
Set `CLAUDE_LEVERAGE_CTX_DISABLE=1` in the environment to disable the hook
entirely without removing the manifest. Useful for one-off diagnostic sessions
where the context injection is noise.
## Verbose mode
By default the hook surfaces only `AIDEV-*` anchors (the trap-catching content
per the Run-3 token-tax finding). Set `CLAUDE_LEVERAGE_CTX_VERBOSE=1` to also
include per-dir `AGENTS.md` references and related ADR paths in every
injection. Useful in repos where the per-dir AGENTS.md surface is dense and
worth the extra tokens; off by default to keep the tax minimal in the common
case.
Versions
The database has no other skills named refresh-context-map.
Database snapshot: 13.11.2026 · package version 72ff693cc322 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 82repo-doctor
USE WHEN inheriting a legacy repo, when user asks "what's missing for AI-first work here?", "is this repo agent-ready?", "audit my repo", "is anything out of sync with the code?", or when the bare-repo-nudge / cheatsheet hook suggests a checkup. Read-only AI-readiness audit —… - 100agents-md-generator
Generate or update an AGENTS.md / CLAUDE.md / context file for a repo. Use when the user says "set up CLAUDE.md", "generate AGENTS.md", "write a context file for this repo", "document this codebase for AI agents", or when a fresh repo has none. Also use when an existing context… - 100leverage-cloud-agents
Sets up Leverage Computer, the team agent workspace, so Claude Code and Codex run on persistent cloud machines, then runs the user's first task there. Use when the user says "run Claude Code in the cloud", "cloud agents", "keep my agent running when I close my laptop",… - 100ai-context-refresh
[Documentation] Use when generating, smart-merging or refactoring the root AI context (CLAUDE.md, AGENTS.md) and its Claude/Codex projections. Config file only: project-config. - 100ai-context-refresh
[Documentation] Use when generating, smart-merging or refactoring the root AI context (CLAUDE.md, AGENTS.md) and its Claude/Codex projections. Config file only: project-config. - 90om-create-agents-md
Write, rewrite, or refresh an AGENTS.md (repo root or one package/module) from the actual codebase — Always / Ask First / Never / Validation Commands rules, task checklists, real paths and commands. Follows a repo template when present, else a built-in default. Use for "write…