A skill your agent uses when 程序出现错误、异常、崩溃,或行为与预期不符,或测试失败,或无法定位问题根因时。触发场景:调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了。

MITAuto-check passedDevelopment

Install Debug Expert

skills CLI
$ npx skills add ProgrammerAnthony/Expert-Coding-Harness --skill debug-expert -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ProgrammerAnthony/Expert-Coding-Harness debug-expert --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ProgrammerAnthony/Expert-Coding-Harness.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/debug-expert .claude/skills/debug-expert && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
debug-expert
GitHub stars
235
Token cost
~986 tokens
SKILL.md length
140 words
Files
5 (incl. references)
Skills in repo
23
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses when 程序出现错误、异常、崩溃,或行为与预期不符,或测试失败,或无法定位问题根因时。触发场景:调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了。

  • Works in 3 steps: 制定修复方案(不要第一个想到的方案就是最好的) → 实施修复 → 验证清单(完成前强制检查,不得跳过)
  • 程序出现错误、异常、崩溃,或行为与预期不符,或测试失败,或无法定位问题根因时。触发场景:调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了
  • SKILL.md covers Inputs / Outputs / Gates /…, 调试工作流, 特殊问题处理 and 红旗警告:当你想跳过流程时, plus 1 more section
  • Calls docker and pip

What it does

Debug Expert is an agent skill from ProgrammerAnthony/Expert-Coding-Harness. Use when 程序出现错误、异常、崩溃,或行为与预期不符,或测试失败,或无法定位问题根因时。触发场景:调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了。

Its SKILL.md is about 990 tokens, which your agent loads only when the skill is triggered. The skill folder holds 5 other files, including reference files (for example `README.md`, `references/debug-log-template.md` and `references/debugging-patterns.md`).

It sits in Development. The repository describes itself as: 生产级 AI Agent 技能集,辅助AI Harness应用于企业开发,覆盖代码审查、代码安全审计、TDD、需求工程、实施计划与子代理编排、架构设计、调试、前端开发与技能创建全流程。 The licence is MIT.

When your agent uses it

  • 程序出现错误、异常、崩溃,或行为与预期不符,或测试失败,或无法定位问题根因时。触发场景:调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了

Example prompts

  • “/debug-expert”

Requirements

  • Python 3
  • Docker

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. 制定修复方案(不要第一个想到的方案就是最好的)
  2. 实施修复
  3. 验证清单(完成前强制检查,不得跳过)

What it can do on your machine

Read from SKILL.md and the folder at commit ab0b827. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • docker
    • pip

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use docker and pip, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Debug Expert loads about 986 tokens when it runs, and up to ~3.8k if it reads all its reference files. Until then it costs about 34 tokens; SKILL.md has 140 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~34
When it runs · the whole SKILL.md, loaded when a task matches
~986
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ProgrammerAnthony/Expert-Coding-Harness at commit ab0b827, republished under its MIT licence (© ProgrammerAnthony). 140 words, ~986 tokens.

Download SKILL.mdSave it as .claude/skills/debug-expert/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.
name
debug-expert
description
Use when 程序出现错误、异常、崩溃,或行为与预期不符,或测试失败,或无法定位问题根因时。触发场景:调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了。

调试专家

铁律:先理解,再修改。 禁止在没有复现和定位根因之前就修改代码(猜测式修改往往掩盖真实问题)。

<HARD-GATE>
在完成**阶段二(假设清单)**和**阶段三(最小复现)**之前,禁止对任何代码做出修改。
即便你"知道"原因,也必须先建立假设清单并尝试复现,再动手修改。
</HARD-GATE>

Inputs / Outputs / Gates / Handoffs(统一契约)

  • Inputs(最小输入):期望 vs 实际;完整错误信息/日志/堆栈;可复现步骤(如有);最近改动(如有);运行环境信息(OS/版本/命令)。
  • Outputs(产物形态):一份可交接的调试记录(结构参考 references/debug-log-template.md),包含假设清单、最小复现、证据链、验证命令与回归建议。
  • Gates(继续前必须满足):
    • 未完成“假设清单 + 最小复现”前禁止修改代码(保持与本文件 HARD-GATE 一致)。
    • 宣称“已修复”前必须运行验证命令并贴出绿色输出或关键结果(保持与本文件后续 HARD-GATE 一致)。
    • 通用门控清单可复制使用:../code-review-expert/references/quality-gates-checklist.md。
  • Handoffs(推荐下游):
    • tdd-master(TDD 开发大师):先写能复现问题的测试,再修复
    • writing-plans(实施计划编写):把修复拆成可执行步骤(适合复杂问题)
    • code-review-expert(代码审查专家):变更后做质量门禁

调试工作流

阶段一:问题理解

收集足够的背景信息(每次最多问 2-3 个问题):

必须了解:

  • "期望行为是什么?实际发生了什么?"
  • "错误信息或日志是什么?"(要求贴出完整错误,不要省略)
  • "最后一次正常工作是什么时候?中间做了什么改动?"

按需追问:

  • "是否能稳定复现?还是随机出现?"
  • "在什么环境发生的?(本地/测试/生产,什么 OS/版本)"
  • "是否有完整的调用堆栈?"

明确禁止:在没有完整错误信息时就开始猜测原因。


阶段二:建立假设

根据现有信息,生成 2-5 个可能的假设(从最可能到最不可能排序):

假设清单:
1. [假设 A]:可能性 高/中/低,理由:[...]
2. [假设 B]:可能性 高/中/低,理由:[...]
3. [假设 C]:可能性 高/中/低,理由:[...]

验证计划:先验证假设 1,因为 [原因]。

思考方向:

  • 最近的改动(最可能的原因)
  • 环境差异(本地可以,线上不行 → 看配置、依赖、权限)
  • 数据问题(特定数据触发 → 看边界条件)
  • 并发/时序问题(随机出现 → 看竞态条件)
  • 外部依赖(网络/数据库/第三方服务)

阶段三:最小复现

在验证假设之前,先建立最小可复现的测试案例:

python
# 目标:用最少的代码稳定复现问题
# 好处:
# 1. 确认问题确实存在(而非环境问题)
# 2. 排除无关因素
# 3. 修复后可用作回归测试

# 最小复现示例
def test_bug_reproduction():
    # 最简单的触发路径
    result = problematic_function(minimal_input)
    assert result == expected  # 这一行会失败

如果无法复现:

  • 说明是环境问题 → 系统对比两个环境的差异
  • 说明是特定数据问题 → 询问触发数据的特征

加载 references/root-cause-analysis.md 获取系统化分析工具。


阶段四:定位根因

使用二分法逐步缩小问题范围:

定位策略:
1. 确认问题的边界(从哪里开始出错,到哪里结束)
2. 在中间点添加检查点,判断问题在前半段还是后半段
3. 重复,直到定位到具体的函数/行

常用调试工具:

python
# Python:pdb 调试
import pdb; pdb.set_trace()  # 设置断点

# 或者使用 print 调试(快速但临时)
print(f"DEBUG: variable={variable!r}, type={type(variable)}")

# 日志记录
import logging
logging.debug("状态: %s", state)
bash
# 查看进程状态
ps aux | grep process_name
# 查看端口占用
lsof -i :8080
# 查看系统日志
journalctl -u service_name -n 100 --no-pager
# 查看 Docker 容器日志
docker logs container_name --tail 100

加载 references/debugging-patterns.md 获取特定类型问题的调试模式。


阶段五:修复与验证

定位根因后:

  1. 制定修复方案(不要第一个想到的方案就是最好的):

    • 方案 A:[描述],优点/缺点
    • 方案 B:[描述],优点/缺点
    • 推荐:[哪个方案,为什么]
  2. 实施修复

  3. 验证清单(完成前强制检查,不得跳过):

<HARD-GATE>
在宣布"已修复"之前,必须在本条消息中实际运行验证命令,得到绿色输出才能结束。不得仅凭分析判断就宣称修复完成。
</HARD-GATE>
  • 原始问题是否已解决?(运行最小复现案例)
  • 是否有其他类似的代码也存在相同问题?(用 rg 全局搜索)
  • 修复是否引入了新问题?(运行完整测试套件)
  • 是否需要添加回归测试防止将来重现?
  • 根因是否真正解决,而非只是绕过症状?
  1. 记录(如果是重要的 Bug):
    根因:[什么导致的]
    触发条件:[什么情况下会触发]
    修复方式:[如何修复]
    预防措施:[如何防止再次发生]

特殊问题处理

随机/偶发性问题
  • 极大概率是竞态条件或内存问题
  • 增加日志详细度,在生产环境收集更多信息
  • 检查并发访问共享资源的代码
  • 使用压测工具提高触发频率
只在特定环境出现

系统对比两个环境:

bash
# 对比环境变量
diff <(env | sort) <(ssh prod 'env | sort')
# 对比依赖版本
pip freeze vs pip freeze(生产)
# 对比配置文件
diff local.env prod.env
性能问题

先测量,再优化,不要靠直觉:

python
# Python 性能分析
import cProfile
cProfile.run('main_function()', sort='cumulative')

# 简单计时
import time
start = time.perf_counter()
# ...代码...
print(f"耗时:{time.perf_counter() - start:.3f}秒")

红旗警告:当你想跳过流程时

遇到以下想法,立刻停下,回到当前应该所在的阶段:

借口现实
"错误很明显,我知道原因,直接改就好""明显原因"往往是症状不是根因。30 秒建个假设清单不会耽误你。
"问题太紧急,没时间走流程"猜测式修改引入新 bug 比走流程耗时更长。紧急时更要冷静。
"已经修了类似的 bug,这次一样"表面相似的 bug 根因可能完全不同。相似性是陷阱。
"最小复现太麻烦,能复现就行"无法最小复现 = 无法确认修复 = 留下定时炸弹。
"测试过了,差不多能用""差不多"不是通过标准。必须运行验证清单中的每一项。
"这个问题太随机,复现不了"随机问题 = 竞态条件/内存问题。不复现不代表可以跳过假设阶段。

参考资源

  • references/root-cause-analysis.md — 根因分析工具和框架
  • references/debugging-patterns.md — 常见问题类型的调试模式

© ProgrammerAnthony, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files (references) in skills/debug-expert of ProgrammerAnthony/Expert-Coding-Harness.

  • SKILL.md
  • README.md
  • references/debug-log-template.md
  • references/debugging-patterns.md
  • references/root-cause-analysis.md

Open the folder on GitHubat commit ab0b827

Compare with similar skills

Debug Expert next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Debug Expert compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Debug Expert this skillProgrammerAnthony/Expert-Coding-Harness235—~986Automated safety check: PassMIT
PR Babysitteropeninterpreter/openinterpreter69k3 repos~4.2kAutomated safety check: PassApache-2.0
Mailspring App ScreenshotsFoundry376/Mailspring18k—~1.4kAutomated safety check: PassGPL-3.0
Merge Dependabot PRsonyx-dot-app/onyx32k1 repos~2.2kAutomated safety check: PassMIT
Android UI Visual Reviewpermissionlesstech/bitchat-android7.7k—~2.6kAutomated safety check: PassGPL-3.0
Constraint-Driven Developmentaddyosmani/agent-skills102k2 repos~5.2kAutomated safety check: PassMIT

Similar skills

  • PR Babysitter

    openinterpreter/openinterpreter

    Watches an open GitHub pull request until it merges, handling review comments, diagnosing CI failures and retrying flaky checks along the way.

    69k GitHub starsUsed in 3 repos~4.2k tokens
    DevelopmentAuto-check passed
  • Mailspring App Screenshots

    Foundry376/Mailspring

    Captures screenshots of the running Mailspring dev app for docs, PRs or visual checks by launching it with a debugging port, driving the UI and clipping to an element.

    18k GitHub stars~1.4k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Merge Dependabot PRs

    onyx-dot-app/onyx

    Triages and lands a batch of open Dependabot PRs in the Onyx repo, where main is gated exclusively by GitHub's merge queue: approves and enqueues green PRs, closes superseded duplicates, fixes…

    32k GitHub starsUsed in 1 repo~2.2k tokens
    DevelopmentAuto-check passed
  • Android UI Visual Review

    permissionlesstech/bitchat-android

    Analyze an Android pull request, branch, commit, or patch for user-visible changes and produce reproducible before/after screenshots from isolated builds.

    7.7k GitHub stars~2.6k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Constraint-Driven Development

    addyosmani/agent-skills

    Records a project's quality bar in CONSTRAINTS.md and watches diffs for signs an agent quietly weakened it, such as suppressions, skipped tests or lowered thresholds.

    102k GitHub starsUsed in 2 repos~5.2k tokens
    DevelopmentAuto-check passed
  • Go Pedantry

    chromedp/chromedp

    This skill should be used when the user is writing Go code and needs guidance on Go-specific pedantry: error wrapping with fmt.Errorf and %w, interface design (accept interfaces return structs)…

    13k GitHub stars~3.7k tokensUpdated 2 days ago
    DevelopmentAuto-check passed

More from ProgrammerAnthony/Expert-Coding-Harness

All 23 skills in this repo
  • Architecture Advisor

    ProgrammerAnthony/Expert-Coding-Harness

    A skill your agent uses when 用户需要设计新系统架构、评审或优化已有系统架构、选择技术方案时。触发场景:架构分析、架构设计、系统设计、architecture、架构优化、系统架构、架构评审、架构咨询、技术方案、技术设计、如何组织代码结构、模块划分、服务拆分、数据库选型、微服务设计。

    235 GitHub stars~673 tokensUpdated 4 mo ago
    Auto-check passed
  • Code Review Expert

    ProgrammerAnthony/Expert-Coding-Harness

    A skill your agent uses when 用户要求审查代码、评估代码质量、提交 PR 前检查、发现代码有潜在问题时。触发场景:代码审查、code review、审查代码、review、检查代码、代码检查、代码质量、代码评审、这段代码有问题吗、帮我看看代码、合并前检查。

    235 GitHub stars~806 tokensUpdated 4 mo ago
    Auto-check passed
  • Code Security Audit

    ProgrammerAnthony/Expert-Coding-Harness

    A skill your agent uses when 用户需要对代码进行安全审计、发现安全漏洞、上线前安全评估、检查代码是否存在安全风险时。触发场景:代码安全审计、安全审计、白盒审计、安全扫描、漏洞检测、漏洞挖掘、SQL注入、命令注入、XSS、SSRF、反序列化、认证绕过、越权、代码安全检查、security audit、code…

    235 GitHub stars~1.6k tokensUpdated 4 mo ago
    Auto-check passed
  • Frontend Code Review

    ProgrammerAnthony/Expert-Coding-Harness

    A skill your agent uses when 用户需要审查前端代码(React/Vue/Next.js/TypeScript/Tailwind等)、检查代码质量、性能问题、可维护性、安全漏洞、最佳实践落地时。触发场景:前端代码评审、前端代码优化、React/Vue代码检查、TypeScript代码审查、前端性能优化、前端安全审计、前端代码规范检查。

    235 GitHub stars~614 tokensUpdated 4 mo ago
    Auto-check passed
  • Frontend Performance Optimization

    ProgrammerAnthony/Expert-Coding-Harness

    A skill your agent uses when 用户需要优化前端性能、提升页面加载速度、减少白屏时间、优化交互流畅度、进行性能排查时。触发场景:前端性能优化、页面加载慢、白屏时间长、卡顿、LCP/FID/CLS指标优化、前端性能分析、打包体积优化。

    235 GitHub stars~701 tokensUpdated 4 mo ago
    Auto-check passed
  • Prd Engineer

    ProgrammerAnthony/Expert-Coding-Harness

    A skill your agent uses when 用户需要编写产品需求文档、整理功能需求、拆解 GitHub Issues 或制定实施计划时。触发场景:写PRD、产品需求、需求文档、prd、需求分析、功能设计、产品设计、需求评审、需求拆解、issue拆解、帮我写需求、整理功能点、我有个想法要落地、新功能规划。

    235 GitHub stars~624 tokensUpdated 4 mo ago
    Auto-check passed

Questions about Debug Expert

What does Debug Expert do?

A skill your agent uses when 程序出现错误、异常、崩溃,或行为与预期不符,或测试失败,或无法定位问题根因时。触发场景:调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了。. Debug Expert is an agent skill from ProgrammerAnthony/Expert-Coding-Harness.

When should I use Debug Expert?

Debug Expert fits situations like: 程序出现错误、异常、崩溃,或行为与预期不符,或测试失败,或无法定位问题根因时。触发场景:调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了.

How do I install Debug Expert in Claude Code?

Run `npx skills add ProgrammerAnthony/Expert-Coding-Harness --skill debug-expert -a claude-code`. Or copy the skill folder (skills/debug-expert in ProgrammerAnthony/Expert-Coding-Harness) into .claude/skills/debug-expert in your project. Claude Code loads it when a task matches its description.

How do I install Debug Expert in Codex?

Run `npx skills add ProgrammerAnthony/Expert-Coding-Harness --skill debug-expert -a codex`. Or copy the skill folder (skills/debug-expert in ProgrammerAnthony/Expert-Coding-Harness) into .agents/skills/debug-expert in your project. Codex loads it when a task matches its description.

Can I use Debug Expert in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ProgrammerAnthony/Expert-Coding-Harness --skill debug-expert -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debug-expert, .gemini/skills/debug-expert, .github/skills/debug-expert and .opencode/skills/debug-expert in your project.

What does Debug Expert need to run?

Going by SKILL.md and its folder, Debug Expert needs the command-line tools its instructions call (docker and pip). Our summary lists: Python 3; Docker.

Does Debug Expert access the network?

SKILL.md contains no URLs. Its commands use docker and pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Debug Expert safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Debug Expert use?

Debug Expert is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Debug Expert use?

About 986 tokens (SKILL.md is roughly 3.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2.8k tokens, read only when the agent opens those files.

What are the alternatives to Debug Expert?

Skills that share tags, products or a category with Debug Expert: PR Babysitter (openinterpreter/openinterpreter, 69k stars), Mailspring App Screenshots (Foundry376/Mailspring, 18k stars), Merge Dependabot PRs (onyx-dot-app/onyx, 32k stars) and Android UI Visual Review (permissionlesstech/bitchat-android, 7.7k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Debug Expert?

ProgrammerAnthony (a GitHub user) maintains it in ProgrammerAnthony/Expert-Coding-Harness, which has 235 GitHub stars. The repository holds 23 skills in this directory. The repository was last updated on May 11, 2026.

Source: ProgrammerAnthony/Expert-Coding-Harness on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.