Skip to content
Get packs

Guide · Agent skill

How to use the DeerFlow Smoke Test agent skill (smoke-test)

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

The DeerFlow Smoke Test skill (skill name: smoke-test) is an agent skill that gives your AI agent a step-by-step checklist for confirming that a DeerFlow project works end to end. This guide explains what agent skills are, how to install this one, how to ask for it in plain language, and what it needs before you run it. By the end you will be able to run a full check of a fresh or updated DeerFlow install and read the report it produces.

DeerFlow Smoke Testbytedance/deer-flow · MIT

Quick start

  1. 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Prepare your environment. Confirm you are in the DeerFlow project root and that git, Node.js 22+, pnpm, uv, nginx (local mode) or Docker and Docker Compose (Docker mode), and lsof are available. Add a model API key such as OPENAI_API_KEY to .env.
  3. 3Ask for the smoke test. Tell the agent in plain language, for example 'run smoke test' or 'verify installation'. Mention Docker if you want that mode.
  4. 4Let the agent pull and deploy. The agent pulls the latest code with git pull origin main, prepares config and starts services in local or Docker mode, waiting 90-120 seconds for local startup or 60 seconds for Docker.
  5. 5Review health checks. The agent checks http://localhost:2026, the /health endpoint, the /api/langgraph/* route and key /workspace routes via frontend_check.sh.
  6. 6Read the report. Review the report built from the matching template, including the overall conclusion, per-case results and frontend route results.

What the smoke-test skill makes the agent do

An agent skill is a folder of instructions and scripts that an AI agent can load when a task matches it. This skill covers verification of a DeerFlow deployment rather than using DeerFlow for research tasks.

The workflow runs in phases: it updates the code from git, checks that the machine has the right tools, prepares configuration, starts the app either locally or in Docker, checks that the web page, API and key routes respond, and then writes a test report from a template. Scripts are provided for each step, so the agent runs the checks instead of guessing their results.

  • Pull the latest code from git (git pull origin main).
  • Check required tools and ports for local or Docker mode.
  • Start services and wait for them to come up.
  • Verify the frontend page, the /health endpoint and the /api/langgraph/* route.
  • Check key /workspace routes with frontend_check.sh.
  • Write a final report using the matching template.

Install the smoke-test skill in Claude

Download the ZIP for this skill from this page. You can install it in one of three ways, depending on how you use Claude.

For a personal setup, unzip the folder into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

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

Choose local or Docker deployment mode

The skill supports two modes. Local installation mode runs all services directly on the machine and is the recommended default. Docker mode runs all services inside Docker containers.

If you explicitly ask for Docker, the agent uses Docker. If network problems occur, such as slow image pulls, the skill switches to local mode. Local mode also avoids those network issues in the first place, so it is the default whenever possible.

  • Local mode: recommended, especially on networks with problems.
  • Docker mode: used when you ask for it.
  • Automatic fallback: the agent moves to local mode if image pulls are slow.

Trigger the skill with natural requests

You do not need special syntax. Describe what you want in ordinary words. The skill is meant to activate on requests like the ones below, or similar wording about checking a deployment.

Be specific about your situation when it helps, for example saying you want Docker mode or that you have just cloned the project on a new server. The agent will still ask before risky steps such as overwriting configuration.

  • "Run smoke test"
  • "Smoke test deployment"
  • "Verify installation"
  • "Test service availability"
  • "Run an end-to-end test on my DeerFlow install using Docker"

Understand the checks and the commands involved

Local mode checks Node.js 22+, pnpm, uv, nginx and that ports 2026, 3000 and 8001 are free. Docker mode checks Docker, the Docker daemon and Docker Compose, and that port 2026 is free. Both modes then prepare configuration and start services.

Configuration preparation generates config.yaml with make config if it is missing, or checks for upgrades with make config-upgrade. The skill also checks the .env file for model API keys such as OPENAI_API_KEY.

  • Local: make check, make install, make start (optional: make setup-sandbox)
  • Docker: make docker-init, make up
  • Health: http://localhost:2026, http://localhost:2026/health, /api/langgraph/* routes
make check make install make start

Read the test report and known warnings

The final report must use the template that matches the mode you ran: templates/report.local.template.md or templates/report.docker.template.md. It includes an overall pass or fail conclusion, a result for each key test case, and explicit frontend route results.

The skill lists two warnings that can appear in logs without blocking a pass. Feishu/Lark SSL errors can be ignored if that channel is not enabled. Warnings about missing checkpointer methods such as adelete_for_runs or aprune are also listed as acceptable.

  • Feishu/Lark SSL errors in Gateway logs can be ignored if that channel is disabled.
  • Missing custom checkpointer method warnings (adelete_for_runs, aprune) are listed as non-blocking.

Safety notes before you run it

This skill runs scripts and uses the network. The workflow changes the project directory and launches processes. It can run git pulls, package installs and make targets that start and restart services, and it may modify config.yaml and .env files.

Do not run it on production servers with live data, or on machines where you do not want automatic git pulls, package installs or started services. The skill is for testing a deployment, not for running research tasks. The source says the agent should ask for confirmation before risky operations such as overwriting config, and that git conflicts should be handled by committing or stashing first.

  • Do not use on production servers with live data.
  • Expect git pulls, package installs and services to start or restart.
  • Back up or commit local changes before the pull step.
  • Remember that a model API key such as OPENAI_API_KEY in .env is needed for the app to work fully.

What people use it for

  • Confirming a fresh clone of DeerFlow runs on a new laptop or server.
  • Repeating the same verification before a release or after a deployment.
  • Checking that the web page, API and key routes still respond after pulling new code.
  • Producing a written test report for a team that tests DeerFlow on new machines.

Frequently asked questions

Is the DeerFlow smoke-test skill free?

The skill is published under the MIT licence, as stated for the bytedance/deer-flow project. You still need the tools it depends on, such as git, Node.js, Docker where used, and a model API key for full app functionality.

What do I need to run the smoke-test skill?

You need git, Node.js 22 or newer, pnpm, uv, nginx for local mode, Docker and Docker Compose for Docker mode, lsof for port checks, network access, and a model API key such as OPENAI_API_KEY in the .env file for the app to work fully.

Where do I put the smoke-test skill folder?

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

Is this skill safe to run on my computer?

It runs scripts and uses the network, and it can run git pulls, package installs and make targets that start and restart services. It may also modify config.yaml and .env. Avoid production servers with live data and use a machine where those changes are acceptable.

What should I do if git pull fails with a merge conflict?

The troubleshooting guide lists three options: commit your local changes and pull, stash them and pull, or discard them with git reset --hard HEAD. The last option removes local edits, so use it only when you are sure.

Should I pick Docker or local mode?

Pick local mode if you want the default recommended path, especially on networks where Docker image pulls are slow. Choose Docker only when you specifically want containers, since the skill switches to local mode when network issues occur.

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 this skill if you are a developer or maintainer who wants a repeatable check that a fresh, updated or newly deployed DeerFlow install runs end to end. Pick something else if you only want to use DeerFlow for tasks, or if you need to run checks on a production server with live data, since this workflow starts and restarts services and can change project files.

Download the skill