Systematic Debugging
ultralisp/ultralisp
A skill your agent uses when encountering any bug, test failure, or unexpected behavior, before proposing fixes
A skill your agent uses when debugging Go errors, test failures, or unexpected behavior — step-by-step diagnosis approach
Install Debugging Guide
$ npx skills add ZhangShenao/harness9 --skill debugging-guide -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install ZhangShenao/harness9 debugging-guide --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/ZhangShenao/harness9.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/debugging-guide .claude/skills/debugging-guide && rm -rf skills-srcUse ~/.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/
Install the "debugging-guide" agent skill from https://github.com/ZhangShenao/harness9/tree/master/skills/debugging-guide into .claude/skills/debugging-guide/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging-guide", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/ZhangShenao/harness9/tree/master/skills/debugging-guideType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add ZhangShenao/harness9 --skill debugging-guide -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install ZhangShenao/harness9 debugging-guide --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/ZhangShenao/harness9.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/debugging-guide .agents/skills/debugging-guide && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "debugging-guide" agent skill from https://github.com/ZhangShenao/harness9/tree/master/skills/debugging-guide into .agents/skills/debugging-guide/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging-guide", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add ZhangShenao/harness9 --skill debugging-guide -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install ZhangShenao/harness9 debugging-guide --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/ZhangShenao/harness9.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/debugging-guide .cursor/skills/debugging-guide && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "debugging-guide" agent skill from https://github.com/ZhangShenao/harness9/tree/master/skills/debugging-guide into .cursor/skills/debugging-guide/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging-guide", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/ZhangShenao/harness9.git --path skills/debugging-guide--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add ZhangShenao/harness9 --skill debugging-guide -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install ZhangShenao/harness9 debugging-guide --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/ZhangShenao/harness9.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/debugging-guide .gemini/skills/debugging-guide && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "debugging-guide" agent skill from https://github.com/ZhangShenao/harness9/tree/master/skills/debugging-guide into .gemini/skills/debugging-guide/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging-guide", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install ZhangShenao/harness9 debugging-guideInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add ZhangShenao/harness9 --skill debugging-guide -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/ZhangShenao/harness9.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/debugging-guide .github/skills/debugging-guide && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "debugging-guide" agent skill from https://github.com/ZhangShenao/harness9/tree/master/skills/debugging-guide into .github/skills/debugging-guide/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging-guide", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add ZhangShenao/harness9 --skill debugging-guide -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install ZhangShenao/harness9 debugging-guide --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/ZhangShenao/harness9.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/debugging-guide .opencode/skills/debugging-guide && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "debugging-guide" agent skill from https://github.com/ZhangShenao/harness9/tree/master/skills/debugging-guide into .opencode/skills/debugging-guide/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging-guide", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
debugging-guide- GitHub stars
- 141
- Token cost
- ~563 tokens
- SKILL.md length
- 165 words
- Files
- 1
- Skills in repo
- 7
- Repo updated
- First seen
- Licence
- MIT
At a glance
A skill your agent uses when debugging Go errors, test failures, or unexpected behavior — step-by-step diagnosis approach
- Works in 4 steps: 编译错误 → 测试失败 → 运行时 panic → …
- Debugging Go errors
- SKILL.md covers 诊断顺序, 常用调试技巧, harness9 特有问题 and go vet 常见 warning
- Calls go
What it does
Debugging Guide is an agent skill from ZhangShenao/harness9. Use when debugging Go errors, test failures, or unexpected behavior — step-by-step diagnosis approach
Its SKILL.md is about 560 tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Debugging and Failing and flaky tests. The repository describes itself as: Local-First · 轻量级 · 功能完备 · 生产可用的通用 Agent 框架. The licence is MIT.
When your agent uses it
- Debugging Go errors
- Unexpected behavior — step-by-step diagnosis approach
Example prompts
- “/debugging-guide”
Workflow steps
4 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit 5a51b57. 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:
go
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
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
Debugging Guide loads about 563 tokens when it runs. Until then it costs about 29 tokens; SKILL.md has 165 words of instructions outside code blocks.
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 ZhangShenao/harness9 at commit 5a51b57, republished under its MIT licence (© ZhangShenao). 165 words, ~563 tokens.
Download SKILL.mdSave it as
.claude/skills/debugging-guide/SKILL.md (or your agent's skills folder).- name
- debugging-guide
- description
- Use when debugging Go errors, test failures, or unexpected behavior — step-by-step diagnosis approach
- trigger
- debug, error, fail, crash, panic, fix, wrong
harness9 调试指南
诊断顺序
遇到问题时，按以下顺序排查：
1. 编译错误
go build ./...常见原因：
- 未使用的 import → 删除或添加
_blank import - 类型不匹配 → 检查接口实现是否完整
- 循环依赖 → 将接口定义移到使用者侧包中
2. 测试失败
# 详细输出
go test -v ./internal/engine/
# 单个测试
go test -v -run TestAgentLoop ./internal/engine/
# 带 race detector
go test -race ./...3. 运行时 panic
查看完整 goroutine stack：
go run ./cmd/harness9 2>&1 | head -100nil pointer panic 通常来自：
- 未初始化的 map（用
make(map[K]V)初始化） - 接口值为 nil 但调用了方法
4. Agent 行为异常
LLM 不调用工具： 检查工具的 Definition() 描述是否清晰，JSON Schema 是否正确。
工具执行失败： 查看 ToolResult.IsError 和 Output 字段，错误信息会回传给 LLM。
无限循环： 检查 WithMaxTurns 配置，默认 50 Turn。
常用调试技巧
打印 System Prompt
在 internal/context/builder.go 的 Build() 方法末尾临时添加：
fmt.Fprintf(os.Stderr, "=== SYSTEM PROMPT ===\n%s\n===================\n", prompt)检查工具注册
在 registry.Execute 前打印可用工具列表：
for _, def := range registry.GetAvailableTools() {
fmt.Fprintf(os.Stderr, "tool: %s\n", def.Name)
}Provider 请求/响应
如需查看实际 API 请求，在 internal/provider/openai.go 中打印消息列表。
harness9 特有问题
Anthropic Provider：user/assistant 必须严格交替
症状：400 Bad Request 或 invalid_request_error
原因：Anthropic Messages API 禁止连续 assistant 消息。
修复：检查 contextHistory 的消息顺序，确保 system→user→assistant→user→assistant 交替。
路径沙箱拒绝访问
症状：工具返回 路径超出工作区范围 或类似错误
原因：路径包含 ../ 或绝对路径指向启动目录之外。
修复：Agent 应使用相对于启动目录的路径，如 internal/engine/agent_loop.go 而非 /absolute/path/...。
Skills 未加载
症状：Agent 不知道有 Skills 可用
检查：
skills/目录是否在项目根目录（启动目录）下- 每个 Skill 是否在独立子目录中，且子目录内有
SKILL.md文件 SKILL.md是否包含name和descriptionfrontmatter 字段- 启动日志中是否有
[skills]warn 输出
正确的目录结构示例：
skills/
├── go-coding-standards/
│ └── SKILL.md ← 必须是这个文件名
└── debugging-guide/
└── SKILL.mdgo vet 常见 warning
| Warning | 含义 | 修复 |
|---|---|---|
printf 格式不匹配 | %s 传入了非 string 类型 | 修正格式或类型 |
unreachable code | return 后有代码 | 删除死代码 |
loop variable captured | goroutine 捕获了循环变量 | 传参而非捕获 |
© ZhangShenao, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in skills/debugging-guide of ZhangShenao/harness9.
Open the folder on GitHubat commit 5a51b57
Compare with similar skills
Debugging Guide 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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Debugging Guide this skillZhangShenao/harness9 | 141 | — | ~563 | Automated safety check: Pass | MIT | |
| Systematic Debuggingultralisp/ultralisp | 258 | 51 repos | ~2.4k | Automated safety check: Pass | None | |
| Exposed Bug Fix WorkflowJetBrains/Exposed | 9.3k | — | ~3.8k | Automated safety check: Pass | Apache-2.0 | |
| React Router Bug Fix Workflowremix-run/react-router | 57k | — | ~1.3k | Automated safety check: Pass | MIT | |
| Systematic DebuggingChrisWiles/claude-code-showcase | 6.1k | 3 repos | ~1.2k | Automated safety check: Pass | None | |
| Debugging and Error Recoveryaddyosmani/agent-skills | 102k | 1 repos | ~2.6k | Automated safety check: Pass | MIT |
Similar skills
- Official
Exposed Bug Fix Workflow
JetBrains/Exposed
Takes a GitHub or YouTrack issue for the Exposed project through reproduction, a failing test, a fix, validation and a pull request.
React Router Bug Fix Workflow
remix-run/react-router
Fixes a React Router bug reported in a GitHub issue end to end: fetching the issue, validating the reproduction, writing a failing test and implementing the fix on a new branch.
Systematic Debugging
ChrisWiles/claude-code-showcase
Applies a four-phase debugging routine that finds the root cause of a bug or failing test before any fix is written.
Debugging and Error Recovery
addyosmani/agent-skills
Applies a stop-the-line rule and a step-by-step triage when tests fail, builds break or something stops working, aiming at the root cause instead of guesses.
Systematic Debugging
ed3dai/ed3d-plugins
A skill your agent uses when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis…
More from ZhangShenao/harness9
Architecture Overview
ZhangShenao/harness9
A skill your agent uses when asked about harness9 architecture, module design, or how components interact — explains the system design
Go Coding Standards
ZhangShenao/harness9
A skill your agent uses when writing or reviewing Go code — explains harness9 project coding conventions and patterns
Commit
ZhangShenao/harness9
A skill your agent uses when the user invokes /commit or asks to commit changes, after a code review has been completed and the changes are confirmed ready to stage and commit to git.
Cr
ZhangShenao/harness9
A skill your agent uses when the user invokes /cr, requests a code review, or before committing to verify correctness, security, and quality of new or modified code in the working tree.
PR
ZhangShenao/harness9
A skill your agent uses when the user invokes /pr or asks to push changes and open a pull request, after commits are ready to be pushed to a remote branch and merged into the main branch.
Autodev
ZhangShenao/harness9
Feature auto-development — clarify requirements, generate spec, dispatch dev sub-agent to implement and merge into current branch
Related
Categories
Questions about Debugging Guide
What does Debugging Guide do?
A skill your agent uses when debugging Go errors, test failures, or unexpected behavior — step-by-step diagnosis approach. Debugging Guide is an agent skill from ZhangShenao/harness9.
When should I use Debugging Guide?
Debugging Guide fits situations like: debugging Go errors; unexpected behavior — step-by-step diagnosis approach.
How do I install Debugging Guide in Claude Code?
Run `npx skills add ZhangShenao/harness9 --skill debugging-guide -a claude-code`. Or copy the skill folder (skills/debugging-guide in ZhangShenao/harness9) into .claude/skills/debugging-guide in your project. Claude Code loads it when a task matches its description.
How do I install Debugging Guide in Codex?
Run `npx skills add ZhangShenao/harness9 --skill debugging-guide -a codex`. Or copy the skill folder (skills/debugging-guide in ZhangShenao/harness9) into .agents/skills/debugging-guide in your project. Codex loads it when a task matches its description.
Can I use Debugging Guide 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 ZhangShenao/harness9 --skill debugging-guide -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debugging-guide, .gemini/skills/debugging-guide, .github/skills/debugging-guide and .opencode/skills/debugging-guide in your project.
What does Debugging Guide need to run?
Going by SKILL.md and its folder, Debugging Guide needs the command-line tools its instructions call (go).
Does Debugging Guide access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Debugging Guide 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 Debugging Guide use?
Debugging Guide 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 Debugging Guide use?
About 563 tokens (SKILL.md is roughly 2.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Debugging Guide?
Skills that share tags, products or a category with Debugging Guide: Systematic Debugging (ultralisp/ultralisp, 258 stars), Exposed Bug Fix Workflow (JetBrains/Exposed, 9.3k stars), React Router Bug Fix Workflow (remix-run/react-router, 57k stars) and Systematic Debugging (ChrisWiles/claude-code-showcase, 6.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Debugging Guide?
ZhangShenao (a GitHub user) maintains it in ZhangShenao/harness9, which has 141 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on October 7, 2026.
Source: ZhangShenao/harness9 on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.