Skip to content
Skills Library
AI & agents · Automation

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.

Licence
MIT
Last repository change
03.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.08.2026, without references to retired models or APIs.

Licence

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

  1. When to invoke
  2. When NOT to invoke
  3. What it does
  4. Hard rules
  5. If the rebuild fails
  6. Verifying the rebuild
  7. Opting out per-session
  8. Verbose mode
Original SKILL.md headings · 101 lines, 586 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.