Area Context Create

Create context skills for codebase areas (<5 min per area, one-time setup).

Purpose

Generate specialized context skills that help agents instantly navigate specific codebase areas (analytics, brokerage, security-resolver, core-data). Each area skill provides:

• Quick file navigation (15 min → instant lookup)
• Symbol-level indexing (classes, functions, key exports)
• Backup file disambiguation (active vs deprecated)
• Test file coverage (where to find tests)
• Entry point guidance (where to start reading)

Impact: Solves 15-minute navigation pain by pre-loading 4 area contexts (28KB total overhead in 200K context).

Philosophy: Manual maintenance (like docs-create), ONE-TIME auto-detection for initial creation.

When to Use This Skill

Trigger phrases:

• "create analytics context"
• "set up brokerage area skill"
• "regenerate security-resolver context"
• "update core-data navigation"

Use when:

• Initial setup (creating all 4 area contexts)
• New area added (expand beyond 4 areas)
• Major refactor (file structure changed significantly)
• Manual maintenance (area expanded, files moved)

Don't use when:

• Minor file changes (wait for batch regeneration)
• PR-level updates (Phase 2 automation handles this)
• Exploring codebase (use Serena tools directly)

Workflow

1. Read Area Configuration

Parse .context/area-config.yml to understand:

• Which area to create/update
• Glob patterns for file matching
• Detector patterns for content scoring
• Exclude patterns (backup files, deprecated)

# Read config
Read .context/area-config.yml

# Validate area exists
if area not in config.areas:
  echo "Error: Area '$area' not defined in area-config.yml"
  exit 1

2. Auto-Detect Files (ONE-TIME)

Use Serena to discover files matching area globs:

# List files matching glob patterns
files = []
for glob_pattern in area_config.globs:
  matches = mcp__serena__list_dir(
    relative_path=extract_base_path(glob_pattern),
    recursive=True,
    file_extensions=extract_extensions(glob_pattern)
  )
  files.extend(filter_by_glob(matches, glob_pattern))

# Apply exclude patterns
files = [f for f in files if not matches_exclude(f, area_config.excludes)]

# Score files by relevance (detector patterns)
scored_files = []
for file in files:
  confidence = calculate_confidence(file, area_config.detectors)
  if confidence >= settings.auto_detect.confidence_threshold:
    scored_files.append((file, confidence))

# Sort by confidence (highest first)
scored_files.sort(key=lambda x: x[1], reverse=True)

# Cap at max_files_per_area
top_files = scored_files[:settings.skill.max_files_per_area]

Confidence calculation:

def calculate_confidence(file_path, detectors):
  # Base score from glob match
  confidence = 0.5

  # Read file content (use Serena)
  content = Read(file_path)

  # Apply detector patterns
  for detector in detectors:
    if re.search(detector.pattern, content):
      confidence += detector.weight

  return min(confidence, 1.0)  # Cap at 1.0

3. Index Symbols with Serena

For each top file, extract symbol overview:

indexed_files = []
for file_path, confidence in top_files:
  # Get symbols overview (lightweight, no bodies)
  overview = mcp__serena__get_symbols_overview(
    relative_path=file_path
  )

  # Parse key symbols
  symbols = {
    "classes": [s.name for s in overview.symbols if s.kind == "class"],
    "functions": [s.name for s in overview.symbols if s.kind == "function"],
    "exports": [s.name for s in overview.symbols if s.exported]
  }

  # Detect file status
  status = "active"
  if "backup" in file_path.lower() or "old" in file_path.lower():
    status = "deprecated"
  elif file_path.startswith("tests/"):
    status = "test"

  indexed_files.append({
    "path": file_path,
    "confidence": confidence,
    "symbols": symbols,
    "status": status,
    "loc": count_lines(file_path)
  })

4. Generate SKILL.md from Template

Use template substitution (like docs-create pattern):

# Read template
template_path=".claude/skills/area-context-create/resources/templates/area-context-template.md"
template_content=$(Read $template_path)

# Prepare metadata
area_name="$1"
description=$(yq .areas.$area_name.description .context/area-config.yml)
keywords=$(yq .areas.$area_name.keywords .context/area-config.yml || echo "")
tags=$(yq .areas.$area_name.tags .context/area-config.yml || echo "[codebase]")
total_files=$(echo "$indexed_files" | jq 'length')
total_loc=$(echo "$indexed_files" | jq '[.[] | .loc] | add')
created_date=$(date +%Y-%m-%d)

# Group files by status (active, deprecated, test)
active_files=$(echo "$indexed_files" | jq '[.[] | select(.status == "active")]')
deprecated_files=$(echo "$indexed_files" | jq '[.[] | select(.status == "deprecated")]')
test_files=$(echo "$indexed_files" | jq '[.[] | select(.status == "test")]')

# Generate file listings
active_listing=$(generate_file_listing "$active_files")
deprecated_listing=$(generate_file_listing "$deprecated_files")
test_listing=$(generate_file_listing "$test_files")

# Substitute placeholders
skill_content=$(echo "$template_content" | \
  sed "s/{{AREA_NAME}}/$area_name/g" | \
  sed "s/{{DESCRIPTION}}/$description/g" | \
  sed "s/{{KEYWORDS}}/$keywords/g" | \
  sed "s/{{TAGS}}/$tags/g" | \
  sed "s/{{TOTAL_FILES}}/$total_files/g" | \
  sed "s/{{TOTAL_LOC}}/$total_loc/g" | \
  sed "s/{{CREATED_DATE}}/$created_date/g" | \
  sed "s|{{ACTIVE_FILES}}|$active_listing|g" | \
  sed "s|{{DEPRECATED_FILES}}|$deprecated_listing|g" | \
  sed "s|{{TEST_FILES}}|$test_listing|g")

# Write to skill directory
skill_dir=".claude/skills/context-$area_name"
mkdir -p "$skill_dir"
echo "$skill_content" > "$skill_dir/SKILL.md"

File listing format:

### Backend (Active)
- analytics_api.py:22 - `get_portfolio_summary()` ✅ CURRENT
- analytics_supabase.py:70 - `SupabaseAnalyticsEngine` class
- analytics_models.py:15 - `PortfolioMetrics` data model

### Backend (Deprecated)
- analytics_api_backup.py ❌ DO NOT EDIT (backup from 2024-11-10)

### Tests
- tests/analytics/test_api.py:50 - `test_portfolio_summary()`

Template variables explained:

Variable	Source	Purpose	Example
{{AREA_NAME}}	CLI arg	Area identifier	analytics
{{DESCRIPTION}}	area-config.yml	Brief summary	Portfolio analytics, metrics calculation
{{KEYWORDS}}	area-config.yml	Trigger words for skill activation	analytics, metrics, portfolio, dashboard
{{TAGS}}	area-config.yml	Skill categorization	[backend, analytics, data]
{{TOTAL_FILES}}	Auto-detected	File count	15
{{TOTAL_LOC}}	Auto-calculated	Lines of code	2847
{{CREATED_DATE}}	Auto-generated	Timestamp	2025-01-18
{{ACTIVE_FILES}}	Auto-generated	Current file listing	See format above
{{DEPRECATED_FILES}}	Auto-generated	Deprecated file listing	See format above
{{TEST_FILES}}	Auto-generated	Test file listing	See format above

Note: The enhanced description field now includes "Use when...", "Invoke when...", and "Keywords:" sections to improve Claude Code's skill activation detection. The {{KEYWORDS}} and {{TAGS}} variables should be defined in area-config.yml for each area.

5. Update Skill Registry

Add auto-activation rules to skill system:

# Update .claude/skills/skill-rules.json (if exists)
if [ -f .claude/skills/skill-rules.json ]; then
  jq ".\"context-$area_name\" = {
    \"triggers\": [\"$area_name\", \"navigate $area_name\", \"$area_name files\"],
    \"intents\": [\"Navigate $area_name codebase\", \"Find $area_name files\"],
    \"examples\": [\"User: 'where is $area_name code?'\"]
  }" .claude/skills/skill-rules.json > tmp.json
  mv tmp.json .claude/skills/skill-rules.json
fi

6. Verify and Report

Final validation:

# Verify SKILL.md created
if [ ! -f ".claude/skills/context-$area_name/SKILL.md" ]; then
  echo "Error: Failed to create SKILL.md"
  exit 1
fi

# Report results
echo "✅ Area context created: context-$area_name"
echo "   Files indexed: $total_files"
echo "   Total LOC: $total_loc"
echo "   Active files: $(echo $active_files | jq 'length')"
echo "   Deprecated: $(echo $deprecated_files | jq 'length')"
echo "   Tests: $(echo $test_files | jq 'length')"
echo ""
echo "📁 Created: .claude/skills/context-$area_name/SKILL.md"
echo ""
echo "🔄 To update later:"
echo "   scripts/area-context-update $area_name"

Integration Points

With Serena MCP

Pattern:

# Don't use bash find/grep - use Serena
files = mcp__serena__list_dir(relative_path="backend", recursive=True)
overview = mcp__serena__get_symbols_overview(relative_path="backend/api/analytics_api.py")

Benefits:

• Respects .gitignore (no node_modules, .venv pollution)
• Symbol-aware (classes, functions, exports)
• Faster than bash find/grep

With area-config.yml

Pattern:

# Manual maintenance (user controls)
areas:
  analytics:
    globs:
      - "backend/**/*analytics*.py"  # User adds/removes patterns
      - "frontend/src/components/*Analytics*.tsx"

When user updates config:

# Regenerate area
scripts/area-context-update analytics

With Scripts

Pattern:

# ONE-TIME auto-detect
scripts/area-context-create analytics

# Manual regeneration
scripts/area-context-update analytics

# Batch regenerate all areas
for area in $(yq '.areas | keys | .[]' .context/area-config.yml); do
  scripts/area-context-update "$area"
done

Best Practices

Do

✅ Use ONE-TIME auto-detection for initial creation only ✅ Rely on manual area-config.yml maintenance ✅ Mark backup files clearly (❌ DO NOT EDIT) ✅ Group files by status (active, deprecated, test) ✅ Cap at max_files_per_area (prevent context bloat) ✅ Sort by relevance (confidence scores) ✅ Include symbol-level navigation (classes, functions) ✅ Test the generated skill (try navigating with it)

Don't

❌ Auto-update areas continuously (manual maintenance only) ❌ Include backup files in active listings ❌ Exceed 500 lines in main SKILL.md (use resources/) ❌ Skip confidence filtering (respect thresholds) ❌ Forget to update skill-rules.json (auto-activation) ❌ Create skills for areas with <5 files (too small)

What This Skill Does

✅ Parse area-config.yml for area definition ✅ Auto-detect files using Serena (ONE-TIME) ✅ Score files by confidence (glob + detector patterns) ✅ Index symbols (classes, functions, exports) ✅ Identify file status (active, deprecated, test) ✅ Generate SKILL.md from template ✅ Update skill registry (auto-activation) ✅ Report results (files, LOC, status breakdown)

What This Skill DOESN'T Do

❌ Continuous auto-update (manual maintenance only) ❌ Deep dependency analysis (Serena doesn't support this) ❌ Automatic area discovery (user defines areas) ❌ GitHub Actions integration (Phase 2 handles this) ❌ PR-level incremental updates (use area-context-update)

Examples

Example 1: Create Analytics Context

User: "create analytics context"

AI reads .context/area-config.yml
→ Area: analytics
→ Globs: backend/**/*analytics*.py, frontend/**/*Analytics*.tsx
→ Detectors: SupabaseAnalyticsEngine, calculate_portfolio

AI uses Serena to list files
→ Found 23 files matching globs
→ Apply excludes (backup files removed)
→ Score by confidence (detector patterns)
→ Top 20 files (confidence > 0.5)

AI indexes symbols with Serena
→ analytics_api.py: get_portfolio_summary(), ...
→ analytics_supabase.py: SupabaseAnalyticsEngine class
→ analytics_models.py: PortfolioMetrics model

AI generates SKILL.md from template
→ Substitute {{AREA_NAME}} → analytics
→ Substitute {{ACTIVE_FILES}} → formatted listing
→ Write to .claude/skills/context-analytics/SKILL.md

Result:
✅ Created: context-analytics skill
✅ Files: 20 active, 2 deprecated, 5 tests
✅ Total LOC: 3,200
✅ Navigation: 15 min → instant

Example 2: Regenerate After Major Refactor

User: "regenerate all area contexts"

AI batch regenerates:
for area in [analytics, brokerage, security-resolver, core-data]:
  scripts/area-context-update $area

analytics: ✅ Updated (5 new files, 2 removed)
brokerage: ✅ Updated (no changes)
security-resolver: ✅ Updated (3 files moved)
core-data: ✅ Updated (10 new migrations)

Result:
✅ All 4 areas refreshed
✅ Total time: 8 minutes
✅ Ready for navigation

Example 3: Add New Area (Future)

User: "add reporting area"

AI guides user:
1. Edit .context/area-config.yml
2. Add reporting area definition:
   areas:
     reporting:
       description: "Report generation, exports, PDFs"
       globs: ["backend/**/*report*.py", "frontend/**/*Report*.tsx"]
3. Run: scripts/area-context-create reporting

Result:
✅ Created: context-reporting skill
✅ 5th area added to system
✅ Pre-loaded in all sessions (34KB total overhead)

Troubleshooting

No Files Found

Symptom: Auto-detect finds 0 files for area

Diagnosis:

• Check glob patterns in area-config.yml
• Verify files exist (use bash ls or Serena list_dir)
• Check exclude patterns (might be too broad)

Fix:

# Debug glob matching
yq '.areas.analytics.globs' .context/area-config.yml
ls backend/**/*analytics*.py

Low Confidence Scores

Symptom: All files filtered out by confidence threshold

Diagnosis:

• Detector patterns don't match file contents
• Threshold too high (default 0.5)

Fix:

# Lower threshold in area-config.yml
settings:
  auto_detect:
    confidence_threshold: 0.3  # Was 0.5

Too Many Files

Symptom: Area has >50 files (exceeds max_files_per_area)

Diagnosis:

• Globs too broad (matching unrelated files)
• Area too large (consider splitting)

Fix:

# Narrow globs
globs:
  - "backend/api/*analytics*.py"  # More specific
  # - "backend/**/*analytics*.py"  # Too broad (removed)

# Or increase cap
settings:
  skill:
    max_files_per_area: 80  # Was 50

Related Resources

• Template: resources/templates/area-context-template.md (SKILL.md generation)
• Examples: resources/examples/ (sample generated skills)
• Scripts: scripts/area-context-create, scripts/area-context-update
• Config: .context/area-config.yml (area definitions)

---

Last Updated: 2025-11-17 Skill Type: Meta-skill Impact: Skill system (creates context-* skills) Average Duration: 5 minutes per area Related Docs:

• CLAUDE.md (V3 DX Workflow)
• .claude/skills/skill-creator/SKILL.md (meta-skill pattern)
• docs/DX_PARITY_V3/SKILL_ACTIVATION_SYSTEM_SPEC.md