debug-mode
运行迭代的、假设驱动的“调试模式”循环,使用目标检测和日志捕获来诊断和修复错误。当用户需要交互式调试循环时,当您需要通过添加的调试语句快速缩小故障范围时,或者当您需要一种轻量级方法来集中重现运行的日志时(通过“agent-skills debug”服务器+ SSE UI),请使用。
📖 中文导读:运行迭代的、假设驱动的“调试模式”循环,使用目标检测和日志捕获来诊断和修复错误。当用户需要交互式调试循环时,当您需要通过添加的调试语句快速缩小故障范围时,或者当您需要一种轻量级方法来集中重现运行的日志时(通过“agent-skills debug”服务器+ SSE UI),请使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: debug-mode
description: Run an iterative, hypothesis-driven “debug mode” loop to diagnose and fix a bug using targeted instrumentation and log capture. Use when the user wants an interactive debug loop, when you need to quickly narrow a failure via added debug statements, or when you need a lightweight way to centralize logs from a repro run (via agent-skills debug server + SSE UI).
Debug Mode
Run a tight debug loop: form a hypothesis, instrument the smallest surface area, capture evidence, update the hypothesis, and repeat until you can ship a fix with a regression test (or a clear root-cause explanation).
This skill assumes you can add temporary debug statements and that you can ask the user to run a repro while a local log capture server is running.
Quick start
- Start the log capture server:
agent-skills debug
- Ask the user to reproduce while sending logs to the server (pick a method):
agent-skills debug send …curl -X POST … /v1/logs
- Use the captured evidence to pick the next instrumentation point and repeat.
Reference: skills/debug-mode/references/debug-server.md.
Workflow (debug loop)
Establish the repro and success criteria.
- Ask for exact commands/inputs and the expected vs actual outcome.
- Freeze variables: versions, env, config, dataset, feature flags.
- If the bug is flaky, ask for frequency and a “best repro” loop.
Form a falsifiable hypothesis.
- Phrase it as: “If X is happening, we should observe Y at location Z.”
- Prefer hypotheses that narrow the search space (not “something is wrong”).
Instrument minimally.
- Add logs at decision boundaries, not every line.
- Log identifiers and invariants (IDs, counts, state machine states), not entire blobs.
- Include correlation keys (
requestId,userId,jobId, etc.).
Capture and review evidence.
- Use the debug server UI and/or the NDJSON file as the shared artifact.
- Summarize the evidence in a small table: observation → supports/refutes → next step.
Iterate until root cause is isolated.
- Move instrumentation “upstream” or “downstream” based on what you learned.
- Delete/undo misleading logs; keep only the ones that pay rent.
Fix + lock it in.
- Implement the smallest safe fix.
- Add a regression test or a runnable repro script.
- Remove or downgrade temporary debug statements.
Notes for using agent-skills debug
- Default auth is a random token printed at startup.
- By default, events are appended as NDJSON to
.agent-skills/debug.ndjson(disable with--out=). - Use headers for ingestion where possible; use
?token=mainly for the browser UI. - Prefer structured JSON logs with stable keys over freeform text.