Skip to content
Get packs

Blocking-IO Guard

Adds and verifies runtime tests that catch blocking I/O on DeerFlow's async backend code

Source Download skill
Repository
bytedance/deer-flow
Stars
84,876
Licence
MIT
Files
4 files

What it does

When a developer changes DeerFlow's Python backend, this skill guides the agent to scan the change for code that could freeze the async event loop (for example, a slow file or network call run directly instead of offloaded to a thread). It then routes each finding: fix the code, guard it with a regression test in tests/blocking_io/, or record why no action is needed. The test must be shown to fail when the blocking call is reintroduced and pass after the fix, so the CI gate actually protects the code.

Great for

  • Contributors to the DeerFlow backend who change async Python code under app/, packages/harness/deerflow/, or scripts/
  • Maintainers running a repo-wide blocking-I/O triage round
  • Reviewers who want evidence that a blocking-I/O regression test really catches the problem

Skip it if

  • Projects that are not DeerFlow or do not use its tests/blocking_io/ suite and Blockbuster gate, since the paths, make targets and templates are specific to this repo
  • Frontend or non-Python changes, which the skill does not cover
  • Teams expecting the static scan to prove there are no bugs: its output is a review ordering, and only the runtime test proves protection

Try asking

  • “Check whether my changes to backend/app/ add any blocking I/O on the async event loop before I open a PR”
  • “Run a full-repo blocking-I/O triage and work through the HIGH priority findings”
  • “Write a regression test that proves the cleanup path in this file no longer blocks the event loop”
  • “Explain in my PR which blocking-I/O candidates I found and how I dispositioned each one”
Step-by-step guide: how to use Blocking-IO GuardInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 4 original files, the MIT licence and an attribution note.

    blocking-io-guard.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip blocking-io-guard.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip blocking-io-guard.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Commit your work before running the scan, because it only inspects committed lines in the diff against origin/main
  • Read references/good-anchor-rules.md before writing a new anchor, and mock only the external boundary, not the offload under test
  • Always run the teeth check (fail on reintroduced block, pass on fix) before committing the anchor

What's inside

  • references/good-anchor-rules.md
  • references/sop-skeleton.md
  • SKILL.md
  • templates/anchor.template.py

Redistributed unmodified from bytedance/deer-flow under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.