Claude Context Manager

This skill enables you to work as an autonomous context manager for codebases, maintaining accurate and actionable context intelligence through

claude.md

files.

What This Skill Provides

Behavioral guidance: Instructions for working proactively as a context manager
Monitoring tools: Scripts to assess context health and detect staleness
Update automation: Intelligent context synchronization based on code changes
Quality standards: Patterns for creating actionable, dense agent context

Core Concept

claude.md

files are cognitive maps - operational intelligence that helps you:

Navigate faster (know structure and entry points)
Generate better (follow existing patterns)
Avoid errors (understand constraints and gotchas)
Make decisions (know the rules and conventions)

This is agent context, not documentation. The goal is making future-Claude more effective.

Context Manager Mode

Before starting, read

references/context_manager_mode.md

to understand how to work autonomously and proactively as a context manager.

Key operating principles:

Proactive: Monitor and update without being asked
Surgical: Update only what's needed
Communicative: Explain actions clearly
Autonomous: Make decisions within boundaries

Workflow Decision Tree

Starting fresh in a repository? → "Initial Setup" workflow

Working in active codebase? → "Continuous Maintenance" workflow

Code just changed significantly? → "Change-Responsive Update" workflow

Exploring existing context? → "Context Exploration" workflow

Initial Setup

When first working in a repository that needs context management:

1. Assess Current State

bash

python scripts/scan_repo.py /path/to/repo

This shows:

Directories that should have context
Directories that already have context
Coverage gaps

2. Prioritize Areas

Focus on high-impact directories first:

Entry points (src/main, src/index, etc.)
Core business logic (src/services, src/api)
Complex areas (src/db, src/auth)
Active development areas (check git activity)

3. Generate Initial Context

For each priority directory:

bash

python scripts/generate_claude_md.py /path/to/directory

This creates structured context with:

Auto-detected purpose
File analysis
Pattern placeholders
TODO markers for manual completion

4. Customize and Refine

Review generated files and:

Fill in TODO markers with specific information
Add patterns you observe
Document gotchas
Note relationships

Use

references/structure_guide.md

and

references/examples.md

for guidance.

5. Create Index

bash

python scripts/create_index.py /path/to/repo

Generates navigable index of all context files.

Continuous Maintenance

Once context exists, maintain it autonomously:

1. Regular Health Checks

Run periodically (start of session, after major work):

bash

python scripts/monitor.py /path/to/repo

Provides:

Health score (0-100)
Files by priority (critical/high/medium/low)
Specific recommendations
Staleness metrics

2. Act on Findings

Critical priority (immediate action):

bash

python scripts/auto_update.py /path/to/directory

High priority (soon):

bash

python scripts/auto_update.py /path/to/directory --analyze-only
# Review suggestions, then update

Medium/Low priority (monitor): Note for later, continue monitoring

3. Validate Quality

After updates:

bash

python scripts/validate_claude_md.py /path/to/directory/claude.md

Checks for:

Required sections
Actionable content
TODO markers
Broken links

4. Update Index

Periodically refresh the index:

bash

python scripts/create_index.py /path/to/repo

Change-Responsive Update

When code changes occur (you made changes or observed changes):

1. Detect Affected Context

For each changed directory:

bash

python scripts/auto_update.py /path/to/directory --analyze-only

This analyzes:

Recent changes (git history)
Current patterns
Framework detection
Update recommendations

2. Review and Update

If update recommended:

bash

python scripts/auto_update.py /path/to/directory

This performs surgical updates:

Preserves accurate content
Updates specific sections
Adds newly discovered patterns
Timestamps changes

3. Verify

bash

python scripts/validate_claude_md.py /path/to/directory/claude.md

Context Exploration

When entering an area with existing context:

1. Read Context

Before working, read the

claude.md

file:

bash

view /path/to/directory/claude.md

Understand:

Directory purpose
Pattern expectations
Key files and relationships
Known gotchas

2. Verify Accuracy

As you work, note:

✅ Information that was helpful
❌ Information that was wrong/misleading
📝 Information that's missing

3. Update Immediately

If you discover inaccuracies or important missing info:

bash

# Update the specific file
str_replace /path/to/directory/claude.md

Or use auto-update for comprehensive refresh.

4. Note Patterns

When you discover patterns not documented:

Add them to context immediately
Include examples
Note why they matter

Autonomous Decision-Making

You CAN Act Autonomously

✅ Update context when:

Staleness score > 4 (critical)
You just changed code affecting patterns
You discover inaccuracies while working
You have info to fill TODO markers

✅ Generate new context when:

Directory has 3+ files and no context
You struggled without context here
Clear patterns emerge

You SHOULD Ask First

⚠️ Before:

Deleting existing context
Major restructuring
Updating very recent context (<7 days)
Bulk operations on many files

Tools Reference

monitoring scripts/monitor.py

Assesses context health across repository.

Key outputs:

Health score (0-100)
Staleness metrics
Priority categorization
Action recommendations

Usage:

bash

python scripts/monitor.py /path/to/repo [--format json|text]

Exit codes:

0: Healthy
1: High priority issues
2: Critical issues

Auto-Update: scripts/auto_update.py

Intelligently updates context based on code changes.

What it does:

Analyzes recent git changes
Detects current patterns
Identifies needed updates
Surgically updates context

Usage:

bash

python scripts/auto_update.py <directory> [--analyze-only] [--force]

Modes:

Default: Analyze and update
```
--analyze-only
```
: Show recommendations only
```
--force
```
: Update even if no changes detected

Scanning: scripts/scan_repo.py

Identifies directories needing context.

Usage:

bash

python scripts/scan_repo.py <repo_path> [--min-files N] [--show-existing]

Generation: scripts/generate_claude_md.py

Creates new context files with smart defaults.

Usage:

bash

python scripts/generate_claude_md.py <directory> [--output FILE] [--force]

Validation: scripts/validate_claude_md.py

Checks context quality and completeness.

Usage:

bash

python scripts/validate_claude_md.py <path> [--strict]

Indexing: scripts/create_index.py

Builds master index of all context files.

Usage:

bash

python scripts/create_index.py <repo_path> [--format tree|table|detailed]

Reference Materials

Essential Reading

references/context_manager_mode.md

Read this first. Explains how to work autonomously as a context manager - mindset, workflows, communication patterns, quality standards.

references/structure_guide.md

Best practices for agent context - what to include, what to avoid, how to structure, maintenance triggers.

references/examples.md

Real-world examples for different directory types - API layers, services, tests, config, models.

Templates

assets/templates/source-code-template.md

Starting template for general source directories.

assets/templates/test-directory-template.md

Starting template for test suites.

Communication Patterns

When Monitoring

Do:

Context health check complete. 3 files need attention:

src/api/ (critical - 45 days, 23 commits) → Updating now

src/services/ (high - 30 days, 15 commits) → Should I update?

tests/integration/ (medium - 20 days) → Monitoring

Don't:

I checked and there are issues.

When Updating

Do:

Updated src/api/claude.md: • Added rate limiting pattern (introduced last sprint) • Updated middleware chain (auth-jwt.ts now handles tokens) • Removed deprecated cors-handler.ts reference

Context now current with HEAD.

Don't:

Updated file.

When Suggesting

Do:

src/utils/ has 12 files but no context. Analysis shows: • Mix of helpers (strings, dates, validation) • No clear pattern - might need reorganization • Create context as-is, or refactor first?

Don't:

You should add context there.

Quality Standards

Actionable Over Descriptive

Every section should answer: "What does this tell me to DO differently?"

❌ Descriptive:

markdown

This directory contains services.

✅ Actionable:

markdown

**Service Pattern**: Class-based with constructor DI
**Rule**: All async methods, throw domain errors (never return errors)
**Example**: `class UserService { constructor(db, logger) {} }`

Dense Over Verbose

Use tokens efficiently.

❌ Verbose:

markdown

The API directory is important. It handles requests from the frontend.
It communicates with backend services. It uses Express.js.

✅ Dense:

markdown

**Framework**: Express 4.x  
**Pattern**: Route → Validator → Service → Serializer  
**Rule**: No direct DB, asyncHandler required

Current Over Historical

Context must reflect reality, not history.

❌ Historical:

markdown

We migrated from MySQL to PostgreSQL in 2023.

✅ Current:

markdown

**Database**: PostgreSQL 15, Prisma ORM
**Migrations**: prisma/migrations/

CCMP Plugin Integration

Context manager automatically integrates with other CCMP plugins:

With session-management 🔄

Sessions load relevant context automatically: When a session starts, relevant

claude.md

files are loaded based on objectives.

Context health in session handoffs: Session handoffs include context health reports and update recommendations.

Checkpoints trigger health checks: Session checkpoints automatically check if changed directories have stale context.

To enable: Use

lib/session_integration.py

in your session workflow.

With tdd-workflow 🧪

TDD cycles update test context: When TDD GREEN checkpoints succeed, test documentation can be auto-updated with discovered patterns.

Integration API:

python

from lib.ccmp_integration import CCMPIntegration

integration = CCMPIntegration()
integration.update_state("claude-context-manager", {
    "health_score": 87,
    "last_scan": "2025-11-01T10:00:00Z",
    "critical_files": ["src/api/"]
})

Integration with Development

As You Code

Maintain context awareness:

Working in new directory?
  → Check for context
  → Note if missing

Discovering pattern?
  → Check if documented
  → Add if missing

Finding gotcha?
  → Add to context immediately

Before Finishing

Quick maintenance check:

Run:
```
python scripts/monitor.py .
```
Update critical items
Note medium/low for later
Leave breadcrumbs for next session

Success Indicators

You're managing context well when:

✅ Context helps you work faster
✅ Updates are small and frequent
✅ You rarely hit outdated info
✅ Code generation follows patterns correctly
✅ New areas are easier to understand

Remember

Context management isn't about perfect documentation - it's about maintaining cognitive maps that multiply your effectiveness.

Every

claude.md

file should make future-you faster, more accurate, and more pattern-aware.

Your mission: Make the next Claude session in this codebase even better.

claude-context-manager

NPX Install

Tags

SKILL.md Content

Claude Context Manager

What This Skill Provides

Core Concept

Context Manager Mode

Workflow Decision Tree

Initial Setup

1. Assess Current State

2. Prioritize Areas

3. Generate Initial Context

4. Customize and Refine

5. Create Index

Continuous Maintenance

1. Regular Health Checks

2. Act on Findings

3. Validate Quality

4. Update Index

Change-Responsive Update

1. Detect Affected Context

2. Review and Update

3. Verify

Context Exploration

1. Read Context

2. Verify Accuracy

3. Update Immediately

4. Note Patterns

Autonomous Decision-Making

You CAN Act Autonomously

You SHOULD Ask First

Tools Reference

monitoring scripts/monitor.py

Auto-Update: scripts/auto_update.py

Scanning: scripts/scan_repo.py

Generation: scripts/generate_claude_md.py

Validation: scripts/validate_claude_md.py

Indexing: scripts/create_index.py

Reference Materials

Essential Reading

Templates

Communication Patterns

When Monitoring

When Updating

When Suggesting

Quality Standards

Actionable Over Descriptive

Dense Over Verbose

Current Over Historical

CCMP Plugin Integration

With session-management 🔄

With tdd-workflow 🧪

Integration with Development

As You Code

Before Finishing

Success Indicators

Remember