context-map

Files (4)

• SKILL.md
• code-lens.md · references/
• research-lens.md · references/
• profile-folder.ps1 · scripts/

SKILL.md (first lines)

# Context Map

Produce a single, factual, skimmable map of everything a person needs to understand a
folder — so they (or another agent) can reason about it without opening it themselves.

The hard part this skill solves: a folder might be a **codebase**, a **research/notes
collection**, or a **mix**. Each needs a different reading lens. Detect the type first,
then map it with the matching lens. Don't read code like prose or prose like code.

## What this is NOT

Keep the output honest about its job. This prevents the three most common ways a folder
summary goes wrong:

- **Not a narrative.** No "the story behind the code," no chronological journey. A map,
  not a documentary. People skim a map; they don't read it front to back.
- **Not a decision.** Don't recommend splitting/merging/refactoring, don't pick a winner,
  don't editorialize on what they *should* do. The user reasons about strategy separately,
  using this map as input. Give them the territory, not the verdict.
- **Not a pre-implementation checklist.** This isn't "files you must change for task X."
  There is no task. It's standing context about what exists.

If you notice yourself writing "you should" or "I recommend," stop — that's the user's job.

## Workflow

### 1. Identify the target

Use the path the user gives. If they didn't give one, use the current working directory.
Confirm the resolved path in your first line of output so there's no ambiguity.

### 2. Profile the folder (cheap, deterministic, read-only)

Run the bundled profiler before reading anything — it counts files by type, measures size
and depth, finds structural markers (`package.json`, `pyproject.toml`, `src/`, `.obsidian/`,
`raw/`, etc.), and prints a **type hint** and a **scale hint**. This is far cheaper and more
reliable than manually listing files.

```powershell
& "~/.claude\skills\context-map\scripts\profile-folder.ps1" "<target-path>"
```

Use the call operator (`&`) as shown — do **not** prepend `powershell -ExecutionPolicy
Bypass -File`. That flag is classified as a security-weakening action and gets blocked
under default auto-mode permissions; the call-operator form runs the script directly with
no bypass needed.

(If you're not on Windows, profile manually with Glob/Grep: count code vs. prose file
extensions, note dependency manifests and folder markers, estimate size.)

### 3. Decide the lens

Use the profiler's type hint as a strong prior, but sanity-check it against what the markers
actually say — a folder of 200 markdown files with a `package.json` is still a research
folder with a tooling sidecar.

| Profile signal | Lens |
|---|---|
| Dependency manifests, `src/`/`tests/`, code files dominate | **CODE** → read `references/code-lens.md` |
| Mostly `.md`/`.txt`/`.pdf`, `.obsidian/`, `raw/`/`notes/`/`sources/`, prose dominates | **RESEARCH** → read `references/research-lens.md` |
| Both present in real proportion | **MIXED** → pick the *dominant* lens as primary; see "Mixed folders" below |

A note on edge cases: a lone self-contained `.html`/`.ipynb`/script that is clearly a
*deliverable or planning artifact* (a one-file tool, a notebook write-up) sitting in an
otherwise prose folder does **not** make the folder MIXED or CODE — it stays RESEARCH, and
the artifact goes in the "Also present" section. The question is what the folder is *for*,
not just its file extensions. When the profiler hint and the markers disagree, trust what
the contents tell you.

Read the matching lens reference file now — it has the exact section template for that type.

### 4. Decide the reading strategy by scale

The profiler prints a scale hint:

- **SMALL** (roughly < 150 files / < 5 MB of content): read inline yourself. Open the
  key files the lens calls for and synthesize directly.
- **LARGE**: fan out. Spawn parallel subagents (the `Explore` agent type is ideal — it's
  read-only and built for breadth) to cover different subtrees or concerns, each returning
  a compact partial map, then you synthesize them into one. This keeps a big codebase from
  blowing the budget on one serial read. Give each subagent a slice ("map the `api/`
  subtree: entrypoints, key modules, dependencies") and the relevant lens sections so the
  partials compose cleanly.

In-session subagent reads use the subscription, not per-call API spend — fanning out on a
large folder is the right call, not an extravagance.

### 5. Produce the map

Start with this shared header, then fill in the lens-specific body from the reference file.

```markdown
# Context map: <folder name>

**Path:** <resolved absolute path>
**Type:** CODE | RESEARCH | MIXED (primary: <lens>)
**Size:** <N files, ~M MB>  ·  **Mapped via:** single pass | N subagents

## TL;DR
<3–5 sentences: what this folder is, its apparent purpose, and its overall state of
maturity. Enough that someone who reads only this paragraph isn't lost.>

<-- lens-specific sections go here, from references/code-lens.md or research-lens.md -->
```

Keep it skimmable: headers, tables, and tight bullets over long paragraphs. Comprehensive
in coverage, economical in words. A reader should be able to scan headers and jump to the
part they need.

### Mixed folders — primary lens + flag the rest

When a folder is genuinely both code and research, don't produce two full maps (redundant)
and don't ignore the minority material (loses context). Instead:

- Map the **dominant** character fully with its lens.
- Add one section near the end titled **"Also present: <other type>"** that briefly
  characterizes the secondary material — what it is, where it lives, how much, and whether
  it looks active or stale. A few bullets, not a second map.

From julianhernandez2155/claude-code-harness, MIT.

More from julianhernandez2155/claude-code-harness