skill

Name: skill
Author: millionco

291stars12forks

How to install skill?

millionco/debug-agent/skill

$npx -y skills add millionco/debug-agent --skill skill

Installs into the current project.

Summary

Systematic evidence-based debugging using runtime logs. Generates hypotheses, instruments code with NDJSON logs, guides reproduction, analyzes log evidence, and iterates until root cause is proven with cited log lines. Use when the user reports a bug, unexpected behavior, or asks

Files · 1

View on GitHub

SKILL.md

1	# Debug Mode
2
3	You are now in DEBUG MODE. You must debug with runtime evidence.
4
5	Why this approach: Traditional AI agents jump to fixes claiming 100% confidence, but fail due to lacking runtime information.
6	They guess based on code alone. You cannot and must NOT fix bugs this way — you need actual runtime data.
7
8	Your systematic workflow:
9
10	1. Generate 3-5 precise hypotheses about WHY the bug occurs (be detailed, aim for MORE not fewer)
11	2. Instrument code with logs (see Logging section) to test all hypotheses in parallel
12	3. Reproduce the bug.
13	- If a failing test already exists: run it directly.
14	- If reproduction is straightforward (e.g., a single CLI command, a curl request, a simple script): write and run an ad hoc reproduction script yourself. Tailor it to the runtime — Playwright/Puppeteer for browser bugs, a Node/Python/shell script for backend bugs, etc.
15	- Otherwise: ask the user to reproduce it. Provide clear, numbered steps. Remind them to restart apps/services if instrumented files are cached or bundled. Offer: "If you'd like me to write a reproduction script instead, let me know."
16	- Once the user confirms a reproduction pathway (manual or automated), reuse it for all subsequent iterations without re-asking.
17	4. Analyze logs: evaluate each hypothesis (CONFIRMED/REJECTED/INCONCLUSIVE) with cited log line evidence
18	5. Fix only with 100% confidence and log proof; do NOT remove instrumentation yet
19	6. Verify with logs: ask user to run again, compare before/after logs with cited entries
20	7. If logs prove success and user confirms: remove all instrumentation by searching for `#region debug log` / `#endregion` markers and deleting those blocks (see Cleanup section). If failed: FIRST remove any code changes from rejected hypotheses (keep only instrumentation and proven fixes), THEN generate NEW hypotheses from different subsystems and add more instrumentation
21	8. After confirmed success: explain the problem and provide a concise summary of the fix (1-2 lines)
22
23	Critical constraints:
24
25	- NEVER fix without runtime evidence first
26	- ALWAYS rely on runtime information + code (never code alone)
27	- Do NOT remove instrumentation before post-fix verification logs prove success and user confirms that there are no more issues
28	- Fixes often fail; iteration is expected and preferred. Taking longer with more data yields better, more precise fixes
29
30	---
31
32	## Logging
33
34	### Choosing local vs remote mode
35
36	- Local mode (default): Use when the buggy code runs on the same machine as this agent (localhost, local dev server, local scripts). Logs are written to a file on disk.
37	- Remote mode: Use when the buggy code runs on a remote server, cloud environment, or production — anywhere that cannot reach `localhost`. Logs are relayed through a hosted service and read over HTTP.
38
39	If the bug is in code that runs remotely or in production, use remote mode. Otherwise, use local mode.
40
41	### STEP 0: Start the logging server (MANDATORY BEFORE ANY INSTRUMENTATION)
42
43	Local mode — run the debug server in daemon mode before any instrumentation. The `--daemon` flag starts the server in the background and exits immediately with the server info — no backgrounding or `&` required.
44
45	```bash
46	npx debug-agent --daemon
47	```
48
49	The command prints a single JSON line to stdout and exits:
50
51	```json
52	{
53	"sessionId": "a1b2c3",
54	"port": 54321,
55	"endpoint": "http://127.0.0.1:54321/ingest/a1b2c3",
56	"logPath": "/tmp/debug-agent/debug-a1b2c3.log"
57	}
58	```
59
60	Capture and remember these values:
61
62	- Server endpoint: The `endpoint` value (the HTTP endpoint URL where logs will be sent via POST requests)
63	- Log path: The `logPath` value (NDJSON logs are written here)
64	- Session ID: The `sessionId` value (unique identifier for this debug session)
65
66	If the server fails to start, STOP IMMEDIATELY and inform the user.
67
68	- DO NOT PROCEED with instrumentation without valid logging configuration.
69	- The server is idempotent — if one is already running, it returns the existing server's info instead of starting a duplicate.
70	- You do not need to pre-create the log file; it will be created automatically when your instrumentation first writes to it.
71
72	Remote mode — run this instead:
73
74	```bash
75	npx debug-agent remote --daemon
76	```
77
78	The command prints a single JSON line to stdout and exits:
79
80	```json
81	{
82	"sessionId": "V1StGXR8_Z5jdHi6B-myT",
83	"endpoint": "https://debug-agent-remote.aidenbai.workers.dev/s/V1StGXR8_Z5jdHi6B-myT",
84	"streamUrl": "https://debug-agent-remote.aidenbai.workers.dev/s/V1StGXR8_Z5jdHi6B-myT/stream",
85	"expiresAt": 1733460389000
86	}

People who liked this also viewed

6 picks

Type

skill

291stars12forks

View on GitHub

How to install skill?

millionco/debug-agent/skill

$npx -y skills add millionco/debug-agent --skill skill

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Debug Mode
2
3	You are now in DEBUG MODE. You must debug with runtime evidence.
4
5	Why this approach: Traditional AI agents jump to fixes claiming 100% confidence, but fail due to lacking runtime information.
6	They guess based on code alone. You cannot and must NOT fix bugs this way — you need actual runtime data.
7
8	Your systematic workflow:
9
10	1. Generate 3-5 precise hypotheses about WHY the bug occurs (be detailed, aim for MORE not fewer)
11	2. Instrument code with logs (see Logging section) to test all hypotheses in parallel
12	3. Reproduce the bug.
13	- If a failing test already exists: run it directly.
14	- If reproduction is straightforward (e.g., a single CLI command, a curl request, a simple script): write and run an ad hoc reproduction script yourself. Tailor it to the runtime — Playwright/Puppeteer for browser bugs, a Node/Python/shell script for backend bugs, etc.
15	- Otherwise: ask the user to reproduce it. Provide clear, numbered steps. Remind them to restart apps/services if instrumented files are cached or bundled. Offer: "If you'd like me to write a reproduction script instead, let me know."
16	- Once the user confirms a reproduction pathway (manual or automated), reuse it for all subsequent iterations without re-asking.
17	4. Analyze logs: evaluate each hypothesis (CONFIRMED/REJECTED/INCONCLUSIVE) with cited log line evidence
18	5. Fix only with 100% confidence and log proof; do NOT remove instrumentation yet
19	6. Verify with logs: ask user to run again, compare before/after logs with cited entries
20	7. If logs prove success and user confirms: remove all instrumentation by searching for `#region debug log` / `#endregion` markers and deleting those blocks (see Cleanup section). If failed: FIRST remove any code changes from rejected hypotheses (keep only instrumentation and proven fixes), THEN generate NEW hypotheses from different subsystems and add more instrumentation
21	8. After confirmed success: explain the problem and provide a concise summary of the fix (1-2 lines)
22
23	Critical constraints:
24
25	- NEVER fix without runtime evidence first
26	- ALWAYS rely on runtime information + code (never code alone)
27	- Do NOT remove instrumentation before post-fix verification logs prove success and user confirms that there are no more issues
28	- Fixes often fail; iteration is expected and preferred. Taking longer with more data yields better, more precise fixes
29
30	---
31
32	## Logging
33
34	### Choosing local vs remote mode
35
36	- Local mode (default): Use when the buggy code runs on the same machine as this agent (localhost, local dev server, local scripts). Logs are written to a file on disk.
37	- Remote mode: Use when the buggy code runs on a remote server, cloud environment, or production — anywhere that cannot reach `localhost`. Logs are relayed through a hosted service and read over HTTP.
38
39	If the bug is in code that runs remotely or in production, use remote mode. Otherwise, use local mode.
40
41	### STEP 0: Start the logging server (MANDATORY BEFORE ANY INSTRUMENTATION)
42
43	Local mode — run the debug server in daemon mode before any instrumentation. The `--daemon` flag starts the server in the background and exits immediately with the server info — no backgrounding or `&` required.
44
45	```bash
46	npx debug-agent --daemon
47	```
48
49	The command prints a single JSON line to stdout and exits:
50
51	```json
52	{
53	"sessionId": "a1b2c3",
54	"port": 54321,
55	"endpoint": "http://127.0.0.1:54321/ingest/a1b2c3",
56	"logPath": "/tmp/debug-agent/debug-a1b2c3.log"
57	}
58	```
59
60	Capture and remember these values:
61
62	- Server endpoint: The `endpoint` value (the HTTP endpoint URL where logs will be sent via POST requests)
63	- Log path: The `logPath` value (NDJSON logs are written here)
64	- Session ID: The `sessionId` value (unique identifier for this debug session)
65
66	If the server fails to start, STOP IMMEDIATELY and inform the user.
67
68	- DO NOT PROCEED with instrumentation without valid logging configuration.
69	- The server is idempotent — if one is already running, it returns the existing server's info instead of starting a duplicate.
70	- You do not need to pre-create the log file; it will be created automatically when your instrumentation first writes to it.
71
72	Remote mode — run this instead:
73
74	```bash
75	npx debug-agent remote --daemon
76	```
77
78	The command prints a single JSON line to stdout and exits:
79
80	```json
81	{
82	"sessionId": "V1StGXR8_Z5jdHi6B-myT",
83	"endpoint": "https://debug-agent-remote.aidenbai.workers.dev/s/V1StGXR8_Z5jdHi6B-myT",
84	"streamUrl": "https://debug-agent-remote.aidenbai.workers.dev/s/V1StGXR8_Z5jdHi6B-myT/stream",
85	"expiresAt": 1733460389000
86	}

People who liked this also viewed

6 picks

Type