SkillsAdd

steel-dev/skills

steel-session-debugging

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.

First seen Jun 4, 2026

Installation

$ npx skills add steel-dev/skills --skill steel-session-debugging
View on skills.sh ↗ GitHub repository ↗

Summary

  • 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.

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

agent-browser Shared topics
vercel-labs/agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, includ…

810.4K installs
azure-aigateway Shared topics
microsoft/azure-skills

Configure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: sem…

566.3K installs
azure-compute Shared topics
microsoft/azure-skills

Azure VM/VMSS router. WHEN: create / provision / deploy / spin-up VM, recommend VM size, compar…

510K installs
supabase-postgres-best-practices Shared topics
supabase/agent-skills

Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill …

391.6K installs
prisma-cli Shared topics
prisma/skills

Prisma ORM CLI commands reference covering init, generate, migrate, db, dev, complete, studio, …

267K installs
supabase Shared topics
supabase/agent-skills

Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge F…

263K installs

Also in this package

Other skills from steel-dev/skills.

npx skills add steel-dev/skills
steel-browser 482 steel-developer 319 steel-reliability 288 steel-skill-creator 264

Browse all from steel-dev/skills

More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Declared
Cursor Declared
Codex Declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Declared

Repository health

Stars 3
License MIT
Default branch main
Open issues 0
Status Active

Skill metadata

Parsed from SKILL.md frontmatter.

LicenseMIT
Compatibilityclaude-code,codex,cursor,opencode,pi
Declared agents claude-code cursor codex opencode
More metadata
owner
steel
category
debug
stage
beta

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 3,181 B
  • docs README.md 876 B
  • docs SUMMARY.md 485 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 293 installs

SKILL.md

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.