Skip to content
Get packs

Guide · Agent skill

How to use the Blocking-IO Guard agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

Blocking-IO Guard is an agent skill for the DeerFlow repository that helps you find backend Python code that could freeze the asyncio event loop, such as a slow file or network call run directly instead of offloaded to a thread. It then guides the agent to fix the code or protect it with a runtime regression test in tests/blocking_io/. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and how to check that its tests really catch regressions.

Blocking-IO Guardbytedance/deer-flow · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
  2. 2Confirm the requirements. Make sure Python with uv is installed, your DeerFlow checkout has origin/main, and the make targets detect-blocking-io and test-blocking-io are available.
  3. 3Commit your backend change. Commit the work first, because the Mode A scan only selects committed lines in base...HEAD.
  4. 4Ask for a blocking-IO check. Describe your backend change in plain language and ask for a blocking-IO check, or ask for a full-repo triage round.
  5. 5Route each finding. For each candidate, the agent chooses GUARD, FIX+ANCHOR, NO-ACTION or a RULE, and records the reason.
  6. 6Prove the test has teeth. Reintroduce the blocking call and confirm make test-blocking-io goes red, then restore the fix and confirm it goes green.

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file and supporting files that an AI coding agent can load when a task matches the skill's description. This skill, blocking-io-guard, is written for DeerFlow's Python backend.

When you change async backend code under app/, packages/harness/deerflow/, or scripts/, the skill makes the agent scan the change for blocking-IO candidates. Each candidate is then routed to one of several outcomes: fix the code, guard it with a regression test, or record why no action is needed. The skill also covers a repo-wide triage round when a maintainer wants a full sweep.

  • Mode A: scan only your own diff against origin/main before a pull request.
  • Mode B: run a full-repo triage round and work through findings by priority.
  • Every route ends with a test in tests/blocking_io/ that must fail when the blocking call returns and pass after the fix.

Install the Blocking-IO Guard skill

Download the skill's ZIP from this page and unzip it. Put the resulting folder in ~/.claude/skills/ to make it available across your projects, or in a project's .claude/skills/ folder to share it with that repository only.

If you use the Claude apps instead, upload the ZIP under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/.
  • Project install: unzip into the project's .claude/skills/ folder.
  • Claude apps: upload the ZIP under Settings → Capabilities → Skills.

Check the requirements before you run it

The skill needs Python with uv, because the scan runs via uv run --project backend. It also needs a git repository with origin/main available for the diff-based scan, the make targets detect-blocking-io and test-blocking-io in the DeerFlow repo, and the Blockbuster detector used by the tests/blocking_io/ suite.

The skill is specific to DeerFlow. Its paths, make targets and test templates will not match other projects.

  • Python with uv
  • A git repository with origin/main available
  • make targets detect-blocking-io and test-blocking-io in DeerFlow
  • The Blockbuster detector used by tests/blocking_io/
uv run --project backend python scripts/scan_changed_blocking_io.py --base origin/main

How to trigger the skill with natural requests

The skill loads when your request matches its description. You do not need to name a command. Ask in plain language about the kind of work you are doing, and mention the backend area or the review context.

Requests that fit well include changing backend Python under app/ or packages/harness/deerflow/, asking for a blocking-IO check before a PR, or asking for a triage round across the whole repo. The skill also applies when a reviewer or CI asks for blocking-IO coverage.

  • "I changed the upload handler in backend/app. Check whether it blocks the event loop and add a test if needed."
  • "Run a blocking-IO triage round on the whole backend and tell me what is HIGH priority."
  • "The reviewer asked for blocking-IO coverage on this change. Can you add an anchor?"

Walk through the workflow on a change

Step 0 runs the deterministic scan. Step 1 has the agent read the code around each candidate and choose a route. For code already offloaded with asyncio.to_thread, run_in_executor or an async client, the route is GUARD, which adds a test that locks the offload in place. For code on the loop that is not offloaded, the route is FIX+ANCHOR: move the call off the loop, re-scan, then add a test.

Step 5 is mandatory. Temporarily reintroduce the block, run make test-blocking-io and confirm it goes red. Then restore the fix and confirm it goes green. A real block that stays green means the detector has no rule for that primitive, which is a separate RULE route.

  • Finding fixed: the re-scan no longer lists the candidate.
  • Anchor red on the reintroduced block, green on the fix.
  • PR note: candidates found, each disposition, re-scan result, and red-to-green evidence.
cd backend && make test-blocking-io

Safety notes: scripts and network

The skill runs scripts: the scan script scripts/scan_changed_blocking_io.py and the make targets. It does not use the network, according to its requirements. Review the scripts before running them in an unfamiliar checkout, as you would with any agent-run command.

The static scan is a review ordering, not proof of a bug. Only the runtime test proves that the event loop is protected. Also note that the scanner only follows reachability within the same file, so a new async caller of a sync helper in another file can be missed; the skill tells the agent to check such helpers manually.

  • Runs scripts: yes. Uses network: no.
  • Static findings are a priority order, not confirmed bugs.
  • Cross-file helpers need a manual check with codegraph or git grep.

Tips for getting good results

Commit your work before the scan, because the diff is base...HEAD and uncommitted lines are not selected. Keep one root cause per pull request while any HIGH finding remains, and ship a new Blockbuster rule alone in its own commit.

When the agent writes an anchor, check that it drives the real production async entry point and does not wrap the blocking call in a test-only thread. The examples in the references are filesystem-based, but the same rules apply to HTTP, subprocess and sleep categories.

  • Commit before running the Mode A scan.
  • Fix one root cause per PR while HIGH findings remain.
  • Do not add a test-only to_thread wrapper; it hides the blocking surface.
  • Use the red-to-green check to confirm the test has teeth.

What people use it for

  • Reviewing a pull request that moves a file or network call in app/ and checking whether it runs on the event loop.
  • Guarding an existing offloaded call with a test so a later edit cannot move it back onto the loop.
  • Running a repo-wide triage round with make detect-blocking-io and working through HIGH findings first.
  • Answering a reviewer who asks for evidence that a blocking-IO regression test really catches the problem.

Frequently asked questions

Is the blocking-io-guard skill free to use?

The source provided does not state a licence for this skill. The DeerFlow project it belongs to is listed under the MIT licence, so check the repository's licence files for the exact terms before you reuse the skill elsewhere.

What do I need to run blocking-io-guard?

You need Python with uv, a git repository with origin/main available, the make targets detect-blocking-io and test-blocking-io in the DeerFlow repo, and the Blockbuster detector used by the tests/blocking_io/ suite. The skill is written for DeerFlow and does not cover other projects.

Where do I install an agent skill like this?

Unzip the downloaded ZIP into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one repository. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

Does the skill use the internet?

According to its requirements, the skill does not use the network, but it does run scripts, including scan_changed_blocking_io.py and the make targets. Review those scripts before running them in an unfamiliar checkout.

Why does the scan say a finding exists but the code seems fine?

The static scan is a review ordering, not proof of a bug. The agent judges each candidate and may route it to NO-ACTION with a recorded reason, such as a scanner false positive or startup-only code.

Can the scanner miss a blocking call?

Yes. Reachability is same-file only, so a new async caller of a sync helper defined in another file may not be flagged. The skill tells the agent to check such helpers with codegraph or git grep before stopping.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use blocking-io-guard if you contribute to or review DeerFlow's Python backend and want async changes under app/, packages/harness/deerflow/ or scripts/ protected by runtime tests. Pick something else if your project is not DeerFlow, does not use its tests/blocking_io/ suite and Blockbuster gate, or if you work on frontend or non-Python code, which this skill does not cover.

Download the skill