bugfix-protocol

bugfix-protocol is a skill for Claude Code, Codex from ellmos-ai/skills. It costs 44 tokens per session (2,764 once invoked), scanned C, a copy of bugfix-protocol, MIT.

A six-stage debugging process for finding and fixing software bugs. It covers quick checks, diagnosis, isolation, repair, verification, and documenting the result.

In plain words
What is it for?
Use it to investigate symptoms, reproduce bugs, identify root causes, make small fixes, check for side effects, and record what you learned.
Why use it?
It gives debugging a repeatable sequence and includes a rule for changing approach or asking for help after 20 minutes without progress.

Skill for Claude CodeCodex

Written for no agent in particular: nothing here depends on one.

Good fit Use it to investigate symptoms, reproduce bugs, identify root causes, make small fixes, check for side effects, and record what you learned.

Compare 6 skills from other repositories ↓
Install with agentmods
npx agentmods add skills/ellmos-ai/skills/zh
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent
npx skills add ellmos-ai/skills --skill zh
Clone the repo
git clone --depth 1 https://github.com/ellmos-ai/skills

Made for: Claude Code, Codex.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for bugfix-protocol

README.md
[![agentmods](https://agentmods.dev/badge/skills/ellmos-ai/skills/zh/github.svg)](https://agentmods.dev/skills/ellmos-ai/skills/zh)
Your own site
<a href="https://agentmods.dev/skills/ellmos-ai/skills/zh"><img src="https://agentmods.dev/badge/skills/ellmos-ai/skills/zh/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

agentmods 80×15 button for bugfix-protocol

Your own site · 80×15
<a href="https://agentmods.dev/skills/ellmos-ai/skills/zh"><img src="https://agentmods.dev/badge/skills/ellmos-ai/skills/zh.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 44 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 2,764 The whole file, excluding the scripts and references it only reads on demand.
Security scan C 1 finding. A grade says what 26 rules found in the file — not that it is safe.
Origin 86% copy Near-identical to another mod in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.00044 $0.02764
Opus 5 $0.00022 $0.01382
Sonnet 5 $0.00009 $0.00553
Haiku 4.5 $0.00004 $0.00276

Measured 9d ago against content hash fe0fb16eff7c, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-09, from the pricing page.

Security

Grade C, and why

bugfix-protocol scanned grade C with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 9d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Recursive force deletehighDestructive command

rm -rf with a variable or a broad path is one typo away from removing the wrong tree.

find . -name "__pycache__" -type d -exec rm -rf {} + 2>&1
Origin

This is a copy

86% identical to bugfix-protocol — 298 lines differ, which has more behind it and is treated as the original. This page carries a canonical link to it rather than competing with it.

skills/dev/bugfix-protocol/ZH/SKILL.md · 334 lines

How it starts

The opening of the file, as written. The whole thing — 334 lines — stays where its author put it; the contents beside it link to each section on GitHub.

中文bugfix-protocol 官方中文版本。

Bugfix Protocol: 系统的 6 阶段 Debugging 协议

结构化的 Bug 处理方法 — 从症状分析到验证。 防止盲目的试错,确保修复方案可持续。


概述与目的

阶段 名称 目标 最长时间
1 快速检查 排除明显原因 2 分钟
2 诊断 定位根本原因 10 分钟
3 隔离测试 使 Bug 可复现 5 分钟
4 修复 最小化修正 10 分钟
5 验证 验证修复 + 检查副作用 5 分钟
6 文档编写 保存知识经验 2 分钟

20分钟规则: 如果 20 分钟后仍无进展,请改变方法或寻求帮助。


阶段 1: 快速检查 (2 分钟)

在深入分析之前 — 检查最常见的原因:

检查清单

  • 语法错误? 仔细阅读错误信息,检查对应行
  • 导入错误? 模块已安装?名称正确?循环导入?
  • 拼写错误? 变量/函数名称是否正确?
  • 数据类型错误? 字符串误作为整型?本应为对象的地方为 None?
  • 缓存过期? 删除 __pycache__,重新启动
  • 环境错误? 是否激活了正确的 venv?Python 版本是否正确?
  • 编码问题? UTF-8 vs. cp1252 (Windows 经典)

快速操作

# 清除缓存
find . -name "__pycache__" -type d -exec rm -rf {} + 2>&1
find . -name "*.pyc" -delete 2>&1

# 检查导入
python -c "import modulename"

# 检查语法
python -m py_compile file.py

阶段 2: 诊断 (10 分钟)

策略:由外入内 (Outside-In)

  1. 分析错误信息 — 从下往上阅读堆栈追踪 (traceback)
  2. 检查最近的修改git diff, git log --oneline -10
  3. 使用诊断工具 — 使用项目专属的诊断工具

诊断工具 (示例)

根据项目的不同,专用的诊断脚本可能会大有帮助:

工具 用途
import_diagnose.py 分析导入问题
method_analyzer.py 检查方法签名
env_checker.py 验证环境变量/路径

注意: 创建项目专属的诊断工具或使用现有的工具。 重要的是系统性的方法,而不是具体的工具。

调试技巧

# 1. Print 调试 (简单但高效)
print(f"DEBUG: variable={variable!r}, type={type(variable)}")

# 2. 断点 (交互式)
breakpoint()  # Python 3.7+

# 3. 详细堆栈追踪
import traceback
traceback.print_exc()

# 4. 使用日志替代 print
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
logger.debug(f"State: {state!r}")

阶段 3: 隔离测试 (5 分钟)

最小可复现示例 (MRE)

目标:用最少的代码复现 Bug。

# test_bug.py — 最小复现测试
"""
Bug: [简短描述]
Expected: [预期发生的结果]
Actual: [实际发生的结果]
"""

# 最小化设置
# ... 仅保留核心必要代码

# Bug 触发器
# ... 触发 Bug 的精确代码

# 预期结果
# assert result == expected, f"Got {result}"

Read the full file on GitHub · 334 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 9d ago First seen · 334 lines · 44 tokens per session scan C fe0fb16eff7c

Subscribe to this mod's changes

bugfix-protocol is a skill published in the GitHub repository ellmos-ai/skills (4 stars, last pushed today), licensed MIT. It adds 44 tokens to every session and 2,764 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it C with 1 finding (recursive force delete). It is 86% identical to bugfix-protocol, differing in 298 lines, and is treated as a copy.

Related

Other skills, from other repositories

accelerate

Run PyTorch training across GPUs with minimal changes.

NousResearch/hermes-agent · 13 tokens

jupyter-notebook

Iterative Python via live Jupyter kernel (hamelnb).

NousResearch/hermes-agent · 18 tokens

stack-trace-python-probe

Internal helper for meta-stack-trace-investigator. Use when a Python traceback needs Python-specific root-cause checks, pytest reproducer guidance, and defensive patch targets.

opensquilla/opensquilla · 40 tokens

pyghidra-scripting

Write and run Python (PyGhidra) code inside the Ghidra session that ReVa's MCP server is already attached to, using the five ReVa scripting tools — run-script, list-scripts, read-script, write-script, edit-script. Use this whenever the user asks to execute Python against the current program, reach for the Ghidra Flat…

cyberkaida/reverse-engineering-assistant · 209 tokens

ctf-kit

Use when the user is solving an authorized CTF / lab reverse-engineering challenge focused on Windows application authentication or license-check bypass. Guides triage → static analysis → dynamic experiment planning → bypass verification, with strong evidence discipline and VM safety boundaries. NOT for real-world…

KerberosClaw/kc_ai_skills · 83 tokens

memory-lint

Use when the user wants to lint a Claude Code memory directory (/.claude/memory or custom path) for index inconsistency, broken cross-links, stale project state, duplicate / conflicting feedback rules, naming violations, frontmatter gaps, and oversized files. Phase 1 is a read-only scan and report. Phase 2 applies…

KerberosClaw/kc_ai_skills · 95 tokens