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
- Confirm the user provided a Steel session ID or enough context to identify one.
- Run
steel doctor --preflight if CLI auth or API access is uncertain.
- Prefer Steel CLI diagnostics before raw API calls.
- Create local artifacts under
.steel-debug/; do not paste raw logs into chat unless the user asks.
Investigation Workflow
- Collect session metadata, browser logs, raw agent logs, semantic agent traces, and viewer/replay links.
- Redact cookies, bearer tokens, API keys, passwords, form values, and obvious PII before summarizing.
- Build a timeline: session creation, navigations, actions, waits, console errors, failed requests, CAPTCHA/proxy signals, and final state.
- Classify the failure using the taxonomy in
references/failure-taxonomy.md.
- Produce an evidence-backed diagnosis with a smallest useful verification step.
- 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.
1---2name: steel-session-debugging3description: Use this skill when the user provides a failed Steel session ID, failed automation run, timeout, browser error, blocked page, or unexpected result and wants evidence-backed diagnosis from session metadata, browser logs, raw agent logs, semantic traces, replay links, screenshots, network failures, or errors. Do not use for first-pass bot mitigation; collect evidence here, then hand off to steel-reliability for proxy, CAPTCHA, identity, or anti-bot fixes.4license: MIT5---67# Steel Session Debugging89## Skill Boundary1011Use this skill to explain what happened in a failed Steel session and what to change next. Start from evidence, not guesses.1213Do 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`.1415## Setup Check16171. Confirm the user provided a Steel session ID or enough context to identify one.182. Run `steel doctor --preflight` if CLI auth or API access is uncertain.193. Prefer Steel CLI diagnostics before raw API calls.204. Create local artifacts under `.steel-debug/`; do not paste raw logs into chat unless the user asks.2122## Investigation Workflow23241. Collect session metadata, browser logs, raw agent logs, semantic agent traces, and viewer/replay links.252. Redact cookies, bearer tokens, API keys, passwords, form values, and obvious PII before summarizing.263. Build a timeline: session creation, navigations, actions, waits, console errors, failed requests, CAPTCHA/proxy signals, and final state.274. Classify the failure using the taxonomy in `references/failure-taxonomy.md`.285. Produce an evidence-backed diagnosis with a smallest useful verification step.296. If the fix involves bot detection, proxy, CAPTCHA, identity, pacing, or login persistence, route to `steel-reliability`.3031## Output Format3233```text34Diagnosis:35- What happened:36- Most likely cause:37- Evidence:38- What to change:39- Verification step:40- Confidence:41```4243## Useful Commands4445```bash46steel --json sessions get <session-id>47steel --json sessions logs <session-id>48steel --json sessions agent-logs <session-id>49steel --json sessions traces <session-id>50node scripts/collect-session-debug.mjs <session-id>51node scripts/redact-session-debug.mjs .steel-debug/<session-id>/bundle.json52node scripts/summarize-session-debug.mjs .steel-debug/<session-id>/redacted-bundle.json53```5455## References5657- `references/investigation-workflow.md`: detailed collection and timeline process.58- `references/log-event-types.md`: how to separate metadata, browser logs, raw agent logs, and traces.59- `references/agent-traces.md`: how to read semantic agent trace events.60- `references/network-forensics.md`: request failures, redirects, and blocked-page evidence.61- `references/replay-and-screenshots.md`: viewer, player, HLS, and screenshot usage.62- `references/failure-taxonomy.md`: standard failure classes.63- `references/reliability-handoff.md`: when to load `steel-reliability`.
steel-dev