Agent skill

area-context-create

Create codebase area context skills for rapid navigation. MUST BE USED for creating area context skills. Handles ONE-TIME auto-detection with Serena, template-based generation, and manual maintenance. Use when creating new area contexts or regenerating existing ones, or when user mentions "create context skill", "generate area context", "map codebase area", skill generation, codebase navigation, area mapping, or template-based skill creation.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/stars-end/agent-skills/tree/master/area-context-create

SKILL.md

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)
bash
# 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:

python
# 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:

python
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:

python
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):

bash
# 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:

markdown
### 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:

bash
# 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:

bash
# 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:

python
# 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:

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

When user updates config:

bash
# Regenerate area
scripts/area-context-update analytics

With Scripts

Pattern:

bash
# 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:

bash
# 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:

yaml
# 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:

yaml
# 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

stars-end/agent-skills

toolchain-health

Validate Python toolchain alignment between mise, Poetry, and pyproject. Use when changing Python versions, editing pyproject.toml, or seeing Poetry/mise version solver errors. Invokes /toolchain-health to check: - .mise.toml python tool version - pyproject.toml python constraint - Poetry env python interpreter Keywords: python version, mise, poetry, toolchain, env use, lock, install

0 0
Explore
stars-end/agent-skills

parallelize-cloud-work

Delegate independent work to Claude Code Web cloud sessions for parallel execution. Generates comprehensive session prompts with context exploration guidance, verifies Beads state, provides tracking commands. Use when user says "parallelize work to cloud", "start cloud sessions", or needs to execute multiple independent tasks simultaneously, or when user mentions cloud sessions, cloud prompts, delegate to cloud, Claude Code Web, generate session prompts, parallel execution, or asks "how do I use cloud sessions".

0 0
Explore
stars-end/agent-skills

docs-create

Create epic-specific documentation skill with external reference docs. MUST BE USED for caching external docs. Fetches URLs, caches full content, uses documentation-engineer to generate cohesive summaries, and creates auto-activating skill. Use when starting work on epic that requires external documentation context (API docs, tool guides, reference materials), or when user mentions "cache docs", "external docs", "API documentation", URLs for docs, documentation needs, reference materials, knowledge caching, or epic context documentation.

0 0
Explore
stars-end/agent-skills

railway-doctor

0 0
Explore
stars-end/agent-skills

git-safety-guard

Installs a Git safety guard hook for Claude Code to prevent destructive Git and filesystem commands. Blocks accidental data loss from commands like 'git checkout --', 'git reset --hard', 'git clean -f', 'git push --force', and 'rm -rf'. Use this skill to set up safety rails in a new or existing repository, or globally for the agent.

0 0
Explore
stars-end/agent-skills

beads-guard

Safe Beads workflow helper (warning-only). Use before bd sync/close/create to avoid JSONL conflicts. Ensures you are on a feature branch, up to date with origin/master, and stages Beads files cleanly with Feature-Key commits.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results