# Debug Agent Communication Failures

Agent systems can fail through silent routing, transport, or configuration issues. This skill guides structured checks for processes, logs, environment, and message delivery.

## Install

```bash
npx skillstore add egadams/agent-communication-debugger
```

## Metadata

- Status: approved
- Slug: egadams-agent-communication-debugger
- Skillstore revision: r1
- Version status: missing
- Tree hash: 3587b1a5f0dd8a45c327025fad71d4fc35aa73b375adba6636c0e5556544fb66
- Author: EGAdams
- GitHub username: EGAdams
- License: MIT
- Repository: https://github.com/EGAdams/planner/tree/main/.claude/skills/agent-debug
- Ref: 26421118b848d9f1efc0aa169d8a7a9e7e0a877e
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: filesystem, env\_access, external\_commands
- Quality score: 50
- Quality tier: warning
- Public page: https://skillstore.pages.dev/skills/egadams-agent-communication-debugger
- Manifest: https://skillstore.pages.dev/api/skills/egadams-agent-communication-debugger/manifest

## Capabilities

- Checks whether orchestrator, coder, tester, and WebSocket agent processes are running.
- Inspects agent configuration files for names, topics, capabilities, and syntax issues.
- Reviews logs for errors, routing decisions, connection failures, and message processing problems.
- Tests message delivery with the included message test script.
- Checks WebSocket and message board transport state for local agent communication.
- Provides restart workflows for stuck local agents and transport services.

## Use Cases

- Restore Silent Agent Workflows: Trace why an orchestrator or worker agent receives messages but does not respond.
- Verify Local Agent Services: Check processes, local ports, logs, and transport state during a development environment incident.
- Run Communication Smoke Tests: Send test messages and confirm that routing, responses, and storage paths behave as expected.

## Prompt Templates

### Check Basic Agent Health

```
Use the agent communication debugger to check which local agents are running and summarize any missing services.
```

### Trace a Missing Message

```
Debug why my message reached the orchestrator but no worker agent responded. Review logs, transport, and recent routing decisions.
```

### Diagnose Wrong Routing

```
Find why code requests are routed to the wrong agent. Compare discovered agents, routing logs, and priority keyword mappings.
```

### Audit the Full Transport Stack

```
Run a complete communication diagnostic across processes, configuration, logs, WebSocket transport, message board state, and test delivery results.
```

## Limitations

- Assumes the project uses the documented a2a\_communicating\_agents and logs directories.
- Requires local shell access and the required Python dependencies.
- Identifies likely causes but does not automatically repair agent code.
- Some restart steps can stop or start local processes and need review before use.

## Best Practices

- Run read-only status and log checks before restart commands.
- Mask API key values and share only whether each variable exists.
- Record the symptom, target agent, message text, and timestamp before diagnosis.

## Anti Patterns

- Do not paste real API keys or full environment files into chat.
- Do not run broad restart commands before checking affected processes.
- Do not assume routing is broken before verifying discovery and transport.

## Security Audit

- Audited at: 2026-07-09T15:46:33.988\+00:00
- Summary: Most static findings are false positives caused by Markdown command examples for local troubleshooting. I confirmed one unmasked API key check in common\_issues.md and several persistent nohup start commands; I also found restart guidance that can terminate local agent processes.

## Stats

- Views: 372
- Downloads: 7
- Favorites: 0
- Popularity score: 0