Claude Skill

session-scan

Compute metrics for Claude Code sessions. Discovers via ccrider, filters trivial, computes friction/opportunity/fingerprint scores. Use for broad session triage.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download oliver-kriska-claude-elixir-phoenix-.claude_skills_session-scan-9767a82.zip · 20 KB

Install

skills CLI npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/.claude/skills/session-scan
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
Git git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Session Scan (Tier 1)

Compute deterministic metrics for sessions discovered via ccrider MCP.

STOP — Read Before Executing

NEVER call mcp__ccrider__get_session_messages in main context. Each response is 5-50KB of JSON. Fetching N sessions directly = context crash.

You MUST delegate all scoring to subagents. The main context only does: discovery, deduplication, subagent spawning, and result collection.

Requirements

Requires ccrider MCP. If not available:

ccrider MCP is required. See: https://github.com/neilberkman/ccrider

Usage

/session-scan                         # Last 7 days, up to 50 sessions
/session-scan --since 2026-02-01      # Since specific date
/session-scan --project enaia         # Filter by project name
/session-scan --limit 20              # Cap session count
/session-scan --list                  # Discovery only, no scoring
/session-scan --rescan                # Recompute already-scanned sessions

What Main Context Does

1. Parse Arguments

Extract from $ARGUMENTS:

  • --since DATE: ISO date filter (default: 7 days ago)
  • --project NAME: Filter by project path substring
  • --limit N: Max sessions to process (default: 50)
  • --list: Discovery only — show table, skip scoring
  • --rescan: Recompute metrics for already-scanned sessions

2. Discover Sessions (safe — response is ~1KB)

mcp__ccrider__list_recent_sessions(limit: N, project: PROJECT, after_date: SINCE)

Filter out sessions with < 10 messages. If --list: show table and stop.

3. Deduplicate

Read .claude/session-metrics/metrics.jsonl (if exists). Skip sessions already scanned unless --rescan flag is set. Report: "N new sessions to scan (M already in ledger)"

4. Resolve Scorer Path

Glob: **/session-scan/references/compute-metrics.py

Store as SCORER_PATH (absolute). PROJECT_ROOT = current working directory.

5. Spawn ONE Subagent Per Session

DO NOT fetch messages yourself. DO NOT run Python yourself. You MUST use the Task tool to spawn subagents.

For EACH unscanned session, spawn a haiku subagent using this template:

Task(subagent_type="general-purpose", model="haiku", mode="bypassPermissions", prompt="""
Score one Claude Code session. Steps:

1. Fetch messages:
   mcp__ccrider__get_session_messages(session_id: "{SESSION_ID}", last_n: 200)

2. Write the full tool result (messages JSON) to:
   {PROJECT_ROOT}/.claude/session-metrics/_tmp_{SHORT_ID}.json

3. Run scorer and capture result in ONE Bash command:
   python3 {SCORER_PATH} {PROJECT_ROOT}/.claude/session-metrics/_tmp_{SHORT_ID}.json --session-id {SESSION_ID} --project {PROJECT_NAME} > {PROJECT_ROOT}/.claude/session-metrics/_result_{SHORT_ID}.json && rm {PROJECT_ROOT}/.claude/session-metrics/_tmp_{SHORT_ID}.json

4. Report back: "Scored {SHORT_ID}: friction=X.XX fingerprint=Y"

If ccrider fails, report the error and exit.
""")

Spawn ALL subagents in parallel. Wait for all to complete.

6. Collect Results

for f in .claude/session-metrics/_result_*.json; do
  cat "$f" >> .claude/session-metrics/metrics.jsonl
  rm "$f"
done

7. Display Results

Show summary table sorted by friction (descending):

| ID       | Project | Date       | Type        | Friction | Opportunity | Tier2? |
|----------|---------|------------|-------------|----------|-------------|--------|
| ffa155ee | enaia   | 2026-02-18 | bug-fix     | 0.42     | 0.65        | Yes    |
| 90a74843 | wedding | 2026-02-17 | feature     | 0.15     | 0.20        | No     |

If Tier 2 eligible: suggest /session-deep-dive --from-scan.

8. Update Scan Metadata

Write .claude/session-metrics/latest-scan.json:

{
  "scanned_at": "2026-02-20T14:30:00Z",
  "sessions_discovered": 25,
  "sessions_scanned": 18,
  "sessions_skipped": 7,
  "tier2_eligible": 5
}

Scoring Reference

See references/scoring-guide.md for full algorithm documentation.

  • Friction Score (0-1): Weighted signals, sigmoid-normalized
  • Fingerprint: Rule-based classifier (6 types)
  • Plugin Opportunity (0-1): Missed /phx: commands
  • Tier 2 Eligible: friction > 0.35 OR opportunity > 0.5 OR plugin used OR msgs > 50

Iron Laws

  1. NEVER call get_session_messages in main context — WILL crash context
  2. ONE subagent per session — each fetches exactly ONE session
  3. mode="bypassPermissions" on every Task — subagents need Write+Bash
  4. Absolute paths in subagent prompts — subagents don't inherit context
  5. Result files, not direct append — avoid jsonl race conditions
  6. NEVER modify existing metrics.jsonl entries — append-only ledger
  7. ALWAYS delete temp and result files after processing
Files (claude-elixir-phoenix)
  • references
    • compute-metrics.py 66.5 KB
      Loading…
    • scoring-guide.md 4.8 KB
      Loading…
  • SKILL.md 5 KB
    ---
    name: session-scan
    description: Compute metrics for Claude Code sessions. Discovers via ccrider, filters trivial, computes friction/opportunity/fingerprint scores. Use for broad session triage.
    argument-hint: "[--since DATE] [--project NAME] [--limit N] [--list] [--rescan]"
    disable-model-invocation: true
    ---
    
    # Session Scan (Tier 1)
    
    Compute deterministic metrics for sessions discovered via ccrider MCP.
    
    ## STOP — Read Before Executing
    
    **NEVER call `mcp__ccrider__get_session_messages` in main context.**
    Each response is 5-50KB of JSON. Fetching N sessions directly = context crash.
    
    **You MUST delegate all scoring to subagents.** The main context only does:
    discovery, deduplication, subagent spawning, and result collection.
    
    ## Requirements
    
    Requires **ccrider MCP**. If not available:
    
    > ccrider MCP is required. See: <https://github.com/neilberkman/ccrider>
    
    ## Usage
    
    ```
    /session-scan                         # Last 7 days, up to 50 sessions
    /session-scan --since 2026-02-01      # Since specific date
    /session-scan --project enaia         # Filter by project name
    /session-scan --limit 20              # Cap session count
    /session-scan --list                  # Discovery only, no scoring
    /session-scan --rescan                # Recompute already-scanned sessions
    ```
    
    ## What Main Context Does
    
    ### 1. Parse Arguments
    
    Extract from `$ARGUMENTS`:
    
    - **`--since DATE`**: ISO date filter (default: 7 days ago)
    - **`--project NAME`**: Filter by project path substring
    - **`--limit N`**: Max sessions to process (default: 50)
    - **`--list`**: Discovery only — show table, skip scoring
    - **`--rescan`**: Recompute metrics for already-scanned sessions
    
    ### 2. Discover Sessions (safe — response is ~1KB)
    
    ```
    mcp__ccrider__list_recent_sessions(limit: N, project: PROJECT, after_date: SINCE)
    ```
    
    Filter out sessions with < 10 messages. If `--list`: show table and stop.
    
    ### 3. Deduplicate
    
    Read `.claude/session-metrics/metrics.jsonl` (if exists).
    Skip sessions already scanned unless `--rescan` flag is set.
    Report: "N new sessions to scan (M already in ledger)"
    
    ### 4. Resolve Scorer Path
    
    ```
    Glob: **/session-scan/references/compute-metrics.py
    ```
    
    Store as `SCORER_PATH` (absolute). `PROJECT_ROOT` = current working directory.
    
    ### 5. Spawn ONE Subagent Per Session
    
    **DO NOT fetch messages yourself. DO NOT run Python yourself.**
    **You MUST use the Task tool to spawn subagents.**
    
    For EACH unscanned session, spawn a haiku subagent using this template:
    
    ```
    Task(subagent_type="general-purpose", model="haiku", mode="bypassPermissions", prompt="""
    Score one Claude Code session. Steps:
    
    1. Fetch messages:
       mcp__ccrider__get_session_messages(session_id: "{SESSION_ID}", last_n: 200)
    
    2. Write the full tool result (messages JSON) to:
       {PROJECT_ROOT}/.claude/session-metrics/_tmp_{SHORT_ID}.json
    
    3. Run scorer and capture result in ONE Bash command:
       python3 {SCORER_PATH} {PROJECT_ROOT}/.claude/session-metrics/_tmp_{SHORT_ID}.json --session-id {SESSION_ID} --project {PROJECT_NAME} > {PROJECT_ROOT}/.claude/session-metrics/_result_{SHORT_ID}.json && rm {PROJECT_ROOT}/.claude/session-metrics/_tmp_{SHORT_ID}.json
    
    4. Report back: "Scored {SHORT_ID}: friction=X.XX fingerprint=Y"
    
    If ccrider fails, report the error and exit.
    """)
    ```
    
    **Spawn ALL subagents in parallel.** Wait for all to complete.
    
    ### 6. Collect Results
    
    ```bash
    for f in .claude/session-metrics/_result_*.json; do
      cat "$f" >> .claude/session-metrics/metrics.jsonl
      rm "$f"
    done
    ```
    
    ### 7. Display Results
    
    Show summary table sorted by friction (descending):
    
    ```
    | ID       | Project | Date       | Type        | Friction | Opportunity | Tier2? |
    |----------|---------|------------|-------------|----------|-------------|--------|
    | ffa155ee | enaia   | 2026-02-18 | bug-fix     | 0.42     | 0.65        | Yes    |
    | 90a74843 | wedding | 2026-02-17 | feature     | 0.15     | 0.20        | No     |
    ```
    
    If Tier 2 eligible: suggest `/session-deep-dive --from-scan`.
    
    ### 8. Update Scan Metadata
    
    Write `.claude/session-metrics/latest-scan.json`:
    
    ```json
    {
      "scanned_at": "2026-02-20T14:30:00Z",
      "sessions_discovered": 25,
      "sessions_scanned": 18,
      "sessions_skipped": 7,
      "tier2_eligible": 5
    }
    ```
    
    ## Scoring Reference
    
    See `references/scoring-guide.md` for full algorithm documentation.
    
    - **Friction Score** (0-1): Weighted signals, sigmoid-normalized
    - **Fingerprint**: Rule-based classifier (6 types)
    - **Plugin Opportunity** (0-1): Missed `/phx:` commands
    - **Tier 2 Eligible**: friction > 0.35 OR opportunity > 0.5 OR plugin used OR msgs > 50
    
    ## Iron Laws
    
    1. **NEVER call `get_session_messages` in main context** — WILL crash context
    2. **ONE subagent per session** — each fetches exactly ONE session
    3. **`mode="bypassPermissions"` on every Task** — subagents need Write+Bash
    4. **Absolute paths in subagent prompts** — subagents don't inherit context
    5. **Result files, not direct append** — avoid jsonl race conditions
    6. **NEVER modify existing metrics.jsonl entries** — append-only ledger
    7. **ALWAYS delete temp and result files** after processing
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.