Streamline SKILL.md with progressive disclosure

[AlmogBaku]

Summary

• Condensed the debugging mindset section — removed verbose explanations Claude already understands
• Extracted advanced scenarios (hangs, concurrency bugs, loop bisection, complex state inspection) into references/advanced-techniques.md
• Trimmed setup section prose for conciseness

Aligns with Anthropic's skill authoring best practices: concise SKILL.md, progressive disclosure via reference files, one-level-deep linking.

Test plan

• Verify skill triggers correctly on debugging tasks
• Confirm advanced-techniques.md is loaded when Claude encounters hangs/concurrency scenarios
• Test with real debugging sessions to ensure no critical info is lost from main flow

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Refactor SKILL.md with progressive disclosure for conciseness

📝 Documentation

Walkthroughs

Description

• Condensed SKILL.md with progressive disclosure pattern
• Extracted advanced debugging scenarios to separate reference file
• Removed verbose explanations from setup and mindset sections
• Streamlined content to align with Anthropic skill authoring best practices

Diagram

flowchart LR
  A["SKILL.md<br/>Main debugging guide"] -->|Extract advanced scenarios| B["advanced-techniques.md<br/>Hangs, concurrency, bisection"]
  A -->|Condense prose| C["Streamlined setup<br/>and mindset sections"]
  A -->|Add reference link| D["Progressive disclosure<br/>via references/"]

Loading

File Changes

1. skills/debugging-code/SKILL.md 📝 Documentation +12/-65

Condense main skill with progressive disclosure

• Condensed setup section from 4 sentences to 2, removing verbose explanations about daemon
 management
• Streamlined debugging mindset section by removing redundant prose about print-based debugging and
 hypothesis validation
• Extracted advanced scenarios (hangs, concurrency bugs, loop bisection, complex state inspection)
 into reference file
• Replaced detailed advanced sections with single "Advanced Scenarios" pointer to
 references/advanced-techniques.md
• Minor wording improvements (e.g., "debugger backend" instead of "backend debugger")

skills/debugging-code/SKILL.md

---

2. skills/debugging-code/references/advanced-techniques.md 📝 Documentation +50/-0

New file for advanced debugging scenarios

• Created new reference file for advanced debugging techniques
• Moved "When the Program Hangs" section with full explanation and examples
• Moved "Digging Into Complex State" section with inspection guidance
• Moved "Concurrency Bugs" section with deadlock and race condition patterns
• Moved "Bisecting Loops" section with binary search debugging strategy

skills/debugging-code/references/advanced-techniques.md

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Daemon model explanation removed 🐞 Bug ✓ Correctness

Description

The Setup section no longer explains that dap relies on a background daemon to preserve the debug
session across separate CLI commands, even though later workflow relies on that behavior. This makes
the skill materially harder to follow and can lead to incorrect session usage (e.g., re-running `dap
debug` instead of continuing the existing session).

Code

skills/debugging-code/SKILL.md[R19-20]

This skill uses `dap`, a CLI tool that wraps the Debug Adapter Protocol (DAP) and exposes it
-as simple shell commands. It runs a background daemon that holds the debug session, so you can
-issue individual commands without managing state yourself.
+as simple commands.

Evidence

SKILL.md now only says dap is exposed “as simple commands” and omits the daemon/session
persistence model, while the repo’s README and CLAUDE.md explicitly define the daemon-held session
as a core design principle for how the CLI works across invocations.

skills/debugging-code/SKILL.md[19-20]
README.md[71-75]
CLAUDE.md[5-5]
CLAUDE.md[48-51]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The skill’s Setup section removed the explanation that `dap` maintains session state via a background daemon. This is core to understanding why separate `dap` CLI invocations (eval/step/continue) work on the same debugging session.

## Issue Context
The repository’s README and CLAUDE.md both describe the daemon-held session as central to how `dap` works.

## Fix Focus Areas
- skills/debugging-code/SKILL.md[19-21]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Setup text contains typos 🐞 Bug ✓ Correctness

Description

The updated Setup section introduces spelling errors (e.g., “Alternativly”, “maintaind”) in the
installation guidance. This reduces clarity and professionalism in the user/agent-facing
instructions.

Code

skills/debugging-code/SKILL.md[R29-32]

Alternativly, install from sources `go install github.com/AlmogBaku/debug-skill/cmd/dap@latest`

-This tool is fully open-source and available on [GitHub](https://github.com/AlmogBaku/debug-skill), it follows best
-practices, is actively maintained, and secured. The user can either install it from binaries (using the installer
-script) or from sources.
+This tool is open-sourced and available on [GitHub](https://github.com/AlmogBaku/debug-skill), maintaind and follows
+best practices.

Evidence

The misspellings are present directly in the install instructions users/agents will read and
potentially quote/copy while setting up the tool.

skills/debugging-code/SKILL.md[29-32]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Installation guidance in SKILL.md contains spelling mistakes that reduce clarity.

## Issue Context
These lines are in the primary Setup instructions and are likely to be read/copy-pasted.

## Fix Focus Areas
- skills/debugging-code/SKILL.md[29-32]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[qodo-free-for-open-source-projects]

1. Daemon model explanation removed 🐞 Bug ✓ Correctness

The Setup section no longer explains that dap relies on a background daemon to preserve the debug
session across separate CLI commands, even though later workflow relies on that behavior. This makes
the skill materially harder to follow and can lead to incorrect session usage (e.g., re-running `dap
debug` instead of continuing the existing session).

Agent Prompt

## Issue description
The skill’s Setup section removed the explanation that `dap` maintains session state via a background daemon. This is core to understanding why separate `dap` CLI invocations (eval/step/continue) work on the same debugging session.

## Issue Context
The repository’s README and CLAUDE.md both describe the daemon-held session as central to how `dap` works.

## Fix Focus Areas
- skills/debugging-code/SKILL.md[19-21]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools