Agent skill

Debug Logs

Iterative debugging with targeted logs. An agent skill from adam-s/intercept.

Install Debug Logs

skills CLI

$ npx skills add adam-s/intercept --skill debug-logs -a claude-code

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

GitHub CLI

$ gh skill install adam-s/intercept debug-logs --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/adam-s/intercept.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/debug-logs .claude/skills/debug-logs && 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/

Paste into Claude Code

Install the "debug-logs" agent skill from https://github.com/adam-s/intercept/tree/main/.claude/skills/debug-logs into .claude/skills/debug-logs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-logs", 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

$skill-installer install https://github.com/adam-s/intercept/tree/main/.claude/skills/debug-logs

Type 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.

skills CLI

$ npx skills add adam-s/intercept --skill debug-logs -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install adam-s/intercept debug-logs --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/adam-s/intercept.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.claude/skills/debug-logs .agents/skills/debug-logs && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "debug-logs" agent skill from https://github.com/adam-s/intercept/tree/main/.claude/skills/debug-logs into .agents/skills/debug-logs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-logs", 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.

skills CLI

$ npx skills add adam-s/intercept --skill debug-logs -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install adam-s/intercept debug-logs --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/adam-s/intercept.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.claude/skills/debug-logs .cursor/skills/debug-logs && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "debug-logs" agent skill from https://github.com/adam-s/intercept/tree/main/.claude/skills/debug-logs into .cursor/skills/debug-logs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-logs", 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

$ gemini skills install https://github.com/adam-s/intercept.git --path .claude/skills/debug-logs

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add adam-s/intercept --skill debug-logs -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install adam-s/intercept debug-logs --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/adam-s/intercept.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.claude/skills/debug-logs .gemini/skills/debug-logs && rm -rf skills-src

Use ~/.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/

Paste into Gemini CLI

Install the "debug-logs" agent skill from https://github.com/adam-s/intercept/tree/main/.claude/skills/debug-logs into .gemini/skills/debug-logs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-logs", 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.

GitHub CLI

$ gh skill install adam-s/intercept debug-logs

Installs 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).

skills CLI

$ npx skills add adam-s/intercept --skill debug-logs -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/adam-s/intercept.git skills-src && mkdir -p .github/skills && cp -r skills-src/.claude/skills/debug-logs .github/skills/debug-logs && rm -rf skills-src

Use ~/.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/

Paste into GitHub Copilot

Install the "debug-logs" agent skill from https://github.com/adam-s/intercept/tree/main/.claude/skills/debug-logs into .github/skills/debug-logs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-logs", 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.

skills CLI

$ npx skills add adam-s/intercept --skill debug-logs -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install adam-s/intercept debug-logs --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/adam-s/intercept.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.claude/skills/debug-logs .opencode/skills/debug-logs && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "debug-logs" agent skill from https://github.com/adam-s/intercept/tree/main/.claude/skills/debug-logs into .opencode/skills/debug-logs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-logs", 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: debug-logs
GitHub stars: 189
Token cost: ~1.1k tokens
SKILL.md length: 508 words
Files: 1
Skills in repo: 10
Repo updated: Jul 31, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Iterative debugging with targeted logs. An agent skill from adam-s/intercept.

Works in 6 steps: Hypothesize → Add targeted DEBUG() calls → Reproduce and read → …
Browser connections fail
SKILL.md covers The DEBUG() Function, The Process and Example
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Debug Logs is an agent skill from adam-s/intercept. Iterative debugging with targeted logs. Use when browser connections fail, traffic capture returns empty, proxy routes return errors, WebSocket issues, or any problem that can't be solved on the first attempt. Add logs, read output, narrow the search, repeat until fixed, then clean up.

Its SKILL.md is about 1.1k 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 Backend & APIs, covering Debugging and Realtime and WebSockets. The repository describes itself as: Turn any website into a typed JSON API using self improving agents. The licence is MIT.

When your agent uses it

Browser connections fail
Traffic capture returns empty
Proxy routes return errors
WebSocket issues

Example prompts

“/debug-logs”

Workflow steps

6 steps, taken from the step headings in SKILL.md.

Hypothesize
Add targeted DEBUG() calls
Reproduce and read
Narrow or widen
Clean up
Clear logs

What it can do on your machine

Read from SKILL.md and the folder at commit 6451b89. 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
No scripts in the folder and no shell commands in SKILL.md (its code samples are bash and typescript).
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

Debug Logs loads about 1.1k tokens when it runs. Until then it costs about 74 tokens; SKILL.md has 508 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~74
When it runs · the whole SKILL.md, loaded when a task matches: ~1.1k

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 adam-s/intercept at commit 6451b89, republished under its MIT licence (© adam-s). 508 words, ~1,138 tokens.

Download SKILL.mdSave it as .claude/skills/debug-logs/SKILL.md (or your agent's skills folder).

name: debug-logs
description: Iterative debugging with targeted logs. Use when browser connections fail, traffic capture returns empty, proxy routes return errors, WebSocket issues, or any problem that can't be solved on the first attempt. Add logs, read output, narrow the search, repeat until fixed, then clean up.

Iterative Debug Logging

When you can't solve a problem by reading code alone, use DEBUG() to observe runtime behavior. This is a methodical process — not a one-shot fix.

The DEBUG() Function

Canonical implementation at packages/shared/src/debug.ts. Choose the import based on context:

typescript

import { DEBUG } from "@interceptor/shared";  // server/API code (routes, handlers)
import { DEBUG } from "@/lib/debug";          // client components ('use client') — do NOT import @interceptor/shared in browser code

Call signatures:

typescript

DEBUG('message')
DEBUG('location', 'message')
DEBUG('location', () => ({ data: value }))
DEBUG('location', 'message', () => ({ data: value }))

The data argument is a factory function (lambda) — expensive computation is deferred and only runs when logging is enabled. DEBUG is disabled in test and production (NODE_ENV).

Output goes to /tmp/interceptor-debug/debug-YYYY-MM-DD.log and console (cyan).

The Process

Step 1: Hypothesize

Before adding any logs, form a hypothesis about where the bug likely is. Ask:

What is the symptom? (e.g., "counter is frozen", "state not updating", "wrong value displayed")
What code path produces the visible output? Trace backwards from the symptom.
Which functions sit between the input and the broken output?

Step 2: Add targeted DEBUG() calls

Add 2-4 calls in the functions you suspect. Log the values that would confirm or reject your hypothesis. Be strategic — avoid noisy locations like tight loops unless you suspect the loop itself.

Good placement:

At the entry of a function you suspect, logging its inputs
At decision points (if/else branches) to see which path was taken
Right before and after a value transformation to see what changed

Bad placement:

Inside a loop that runs hundreds of times per second
In functions you have no reason to suspect
Logging entire objects when one field would suffice

Step 3: Reproduce and read

Reproduce the bug. Then read the log:

bash

cat /tmp/interceptor-debug/debug-$(date +%Y-%m-%d).log

If the file is missing or empty:

bash

ls -la /tmp/interceptor-debug/

For live tailing while reproducing:

bash

tail -f /tmp/interceptor-debug/debug-*.log

Step 4: Narrow or widen

If the logs reveal the bug — fix it, go to Step 5.

If the logs show expected behavior in the suspected area — the bug is elsewhere. Widen scope:

Remove the DEBUG() calls that proved unhelpful
Add new ones in the next most likely location
Move further up or down the call chain

If the logs show something unexpected but you can't pinpoint why — add more calls to narrow within the same area. Log intermediate values, branch decisions, loop iterations.

Repeat Steps 2-4 until the root cause is clear.

Show full SKILL.md (158 more words)Show less

Step 5: Clean up

After fixing the bug, remove DEBUG() calls that were only useful for this investigation. Keep a call only if:

It logs a value that would be useful for future debugging of the same area
It sits at a critical decision point that is hard to reason about from code alone
It captures state that is otherwise invisible (e.g., values computed across multiple steps)

When in doubt, remove it. The calls are easy to add back.

Step 6: Clear logs

bash

rm -f /tmp/interceptor-debug/*.log

Example

Symptom: "The SSE counter is frozen — client connects but count never updates."

Hypothesis: The broadcast function might not be sending updates.

Add DEBUG() in broadcast() and tick():

typescript

function tick(): void {
  count += multiplier;
  DEBUG("tick", () => ({ count, multiplier }));
  broadcast();
}

function broadcast(): void {
  const state = getState();
  const json = JSON.stringify(state);
  DEBUG("broadcast", () => ({ count: state.count, jsonMatch: json === lastJson }));
  if (json === lastJson) return;
  lastJson = json;
  // ...
}

Read logs: If you see tick incrementing but broadcast always showing jsonMatch: true, the dedup comparison is wrong — lastJson is being set before the check.

Fix, then remove the DEBUG() calls (or keep one in broadcast if the dedup logic is tricky enough to warrant permanent observability).

Files

Just SKILL.md in .claude/skills/debug-logs of adam-s/intercept.

Open the folder on GitHubat commit 6451b89

Compare with similar skills

Debug Logs 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 Logs compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Debug Logs this skilladam-s/intercept	189	—	~1.1k	Automated safety check: Pass	MIT	2 mo ago
Supabase Development and Debuggingsupabase/agent-skills	2.7k	3 repos	~3.6k	Automated safety check: Pass	MIT	5 days ago
Debugging Websocket IssuesAgentWorkforce/relay	865	1 repos	~1.3k	Automated safety check: Pass	Apache-2.0	today
Gateway Proxy Debugvercel-labs/vercel-openclaw-archived	117	—	~573	Automated safety check: Pass	MIT	4 mo ago
Realtimebutterbase-ai/butterbase-skills	534	—	~2.1k	Automated safety check: Pass	MIT	2 days ago
Fullstack Devinfometa/workbuddyskills	342	—	~1k	Automated safety check: Pass	MIT	yesterday

Similar skills

Supabase Development and Debugging
supabase/agent-skills
Official
General Supabase skill for database, auth, Edge Functions, Realtime and storage work, plus client libraries, migrations, security audits, debugging and reading logs.
2.7k GitHub starsUsed in 3 repos~3.6k tokens
Backend & APIsAuto-check passed
Debugging Websocket Issues
AgentWorkforce/relay
A skill your agent uses when seeing WebSocket errors like "Invalid frame header", "RSV1 must be clear", or "WSERRUNEXPECTEDRSV1" - covers multiple WebSocketServer conflicts, compression issues, and…
865 GitHub starsUsed in 1 repo~1.3k tokens
Backend & APIsAuto-check passed
Gateway Proxy Debug
vercel-labs/vercel-openclaw-archived
Official
Gateway and proxy debugging for vercel-openclaw: /gateway routing, HTML injection, WebSocket rewrite, gateway-token handoff, waiting page, status heartbeat, sandbox port URL cache, and proxy auth.
117 GitHub stars~573 tokensUpdated 4 mo ago
Backend & APIsAuto-check passed
Realtime
butterbase-ai/butterbase-skills
A skill your agent uses when enabling WebSocket subscriptions for live database changes, presence/multiplayer state, or when debugging clients that connect but receive no events
534 GitHub stars~2.1k tokensUpdated 2 days ago
Backend & APIsAuto-check passed
Fullstack Dev
infometa/workbuddyskills
Full-stack backend architecture and frontend-backend integration guide.
342 GitHub stars~1k tokensUpdated yesterday
Backend & APIsAuto-check passed
EasyEDA Pro API Bridge
easyeda/easyeda-api-skill
Gives an agent the EasyEDA Pro API reference and a WebSocket bridge to run code in a live EasyEDA client, for PCB, schematic and library work and extension development.
855 GitHub stars~7.8k tokensUpdated 5 days ago
DevelopmentAuto-check passed

Questions about Debug Logs

What does Debug Logs do?

Iterative debugging with targeted logs. An agent skill from adam-s/intercept. Debug Logs is an agent skill from adam-s/intercept. Iterative debugging with targeted logs.

When should I use Debug Logs?

Debug Logs fits situations like: browser connections fail; traffic capture returns empty; proxy routes return errors; webSocket issues.

How do I install Debug Logs in Claude Code?

Run `npx skills add adam-s/intercept --skill debug-logs -a claude-code`. Or copy the skill folder (.claude/skills/debug-logs in adam-s/intercept) into .claude/skills/debug-logs in your project. Claude Code loads it when a task matches its description.

How do I install Debug Logs in Codex?

Run `npx skills add adam-s/intercept --skill debug-logs -a codex`. Or copy the skill folder (.claude/skills/debug-logs in adam-s/intercept) into .agents/skills/debug-logs in your project. Codex loads it when a task matches its description.

Can I use Debug Logs 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 adam-s/intercept --skill debug-logs -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-logs, .gemini/skills/debug-logs, .github/skills/debug-logs and .opencode/skills/debug-logs in your project.

What does Debug Logs need to run?

SKILL.md names no scripts, command-line tools or credentials: Debug Logs is instructions for the agent only.

Does Debug Logs 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 Debug Logs 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 Logs use?

Debug Logs 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 Logs use?

About 1.1k tokens (SKILL.md is roughly 4.6k 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 Debug Logs?

Skills that share tags, products or a category with Debug Logs: Supabase Development and Debugging (supabase/agent-skills, 2.7k stars), Debugging Websocket Issues (AgentWorkforce/relay, 865 stars), Gateway Proxy Debug (vercel-labs/vercel-openclaw-archived, 117 stars) and Realtime (butterbase-ai/butterbase-skills, 534 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Debug Logs?

adam-s (a GitHub user) maintains it in adam-s/intercept, which has 189 GitHub stars. The repository holds 10 skills in this directory. The repository was last updated on July 31, 2026.

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

Install Debug Logs

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Iterative Debug Logging

The DEBUG() Function

The Process

Step 1: Hypothesize

Step 2: Add targeted DEBUG() calls

Step 3: Reproduce and read

Step 4: Narrow or widen

Step 5: Clean up

Step 6: Clear logs

Example

Files

Compare with similar skills

Similar skills

More from adam-s/intercept

Related

Questions about Debug Logs