Metrics

Metrics Dashboard

View and analyze execution metrics for the Claude AS framework.

---

OPERATING MODE

/metrics                    → Show metrics dashboard
/metrics agents             → Agent performance breakdown
/metrics stories            → Story completion analysis
/metrics errors             → Error analysis and patterns
/metrics trends             → Trend analysis over time
/metrics export [format]    → Export metrics (json/csv/md)
/metrics reset              → Reset metrics (with confirmation)

---

DASHBOARD VIEW

On /metrics invocation, display the comprehensive dashboard:

METRICS DASHBOARD
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PROJECT: [project-name]
PERIOD: All time (since [start-date])

QUICK STATS
┌────────────────────────────────────────────────────────────────┐
│ Executions: [N]  │  Success: [X]%  │  Stories: [N]  │ Tokens: [X]K │
└────────────────────────────────────────────────────────────────┘

RECENT ACTIVITY (Last 7 days)
├── Executions: [N]
├── Stories Completed: [N]
├── Success Rate: [X]%
└── Avg Tokens/Execution: [X]K

TOP PERFORMING AGENTS
1. [agent-name]: [X]% success ([N] calls)
2. [agent-name]: [X]% success ([N] calls)
3. [agent-name]: [X]% success ([N] calls)

ATTENTION NEEDED
[List any metrics below threshold]

Use /metrics [category] for detailed breakdowns.

---

AGENT METRICS

On /metrics agents:

AGENT PERFORMANCE METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

OVERVIEW
┌──────────────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
│ Agent            │ Calls    │ Success  │ Partial  │ Failed   │ Avg Tok  │
├──────────────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
│ ruthless-coder   │ [N]      │ [X]%     │ [X]%     │ [X]%     │ [X]K     │
│ ruthless-tester  │ [N]      │ [X]%     │ [X]%     │ [X]%     │ [X]K     │
│ gate-keeper      │ [N]      │ [X]%     │ [X]%     │ [X]%     │ [X]K     │
│ cold-architect   │ [N]      │ [X]%     │ [X]%     │ [X]%     │ [X]K     │
│ docs-codifier    │ [N]      │ [X]%     │ [X]%     │ [X]%     │ [X]K     │
│ debug-hunter     │ [N]      │ [X]%     │ [X]%     │ [X]%     │ [X]K     │
└──────────────────┴──────────┴──────────┴──────────┴──────────┴──────────┘

PERFORMANCE RANKING
1. 🥇 [agent]: [X]% success rate
2. 🥈 [agent]: [X]% success rate
3. 🥉 [agent]: [X]% success rate

TOKEN EFFICIENCY
Most Efficient: [agent] ([X] tokens/call avg)
Least Efficient: [agent] ([X] tokens/call avg)

RECENT FAILURES BY AGENT
┌──────────────────┬──────────┬────────────────────────────────────┐
│ Agent            │ Failures │ Common Cause                       │
├──────────────────┼──────────┼────────────────────────────────────┤
│ [agent]          │ [N]      │ [most common error type]           │
└──────────────────┴──────────┴────────────────────────────────────┘

RECOMMENDATIONS
[Based on agent performance, suggest improvements]

---

STORY METRICS

On /metrics stories:

STORY COMPLETION METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

OVERALL
├── Total Stories: [N]
├── Completed: [N] ([X]%)
├── Failed: [N] ([X]%)
├── Blocked: [N] ([X]%)
└── Avg Tokens/Story: [X]K

BY COMPLEXITY
┌────────────┬───────┬──────────┬──────────┬──────────┐
│ Complexity │ Count │ Success  │ Failed   │ Avg Tok  │
├────────────┼───────┼──────────┼──────────┼──────────┤
│ Simple     │ [N]   │ [X]%     │ [X]%     │ [X]K     │
│ Medium     │ [N]   │ [X]%     │ [X]%     │ [X]K     │
│ Complex    │ [N]   │ [X]%     │ [X]%     │ [X]K     │
└────────────┴───────┴──────────┴──────────┴──────────┘

BY LAYER
┌────────────┬───────┬──────────┬──────────┐
│ Layer      │ Count │ Success  │ Trend    │
├────────────┼───────┼──────────┼──────────┤
│ Database   │ [N]   │ [X]%     │ [trend]  │
│ Backend    │ [N]   │ [X]%     │ [trend]  │
│ Frontend   │ [N]   │ [X]%     │ [trend]  │
│ Tests      │ [N]   │ [X]%     │ [trend]  │
│ Docs       │ [N]   │ [X]%     │ [trend]  │
└────────────┴───────┴──────────┴──────────┘

MOST COMMON FAILURE POINTS
1. [failure type]: [N] occurrences
2. [failure type]: [N] occurrences
3. [failure type]: [N] occurrences

RECOMMENDATIONS
[Based on story patterns, suggest improvements]

---

ERROR METRICS

On /metrics errors:

ERROR ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SUMMARY
├── Total Errors: [N]
├── Recovery Rate: [X]%
├── Rollbacks Triggered: [N]
└── Avg Errors/Execution: [X]

BY ERROR TYPE
┌────────────────────┬───────┬──────────┬──────────┐
│ Error Type         │ Count │ % Total  │ Recovered│
├────────────────────┼───────┼──────────┼──────────┤
│ TEST_FAILED        │ [N]   │ [X]%     │ [X]%     │
│ BUILD_FAILED       │ [N]   │ [X]%     │ [X]%     │
│ BLOCKED            │ [N]   │ [X]%     │ [X]%     │
│ TIMEOUT            │ [N]   │ [X]%     │ [X]%     │
│ INVALID_INPUT      │ [N]   │ [X]%     │ [X]%     │
│ SECURITY_VIOLATION │ [N]   │ [X]%     │ [X]%     │
└────────────────────┴───────┴──────────┴──────────┘

BY AGENT
┌──────────────────┬───────┬──────────────────────────────────┐
│ Agent            │ Errors│ Most Common                      │
├──────────────────┼───────┼──────────────────────────────────┤
│ [agent]          │ [N]   │ [error type]                     │
│ [agent]          │ [N]   │ [error type]                     │
└──────────────────┴───────┴──────────────────────────────────┘

RECENT ERRORS (Last 10)
┌────────────────┬────────────────┬────────────┬──────────┐
│ Time           │ Story          │ Error      │ Resolved │
├────────────────┼────────────────┼────────────┼──────────┤
│ [timestamp]    │ STORY-XXX      │ [type]     │ [yes/no] │
└────────────────┴────────────────┴────────────┴──────────┘

ROOT CAUSE ANALYSIS
[Pattern identification and recommendations]

---

TREND ANALYSIS

On /metrics trends:

TREND ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PERIOD: Last 30 days

EXECUTION TREND
Week 1: ████████░░ 8 executions
Week 2: ██████████ 10 executions
Week 3: ████████████ 12 executions
Week 4: ███████████████ 15 executions
Trend: ↑ +87.5% growth

SUCCESS RATE TREND
Week 1: 91.2% ░░░░░░░░░░
Week 2: 92.5% ████░░░░░░
Week 3: 94.1% ████████░░
Week 4: 95.2% ██████████
Trend: ↑ +4.0% improvement

TOKEN EFFICIENCY TREND
Week 1: 52K tokens/exec
Week 2: 48K tokens/exec
Week 3: 45K tokens/exec
Week 4: 42K tokens/exec
Trend: ↓ -19.2% (improving)

WEEKLY COMPARISON
┌────────────────┬──────────┬──────────┬──────────┐
│ Metric         │ This Wk  │ Last Wk  │ Change   │
├────────────────┼──────────┼──────────┼──────────┤
│ Executions     │ [N]      │ [N]      │ [+/-X%]  │
│ Success Rate   │ [X]%     │ [X]%     │ [+/-X%]  │
│ Stories        │ [N]      │ [N]      │ [+/-X%]  │
│ Errors         │ [N]      │ [N]      │ [+/-X%]  │
│ Avg Tokens     │ [X]K     │ [X]K     │ [+/-X%]  │
└────────────────┴──────────┴──────────┴──────────┘

PROJECTIONS (Next 7 days)
Based on current trends:
├── Expected Executions: [N]
├── Expected Success Rate: [X]%
└── Expected Token Usage: [X]K

HEALTH INDICATORS
├── Execution Volume: [HEALTHY/WARNING/CRITICAL]
├── Success Rate: [HEALTHY/WARNING/CRITICAL]
├── Token Efficiency: [HEALTHY/WARNING/CRITICAL]
└── Error Rate: [HEALTHY/WARNING/CRITICAL]

---

EXPORT

On /metrics export [format]:

JSON Export

/metrics export json

Exporting metrics to: .claude/metrics/export_20260120.json
├── Summary data
├── Agent metrics
├── Story metrics
├── Error metrics
└── Trend data

Export complete: .claude/metrics/export_20260120.json

CSV Export

/metrics export csv

Exporting metrics to: .claude/metrics/export_20260120/
├── summary.csv
├── agents.csv
├── stories.csv
├── errors.csv
└── daily.csv

Export complete: .claude/metrics/export_20260120/

Markdown Report

/metrics export md

Generating report: .claude/metrics/report_20260120.md
├── Executive summary
├── Detailed metrics
├── Charts (ASCII)
├── Recommendations

Report generated: .claude/metrics/report_20260120.md

---

RESET

On /metrics reset:

⚠️ RESET METRICS

This will permanently delete all collected metrics.

Current metrics summary:
├── Executions: [N]
├── Stories: [N]
├── Days of data: [N]
└── Size: [X] KB

Type 'RESET' to confirm, or 'cancel' to abort:

After confirmation:

Metrics reset complete.

Backed up to: .claude/metrics/backup_20260120.json
New metrics file initialized.

---

METRICS FILE LOCATION

.claude/
├── metrics.json              # Current metrics
├── metrics/
│   ├── summary.json          # Aggregated summary
│   ├── daily/
│   │   └── YYYY-MM-DD.json   # Daily snapshots
│   ├── executions/
│   │   └── exec_*.json       # Per-execution records
│   ├── exports/
│   │   └── export_*.json     # Exported data
│   └── backups/
│       └── backup_*.json     # Reset backups

---

THRESHOLDS

Default thresholds for health indicators:

| Metric | Healthy | Warning | Critical | |--------|---------|---------|----------| | Success Rate | > 95% | 85-95% | 90% | 80-90% | 15% | | Recovery Rate | > 90% | 75-90% | 15% | CRITICAL | "Error rate critically high. Review root causes." | | Recovery rate 20% week-over-week | WARNING | "Token usage increasing. Review efficiency." | | 0 executions in 7+ days | INFO | "No recent activity. Metrics may be stale." |

Threshold Configuration

Thresholds can be overridden in .claude/metrics-config.json:

{
  "thresholds": {
    "success_rate": { "healthy": 95, "warning": 85, "critical": 75 },
    "agent_success": { "healthy": 90, "warning": 80, "critical": 70 },
    "error_rate": { "healthy": 5, "warning": 15, "critical": 25 },
    "recovery_rate": { "healthy": 90, "warning": 75, "critical": 60 }
  }
}

---

BAD vs GOOD Examples

BAD: Metrics dashboard with no context or actionability

/metrics

METRICS DASHBOARD
━━━━━━━━━━━━━━━━━━

Executions: 47
Success: 89%
Stories: 142
Tokens: 2.1M

Problem: Raw numbers without context. No trend direction. No comparison to thresholds. No recommendations. User cannot tell if 89% is good or bad, or whether things are improving or degrading.

GOOD: Metrics dashboard with trends, alerts, and recommendations

/metrics

METRICS DASHBOARD
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PROJECT: skillfoundry
PERIOD: All time (since 2026-01-15)

QUICK STATS
┌────────────────────────────────────────────────────────────────┐
│ Executions: 47  │  Success: 93.6%  │  Stories: 142  │ Tokens: 2.1M │
└────────────────────────────────────────────────────────────────┘

RECENT ACTIVITY (Last 7 days)
├── Executions: 12 (↑ +20% vs prior week)
├── Stories Completed: 38
├── Success Rate: 95.2% (↑ +1.6% — HEALTHY)
└── Avg Tokens/Execution: 42K (↓ -8% — improving)

TOP PERFORMING AGENTS
1. ruthless-coder: 97% success (34 calls)
2. ruthless-tester: 94% success (34 calls)
3. cold-architect: 92% success (34 calls)

ATTENTION NEEDED
⚠ gate-keeper: 78% success rate (below 80% threshold)
  → Most common failure: incomplete security checklist
  → Recommendation: Add security section to story template

Use /metrics [category] for detailed breakdowns.

---

REFLECTION PROTOCOL

Pre-Execution Reflection

Before generating metrics, answer:

• Is the metrics data file (metrics.json) present and non-empty?
• What time period is the user interested in?
• Are there enough data points for meaningful trends (need 7+ days)?
• Should I highlight any known data quality issues?

Post-Execution Reflection

After displaying metrics, evaluate:

• Did I provide context for every number (trend, threshold comparison)?
• Were recommendations specific and actionable?
• Did I identify the most important metric to focus on?
• Were calculations verified (no division by zero, no stale data)?

Self-Score (1-10)

| Dimension | Score | Criteria | |-----------|-------|----------| | Accuracy | [1-10] | Were all calculations correct? No math errors? | | Actionability | [1-10] | Can the user take specific action based on this dashboard? | | Completeness | [1-10] | Were all relevant metrics categories displayed? | | Clarity | [1-10] | Is the dashboard easy to read and understand? |

Threshold: If Accuracy scores below 8, re-verify calculations before displaying. If Actionability scores below 6, add specific recommendations.

---

ERROR HANDLING

| Error | Cause | Resolution | |-------|-------|------------| | Metrics file not found | No executions yet or file deleted | Display "No metrics collected yet. Run /go to start." | | Metrics file corrupted | Malformed JSON | Attempt recovery from daily backups; if none, reset | | Insufficient data for trends | Fewer than 7 days of data | Show raw numbers only, note trends unavailable | | Division by zero | No executions in period | Display "N/A" for rates, note no activity | | Export fails | Disk full or permission error | Report error, suggest checking disk space | | Stale data warning | No new data in 7+ days | Note data may not reflect current state |

---

INTEGRATION WITH OTHER AGENTS

| Agent | Interaction | |-------|------------| | /go | Primary data source — records execution lifecycle metrics | | /forge | Records forge pipeline metrics (per-phase timing) | | /anvil | Reports per-tier pass/fail rates | | /fixer | Reports auto-fix success rates and retry counts | | /status | Includes key metrics in project status dashboard | | /health | Uses metric thresholds as health indicators | | /cost | Token usage metrics feed into cost analysis | | /analytics | Deeper agent-level analytics complement metrics |

Peer Improvement Signals

• From /go: Execution completion events trigger metric recording
• From /anvil: Per-tier pass/fail data enriches quality metrics
• From /fixer: Auto-fix success rates indicate remediation effectiveness
• To /health: Provide health indicator data (success rate, error rate)
• To /status: Provide summary KPIs for project dashboard
• To /cost: Provide token usage data for cost projections

---

REMEMBER

> "Metrics are the mirror of your process. Look honestly."

> "Every number tells a story. Learn to read it."

> "Good metrics lead to good decisions."

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: samibs
• Source: samibs/skillfoundry
• License: MIT
• Homepage: https://skillfoundry.work

Install and usage instructions live in the source repository linked above.