Navigator Session Statistics Skill

Show real-time efficiency reporting with baseline comparisons, making Navigator's value quantifiable and shareable.

When to Invoke

Invoke this skill when the user:

•Says "show my stats", "show session stats", "show metrics"
•Asks "how efficient am I?", "how much did I save?"
•Says "show my Navigator report", "efficiency report"
•Wants to see token savings or session performance
•Says "show impact", "prove Navigator works"

DO NOT invoke if:

•User just started session (< 5 messages)
•Navigator not initialized in project
•User asking about specific metrics only (answer directly)

Execution Steps

Step 1: Check Navigator Initialized

Verify Navigator is set up:

bash

if [ ! -f ".agent/DEVELOPMENT-README.md" ]; then
  echo "❌ Navigator not initialized in this project"
  echo "Run 'Initialize Navigator' first"
  exit 1
fi

Step 2: Run Enhanced Session Stats

Execute the enhanced session statistics script:

bash

# Check if enhanced script exists
if [ ! -f "scripts/session-stats.sh" ]; then
  echo "❌ Session stats script not found"
  echo "This feature requires Navigator v3.5.0+"
  exit 1
fi

# Run stats script
bash scripts/session-stats.sh

This script outputs shell-parseable variables:

•BASELINE_TOKENS - Total size of all .agent/ docs
•LOADED_TOKENS - Actually loaded in session (estimated)
•TOKENS_SAVED - Difference
•SAVINGS_PERCENT - Percentage saved
•EFFICIENCY_SCORE - 0-100 score
•CACHE_EFFICIENCY - From OpenTelemetry
•CONTEXT_USAGE_PERCENT - Estimated context fill
•TIME_SAVED_MINUTES - Estimated time saved

Step 3: Calculate Efficiency Score

Use predefined function to calculate score:

bash

# Extract metrics from session-stats.sh
source <(bash scripts/session-stats.sh)

# Calculate efficiency score using predefined function
EFFICIENCY_SCORE=$(python3 skills/nav-stats/functions/efficiency_scorer.py \
  --tokens-saved-percent ${SAVINGS_PERCENT} \
  --cache-efficiency ${CACHE_EFFICIENCY} \
  --context-usage ${CONTEXT_USAGE_PERCENT})

Step 4: Format and Display Report

Use predefined function to format visual report:

bash

# Generate formatted report
python3 skills/nav-stats/functions/report_formatter.py \
  --baseline ${BASELINE_TOKENS} \
  --loaded ${LOADED_TOKENS} \
  --saved ${TOKENS_SAVED} \
  --savings-percent ${SAVINGS_PERCENT} \
  --cache-efficiency ${CACHE_EFFICIENCY} \
  --context-usage ${CONTEXT_USAGE_PERCENT} \
  --efficiency-score ${EFFICIENCY_SCORE} \
  --time-saved ${TIME_SAVED_MINUTES}

Output Format:

code

╔══════════════════════════════════════════════════════╗
║          NAVIGATOR EFFICIENCY REPORT                 ║
╚══════════════════════════════════════════════════════╝

📊 TOKEN USAGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Documentation loaded:        12,000 tokens
Baseline (all docs):        150,000 tokens
Tokens saved:               138,000 tokens (92% ↓)

💾 CACHE PERFORMANCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Cache efficiency:              100.0% (perfect)

📈 SESSION METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context usage:                      35% (excellent)
Efficiency score:                94/100 (excellent)

⏱️  TIME SAVED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Estimated time saved:          ~42 minutes

💡 WHAT THIS MEANS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Navigator loaded 92% fewer tokens than loading all docs.
Your context window is 65% available for actual work.

🎯 RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Excellent efficiency - keep using lazy-loading strategy
✅ Context usage healthy - plenty of room for work

Share your efficiency: Take a screenshot! #ContextEfficiency

Step 5: Add Context-Specific Recommendations

Based on efficiency score, provide actionable advice:

If efficiency_score < 70:

code

⚠️  RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Token savings below target (70%+)
→ Check: Are you loading more docs than needed?
→ Tip: Use navigator to find docs, don't load all upfront

Read more: .agent/philosophy/CONTEXT-EFFICIENCY.md

If context_usage > 80%:

code

⚠️  RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Context usage high (80%+)
→ Consider: Create context marker and compact
→ Tip: Compact after completing sub-tasks

Read more: .agent/philosophy/ANTI-PATTERNS.md

If cache_efficiency < 80%:

code

⚠️  RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Cache efficiency low (<80%)
→ Check: CLAUDE.md properly configured?
→ Tip: Ensure prompt caching enabled

Read more: .agent/philosophy/PATTERNS.md (Caching pattern)

Predefined Functions

`efficiency_scorer.py`

Calculate Navigator efficiency score (0-100) based on:

•Token savings (40 points)
•Cache efficiency (30 points)
•Context usage (30 points)

Usage:

bash

python3 skills/nav-stats/functions/efficiency_scorer.py \
  --tokens-saved-percent 92 \
  --cache-efficiency 100 \
  --context-usage 35

Output: 94 (integer score)

`report_formatter.py`

Format efficiency metrics into visual, shareable report.

Usage:

bash

python3 skills/nav-stats/functions/report_formatter.py \
  --baseline 150000 \
  --loaded 12000 \
  --saved 138000 \
  --savings-percent 92 \
  --cache-efficiency 100 \
  --context-usage 35 \
  --efficiency-score 94 \
  --time-saved 42

Output: Formatted ASCII report (see Step 4)

Philosophy Integration

Context Engineering Principle: Measurement validates optimization

From .agent/philosophy/PATTERNS.md:

"Measure to validate. Navigator tracks real metrics, not estimates."

This skill proves:

•Token savings are real (baseline comparison)
•Cache efficiency works (OpenTelemetry data)
•Context usage is healthy (window not overloaded)
•Time saved is quantifiable (6s per 1k tokens)

User Experience

User says: "Show my stats"

Skill displays:

•Visual efficiency report
•Clear metrics (tokens, cache, context)
•Interpretation ("What this means")
•Actionable recommendations

User can:

•Screenshot and share (#ContextEfficiency)
•Understand Navigator's impact
•Optimize workflow based on recommendations
•Validate context engineering principles

Example Output Scenarios

Scenario 1: Excellent Efficiency (Score 94)

User following lazy-loading pattern, cache working perfectly:

•92% token savings ✅
•100% cache efficiency ✅
•35% context usage ✅
•Score: 94/100

Recommendation: Keep it up! Share your efficiency.

Scenario 2: Fair Efficiency (Score 72)

User loading too many docs upfront:

•65% token savings ⚠️
•95% cache efficiency ✅
•55% context usage ✅
•Score: 72/100

Recommendation: Review lazy-loading strategy. Load docs on-demand.

Scenario 3: Poor Efficiency (Score 48)

User not using Navigator patterns:

•45% token savings ❌
•70% cache efficiency ⚠️
•85% context usage ❌
•Score: 48/100

Recommendation: Read philosophy docs. Consider /nav:compact. Review CLAUDE.md.

Success Metrics

After using this skill, users should:

•Understand their efficiency score
•See quantified token savings
•Know what to improve (if anything)
•Feel motivated to share results

Long-term impact:

•Users screenshot reports and share
•"Navigator saved me 138k tokens" becomes common
•Efficiency becomes visible, not abstract
•Continuous improvement through measurement

This skill makes Navigator's value tangible and shareable.