Navigator Session Statistics Skill

Navigator 会话统计Skill

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

展示带有基准对比的实时效率报告，让Navigator的价值可量化、可分享。

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)

当用户出现以下情况时调用此Skill：

说出“显示我的统计数据”“显示会话统计”“显示指标”
询问“我的效率如何？”“我节省了多少？”
说出“显示我的Navigator报告”“效率报告”
想要查看Token节省量或会话性能
说出“显示作用”“证明Navigator有效”

请勿调用的情况：

用户刚开启会话（消息数<5条）
项目中未初始化Navigator
用户仅询问特定指标（直接回答即可）

Execution Steps

执行步骤

Step 1: Check Navigator Initialized

步骤1：检查Navigator是否初始化

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

验证Navigator已配置完成：

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

步骤2：运行增强版会话统计脚本

Execute the enhanced session statistics script:

bash

undefined

执行增强版会话统计脚本：

bash

undefined

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

bash scripts/session-stats.sh


该脚本输出可被Shell解析的变量：
- `BASELINE_TOKENS` - 所有.agent/文档的总大小
- `LOADED_TOKENS` - 会话中实际加载的Token量（估算值）
- `TOKENS_SAVED` - 两者差值
- `SAVINGS_PERCENT` - 节省百分比
- `EFFICIENCY_SCORE` - 0-100分的效率得分
- `CACHE_EFFICIENCY` - 来自OpenTelemetry的缓存效率
- `CONTEXT_USAGE_PERCENT` - 估算的上下文填充率
- `TIME_SAVED_MINUTES` - 估算的节省时长

Step 3: Calculate Efficiency Score

步骤3：计算效率得分

Use predefined function to calculate score:

bash

undefined

使用预定义函数计算得分：

bash

undefined

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})

undefined

EFFICIENCY_SCORE=$(python3 skills/nav-stats/functions/efficiency_scorer.py
--tokens-saved-percent ${SAVINGS_PERCENT}
--cache-efficiency ${CACHE_EFFICIENCY}
--context-usage ${CONTEXT_USAGE_PERCENT})

undefined

Step 4: Format and Display Report

步骤4：格式化并展示报告

Use predefined function to format visual report:

bash

undefined

使用预定义函数将指标格式化为可视化报告：

bash

undefined

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

╔══════════════════════════════════════════════════════╗ ║ 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

undefined

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}


**输出格式**: