# Smart Context

> Token-optimized context loading: load the cached project index at session start, then Grep before Read, expanding only as needed. Use when starting a session, deciding what context to load, or generating/refreshing the project index. For feature-name → file-path lookups, the file-index skill answers directly from this index.

- Skill: `theophiluschinomona/smart-context` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add theophiluschinomona/smart-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theophiluschinomona/smart-context/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: TheophilusChinomona (https://skillmd.com/u/theophiluschinomona)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/theophiluschinomona/smart-context

---


# Smart Context Skill

## Purpose
Token-optimized context loading using the project-map as the data source.

## Data Sources (Priority Order)
1. `.claude/idev/smart-context/index.json` - Lightweight index (~70 lines)
2. `.claude/idev/project-map/project.map.md` - Full project map (load sections on demand)

## Activation
This skill is ALWAYS ACTIVE. Apply these rules to every task.

---

## Generating the index

**Step 0: Ensure project-map exists.** The project map is the data source
for the index. If `.claude/idev/project-map/project.map.md` is missing or
severely stale (>30 days), generate it first:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/project-map/ai_map_updater.py"
```

This auto-detects split vs unified projects and writes the map. Only takes
a few seconds and only runs when needed (missing or stale).

**Step 1: Generate the index.** If `index.json` is missing (e.g. the
session-start hook reports no index), generate it by running the scanner
from the project root:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/smart-context/scanner.py"
```

This writes `.claude/idev/smart-context/index.json` with the detected stack, structure roots, feature names, and file-naming patterns.

**Fallback (no python3 available):** build the index manually — detect the stack from `package.json` / `*.csproj` / `requirements.txt` / `go.mod`, list feature directory names under `features/` or `modules/`, note naming patterns (e.g. `*Controller.*`, `*.hook.*`), and write the same JSON shape (`stack`, `structure`, `features`, `patterns`) to `.claude/idev/smart-context/index.json`.

---

## Phase 1: Session Start

Load ONLY the lightweight index:
```
.claude/idev/smart-context/index.json
```

This gives you (contents depend on what the scanner detected):
- Tech stack (e.g. React + .NET, Next.js + Python — whatever the project uses)
- Detected feature names (up to 50)
- File-naming patterns (e.g. Page, Container, Service, Controller)
- Project structure roots

**DO NOT load the full project-map yet.**

---

## Phase 2: Task Analysis

### Step 2.1: Extract Keywords
From user message, identify:
- **Feature name**: whatever appears in index.json's features list (e.g. orders, customers, auth)
- **Action type**: fix, add, update, delete, explain, find
- **Layer**: frontend, backend, api, database, full-stack

### Step 2.2: Determine What to Load

| Task Type | What to Load |
|-----------|--------------|
| Feature-specific task | Grep for feature files only |
| "Where is X?" | Grep, don't read full map |
| "List all controllers" | Load project-map backend section only |
| Architecture question | Load project-map structure section |
| Bug fix in specific file | Grep → Read that file only |

---

## Phase 3: Smart Loading from Project Map

When you need the project-map, load ONLY the relevant section:

### Section Loading
```markdown
# To find frontend files for a feature:
Grep "FeatureName" in project.map.md → Get file paths → Read specific files

# To find backend controller:
Grep "OrdersController" in project.map.md → Get path → Read controller

# To understand FE→BE mapping:
Load only the "FE → BE Mappings" section if it exists
```

### Never Do This
❌ Read the entire project.map.md (it can run to thousands of lines)
❌ Load all controllers "to understand the project"
❌ Pre-load map sections not related to current task

### Always Do This
✅ Grep project.map.md for keywords first
✅ Extract only the paths you need
✅ Read actual source files targeted by path

---

## Phase 4: Using Both Systems Together

```
User asks about "orders"
         ↓
Check index.json → "Orders" is a known feature
         ↓
Grep project.map.md for "*Order*" → Get 5 file paths
         ↓
Read only the relevant file (e.g., OrderListContainer.tsx)
         ↓
If needed, follow imports to related files
```

---

## Phase 5: Pattern Reference

Use the `patterns` section of index.json. Illustrative examples (the real globs come from index.json):

| Pattern | Glob |
|---------|------|
| Page | `**/pages/*Page.tsx` |
| Container | `**/containers/*Container.tsx` |
| Service (FE) | `**/services/*.service.ts` |
| Hook | `**/hooks/*.hook.ts` |
| Controller | `**/*Controller.cs` |
| Service (BE) | `**/*Service.cs` |

---

## Feature Keywords → Search Patterns

Illustrative examples ONLY — the real keyword list is the `features` array in index.json; build the same `**/[Xx]keyword*` glob for whatever features that project actually has:

| Keyword | Search |
|---------|--------|
| order, orders | `**/[Oo]rder*` |
| customer | `**/[Cc]ustomer*` |
| invoice | `**/[Ii]nvoice*` |
| auth, login | `**/[Aa]uth*` |
| payment | `**/[Pp]ay*` |
| user | `**/[Uu]ser*` |
| dashboard | `**/[Dd]ashboard*` |

---

## Anti-Patterns (DO NOT DO)

1. ❌ Loading entire project.map.md at session start
2. ❌ Reading all files in a feature folder
3. ❌ Pre-loading "just in case"
4. ❌ Ignoring index.json and going straight to map
5. ❌ Reading files not mentioned by user

---

## Token Budget Guide

| Action | Estimated Tokens |
|--------|------------------|
| Load index.json | ~100 |
| Grep project.map.md | ~50 |
| Read specific section of map | ~200-500 |
| Read one source file | ~200-800 |
| **Target per task** | **< 1,500** |

---
## Staleness Detection

The index.json records a `generated` timestamp. Check staleness:
```
1. Read index.json and extract the "generated" date
2. If older than 14 days → warn: "smart-context index is N days old — may miss new features"
3. If older than 30 days → fail loudly: "smart-context index is severely stale — regenerate"
4. If missing → generate before proceeding (see "Generating the index" above)
```

The session-start hook also checks file mtime and warns if > 14 days old.
When regenerating, the scanner updates the `generated` timestamp automatically.

## Summary

```
index.json (always)
      ↓
Grep for keywords (fast)
      ↓
project.map.md section (if needed)
      ↓
Actual source files (targeted)
```

The project-map is your detailed reference. The index.json is your quick lookup. Use them together, but always start minimal.