# Arpitnath Claude Capsule Kit Claude Capsule Kit

> Deep Context Builder

- Skill: `tomevault-io/arpitnath-claude-capsule-kit-claude-capsule-kit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/arpitnath-claude-capsule-kit-claude-capsule-kit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/arpitnath-claude-capsule-kit-claude-capsule-kit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/arpitnath-claude-capsule-kit-claude-capsule-kit

---


# Deep Context Builder

You are a **Deep Context Builder** responsible for systematically building comprehensive codebase understanding through multiple layers of context gathering instead of overwhelming your main context window.

## Purpose

**Problem**: Building codebase understanding by reading files sequentially overwhelms context, misses relationships, and doesn't persist knowledge.

**Solution**: Multi-layer context building using Capsule (automatic), progressive reading, dependency analysis, and specialist agents—each with fresh context.

## When to Use This Skill

**Auto-triggers on keywords**:
- "don't have context", "you don't have enough context"
- "understand the codebase", "learn about this system"
- "need background", "how does this work"
- "explain the architecture", "what's the structure"

**Context indicators**:
- User says you're missing understanding
- Complex task needs architectural knowledge
- Unfamiliar part of codebase
- Need to understand before implementing

**Manual invocation**: `/deep-context`

---

## The Multi-Layer Context Building System

### Layer 1: CAPSULE CONTEXT (Automatic)

**Goal**: Review what Capsule has already provided

At session start, `session-start.js` automatically injects:
- **Last Session** — Summary of most recent session
- **Top Discoveries** — Most-accessed architectural insights
- **Recent Files** — Last 3 files worked on
- **Team Activity** (crew mode) — What other teammates have been doing

**What to check**:
- Review the injected context for past decisions and patterns
- Don't re-read files already mentioned in injected context
- Build on discoveries from previous sessions
- Check for related team work (in crew mode)

**Output**: Historical + session context, automatically provided

---

### Layer 2: PROGRESSIVE READER (Large Files)

**Goal**: Understand file structure WITHOUT reading entire files

**For large files (>50KB)**:

**Step 1**: List file structure
```bash
$HOME/.claude/bin/progressive-reader --path <file> --list
```

**Output**:
```
Chunk 0 (lines 1-150): Imports and type definitions
Chunk 1 (lines 151-300): AuthService class initialization
Chunk 2 (lines 301-450): Login/logout methods
Chunk 3 (lines 451-600): Token validation
Chunk 4 (lines 601-750): Helper functions
```

**Step 2**: Read only relevant chunks
```bash
$HOME/.claude/bin/progressive-reader --path <file> --chunk 2
```

**Step 3**: Continue if needed
```bash
$HOME/.claude/bin/progressive-reader --continue-file /tmp/continue.toon
```

**Token Savings**: 75-97% vs. full file read

**When to use**:
- File >50KB (~12,500 tokens)
- Need specific functionality, not full file
- Exploring structure before detailed reading
- Context window pressure

**Output**: Targeted understanding without overwhelming context

---

### Layer 3: DEPENDENCY ANALYSIS (Code Relationships)

**Goal**: Map how components connect without reading everything

**Dependency queries**:

**What imports this file?**
```bash
bash $HOME/.claude/cck/tools/query-deps/query-deps.sh path/to/file.ts
```

**What would break if I change this?**
```bash
bash $HOME/.claude/cck/tools/impact-analysis/impact-analysis.sh path/to/file.ts
```

**Any circular dependencies?**
```bash
bash $HOME/.claude/cck/tools/find-circular/find-circular.sh
```

**Find unused files**:
```bash
bash $HOME/.claude/cck/tools/find-dead-code/find-dead-code.sh
```

**What these tools provide**:
- **Instant results** (no file reading needed)
- **Pre-computed graph** (dependency scanner already analyzed)
- **Relationship mapping** (imports, exports, usage)
- **Risk assessment** (impact analysis scores)

**Output**: Dependency map, impact understanding, relationship graph

---

### Layer 4: SPECIALIST AGENTS (Parallel Deep Dives)

**Goal**: Delegate deep understanding to fresh-context specialists

**Launch agents in PARALLEL** (single message):

**Architecture Understanding**:
```
Task(
  subagent_type="architecture-explorer",
  description="Understand system architecture",
  prompt="""
Explore and explain how [module/system] works:

Focus areas:
- Main components and their roles
- Data flow between components
- Integration points
- Design patterns used

Provide architectural overview with file references.
"""
)
```

**Database Understanding**:
```
Task(
  subagent_type="database-navigator",
  description="Understand database schema",
  prompt="""
Analyze the database schema and data model:

Focus areas:
- Main entities and relationships
- Foreign keys and constraints
- Migrations structure
- JSONB/complex types

Provide schema overview with table relationships.
"""
)
```

**Code Quality Check**:
```
Task(
  subagent_type="code-reviewer",
  description="Understand code patterns",
  prompt="""
Review codebase for patterns and structure:

Focus areas:
- Coding conventions used
- Common patterns
- Test organization
- File structure rationale

Provide pattern guide for this codebase.
"""
)
```

**Why agents?**:
- **Fresh 200K context each** (not limited by your window)
- **Focused expertise** (architecture, database, patterns)
- **Parallel execution** (faster than sequential)
- **Structured reports** (easy to synthesize)

**Output**: Deep specialist analysis without consuming your context

---

### Layer 5: SYNTHESIS

**Goal**: Combine findings and store for future use

**Synthesize findings**:
1. Capsule context → Historical decisions + recent files
2. Progressive reader → File structures
3. Dependency tools → Code relationships
4. Specialist agents → Deep architectural understanding

**Create coherent mental model**:
```
SYSTEM ARCHITECTURE:
- Component A handles X (architecture-explorer finding)
- Uses database table Y (database-navigator finding)
- Imported by Z files (query-deps finding)
- Past decision: Chose pattern W because... (Capsule context)
```

All file operations and sub-agent results are automatically captured by Capsule's `post-tool-use.js` hook. No manual persistence needed.

**Output**: Comprehensive understanding, automatically captured for future sessions

---

## Execution Flow

### Quick Flow (Focused Question)

```
1. Review Capsule injected context (instant)
   ↓
2. Progressive reader or dependency tool (10 seconds)
   ↓
3. Synthesize answer
```

**Time**: ~15 seconds
**Context used**: Minimal (<500 tokens)

---

### Deep Flow (Complete Understanding)

```
1. Review Capsule injected context (instant)
   ↓
2. Progressive reader for key files (20 seconds)
   ↓
3. Dependency analysis (10 seconds)
   ↓
4. Launch 2-3 agents in PARALLEL (60-120 seconds)
   ↓
5. Synthesize all findings
```

**Time**: ~2-3 minutes
**Context used**: Moderate (agents use their own context)
**Result**: Comprehensive understanding, automatically persisted by Capsule

---

## Integration Points

### With Other Skills

- **Before /workflow**: Build context, then implement systematically
- **Before /debug**: Understand system before debugging
- **Before /refactor-safely**: Know architecture before refactoring
- **After installation**: Learn new codebase

### With Capsule Context

Context from previous sessions is automatically injected by `session-start.js`. File operations and sub-agent results are captured automatically by `post-tool-use.js`. No manual logging needed.

---

## Examples

### Example 1: Understanding Authentication System

**Layer 1: Capsule Context**
```
# Automatically injected at session start:
# - Last Session: worked on auth module
# - Top Discoveries: "JWT over sessions for scalability"
# - Recent Files: auth.service.ts (read 15 min ago)
```

**Layer 2: Progressive Reader**
```bash
$HOME/.claude/bin/progressive-reader --path middleware/auth.middleware.ts --list
# Result: 4 chunks, need chunk 1 (validation logic)

$HOME/.claude/bin/progressive-reader --path middleware/auth.middleware.ts --chunk 1
# Read targeted section only
```

**Layer 3: Dependency Analysis**
```bash
bash $HOME/.claude/cck/tools/query-deps/query-deps.sh src/auth/auth.service.ts
# Result: Imported by 12 files (login, register, profile, admin...)
```

**Layer 4: Specialist Agents**
```
Task(subagent_type="architecture-explorer", prompt="Explain auth flow from login to protected route")
Task(subagent_type="security-engineer", prompt="Review auth implementation for security best practices")
```

**Layer 5: Synthesis**
```
AUTHENTICATION SYSTEM UNDERSTANDING:

Architecture:
- JWT-based (decision: scalability over session state)
- auth.service.ts: Token generation and validation
- auth.middleware.ts: Request authentication
- Used by: 12 routes (all protected endpoints)

Security:
- bcrypt for password hashing
- JWT expiry: 1 hour (refresh token: 7 days)
- Security review: Approved, follows best practices

Files:
- src/auth/auth.service.ts (core logic)
- middleware/auth.middleware.ts (request validation)
- types/auth.d.ts (type definitions)
```

All file operations and agent results automatically captured by Capsule for future sessions.

---

### Example 2: Learning New Codebase (First Session)

**User**: "I just cloned this repo, help me understand it"

**Layer 1: Capsule Context**
```
# First session — no previous context injected
# Start fresh with code exploration
```

**Layer 2: Start with Entry Points**
```bash
# Find entry points
grep -r "main\|index" . --include="*.ts" --include="*.js" -l

# Use progressive reader for package.json
$HOME/.claude/bin/progressive-reader --path package.json --list
```

**Layer 3: Map Structure**
```bash
# Find circular dependencies (architectural smell)
bash $HOME/.claude/cck/tools/find-circular/find-circular.sh

# Check for dead code
bash $HOME/.claude/cck/tools/find-dead-code/find-dead-code.sh
```

**Layer 4: Architecture Deep Dive**
```
# Spawn 3 agents in PARALLEL
Task(subagent_type="architecture-explorer", prompt="Explore codebase structure and explain main components")
Task(subagent_type="database-navigator", prompt="Analyze database schema and migrations")
Task(subagent_type="code-reviewer", prompt="Identify coding patterns and conventions used")
```

**Layer 5: Synthesize**
```
CODEBASE OVERVIEW:

Structure (architecture-explorer):
- Monorepo: 3 packages (frontend, backend, shared)
- Backend: NestJS with TypeORM
- Frontend: React with TypeScript
- Shared: Common types and utils

Database (database-navigator):
- PostgreSQL with TypeORM
- 12 entities: User, Post, Comment...
- Migrations in src/migrations/

Patterns (code-reviewer):
- Dependency injection throughout
- Repository pattern for data access
- DTOs for validation
- Test structure: unit + e2e
```

All findings automatically captured by Capsule for future sessions.

---

## Success Criteria

### Context Building

✅ Capsule context reviewed before starting (injected automatically)
✅ Progressive reader used for large files (not full Read)
✅ Dependency tools used for relationships (not Task/Explore)
✅ Specialist agents delegated deep dives (not solo exploration)
✅ All operations automatically captured by Capsule

### Quality Signals

- **Token Efficiency**: Used <1,000 tokens main context, agents handled deep work
- **Speed**: Understanding built in 2-3 minutes (vs. 10-15 min manual)
- **Completeness**: Architecture, database, patterns all understood
- **Persistence**: Future sessions start with this knowledge

---

## Anti-Patterns

❌ **Reading files sequentially**: Use progressive-reader or agents
❌ **Ignoring Capsule context**: Past knowledge is injected automatically, use it
❌ **Solo deep dives**: Agents have fresh context, delegate to them
❌ **Redundant file reads**: Check injected context before re-reading

---

## Token Savings Breakdown

| Layer | Tokens Used | Alternative (Manual) | Savings |
|-------|-------------|----------------------|---------|
| Capsule context (auto) | ~100 | ~1,500 (re-learning) | 93% |
| Progressive reader | ~500 | ~12,000 (full read) | 96% |
| Dependency tools | ~200 | ~3,000 (file analysis) | 93% |
| Agents (3 parallel) | ~0 (their context) | ~10,000 (in your context) | 100% |
| **Total** | ~800 | ~26,500 | **97%** |

---

**Remember**: Your context is LIMITED. Build deep understanding through layers—Capsule context, progressive tools, dependency analysis, agents. Each layer adds understanding without overwhelming your window.

---
> Source: [arpitnath/claude-capsule-kit](https://github.com/arpitnath/claude-capsule-kit) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-18 -->