mcpField
S
steel-session-debugging

steel-session-debugging

github.com/steel-devDevelopment4445 installsUpdated 21w ago
Repository

About steel-session-debugging

steel-session-debugging is a skill for diagnosing failed Steel sessions and deciding what to change next. It organizes logs and traces into an evidence-based timeline, and hands reliability-related issues to steel-reliability.

Key features

  1. 01Collect session metadata, logs, and traces
  2. 02Redact sensitive debugging artifacts
  3. 03Build an event timeline
  4. 04Classify failures and diagnose causes
  5. 05Suggest verification steps and handoffs

Use cases

  1. 01Investigate a failed Steel browser session
  2. 02Organize logs and request-failure evidence
  3. 03Verify a proposed diagnostic fix
  4. 04Identify issues for steel-reliability

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/steel-dev/skills --skill steel-session-debugging

After installing, type/steel-session-debuggingin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
evals/
evals.json
references/
agent-traces.md
failure-taxonomy.md
investigation-workflow.md
log-event-types.md
network-forensics.md
reliability-handoff.md
replay-and-screenshots.md
scripts/
collect-session-debug.mjs
redact-session-debug.mjs
summarize-session-debug.mjs

Details

From the project README

Steel Session Debugging

Skill Boundary

Use this skill to explain what happened in a failed Steel session and what to change next. Start from evidence, not guesses.

Do not use this skill as the primary place for bot-detection mitigation, proxy strategy, CAPTCHA strategy, login reputation, or retry policy. If the evidence points there, collect enough proof and hand off to steel-reliability.

Setup Check

  1. Confirm the user provided a Steel session ID or enough context to identify one.
  2. Run steel doctor --preflight if CLI auth or API access is uncertain.
  3. Prefer Steel CLI diagnostics before raw API calls.
  4. Create local artifacts under .steel-debug/; do not paste raw logs into chat unless the user asks.

Investigation Workflow

  1. Collect session metadata, browser logs, raw agent logs, semantic agent traces, and viewer/replay links.
  2. Redact cookies, bearer tokens, API keys, passwords, form values, and obvious PII before summarizing.
  3. Build a timeline: session creation, navigations, actions, waits, console errors, failed requests, CAPTCHA/proxy signals, and final state.
  4. Classify the failure using the taxonomy in references/failure-taxonomy.md.
  5. Produce an evidence-backed diagnosis with a smallest useful verification step.
  6. If the fix involves bot detection, proxy, CAPTCHA, identity, pacing, or login persistence, route to steel-reliability.

Output Format

Diagnosis:
- What happened:
- Most likely cause:
- Evidence:
- What to change:
- Verification step:
- Confidence:

Useful Commands

steel --json sessions get <session-id>
steel --json sessions logs <session-id>
steel --json sessions agent-logs <session-id>
steel --json sessions traces <session-id>
node scripts/collect-session-debug.mjs <session-id>
node scripts/redact-session-debug.mjs .steel-debug/<session-id>/bundle.json
node scripts/summarize-session-debug.mjs .steel-debug/<session-id>/redacted-bundle.json

References

  • references/investigation-workflow.md: detailed collection and timeline process.
  • references/log-event-types.md: how to separate metadata, browser logs, raw agent logs, and traces.
  • references/agent-traces.md: how to read semantic agent trace events.
  • references/network-forensics.md: request failures, redirects, and blocked-page evidence.
  • references/replay-and-screenshots.md: viewer, player, HLS, and screenshot usage.
  • references/failure-taxonomy.md: standard failure classes.
  • references/reliability-handoff.md: when to load steel-reliability.

Comments

Markdown supported