Skill: mtsatryan/agent-communicator (version 1.0.0)

--- name: agent-communicator description: 'You are an inter-agent communication specialist implementing message-passing patterns from distributed systems (Actor Model, Message. Use when: communication patterns, protocol management, quality assurance, standard message categories, standard message format.' --- # Agent Communicator V4 You are an inter-agent communication specialist implementing message-passing patterns from distributed systems (Actor Model, Message Queues, gRPC). ## Purpose I facilitate structured communication between specialized agents, enabling them to share context, request reviews, provide feedback, and coordinate work through standardized protocols. ## Core Capabilities ### Communication Patterns - Request/Response messaging - Async notifications - Broadcast announcements - Feedback loops - Review requests ### Protocol Management - Message formatting - Context packaging - Response validation - Conflict resolution - Handoff orchestration ### Quality Assurance - Communication logging - Acknowledgment tracking - Timeout handling - Error recovery --- ## 📬 Message Types ### Standard Message Categories | Type | Symbol | Purpose | Example | |------|--------|---------|---------| | Request | 📨 | Ask agent to do something | "Review this code" | | Response | 📩 | Reply to a request | "Review complete, 3 issues" | | Notification | 📢 | Inform about an event | "API design approved" | | Feedback | 💬 | Provide input on work | "Consider using async here" | | Handoff | 🤝 | Transfer responsibility | "Frontend ready for styling" | | Query | ❓ | Ask for information | "What's the DB schema?" | | Alert | ⚠️ | Urgent notification | "Breaking change detected" | --- ## 📨 Message Protocol ### Standard Message Format ```markdown ## Agent Message **From:** /[sender-agent] **To:** /[recipient-agent] **Type:** [Request/Response/Notification/Feedback/Handoff/Query/Alert] **Priority:** [High/Normal/Low] **Timestamp:** [ISO timestamp] **Thread ID:** [conversation-id] (for tracking related messages) --- ### Subject [Brief description of the message purpose] ### Context [Relevant background the recipient needs] ### Content [The actual message/request/feedback] ### Attachments - [File references if any] - [Code snippets if any] ### Expected Response [What kind of response is expected, if any] ### Deadline [When response is needed, if applicable] --- **Message ID:** msg-[timestamp]-[random] **Status:** Sent / Delivered / Read / Responded ``` --- ## 🔄 Communication Patterns ### Pattern 1: Review Request > 📎 **Code example 1** (markdown) — see [references/examples.md](references/examples.md) ### Pattern 2: Handoff > 📎 **Code example 2** (markdown) — see [references/examples.md](references/examples.md) ### Pattern 3: Feedback Loop > 📎 **Code example 3** (markdown) — see [references/examples.md](references/examples.md) ### Pattern 4: Collaborative Problem Solving > 📎 **Code example 4** (markdown) — see [references/examples.md](references/examples.md) --- ## 📋 Message Templates ### Review Request Template ```markdown 📨 Review Request **From:** /[your-agent] **To:** /[reviewer-agent] **Type:** Request **Priority:** [High/Normal/Low] ### What to Review [Brief description] ### Files/Components - [file1.ts] - [what it does] - [file2.tsx] - [what it does] ### Specific Concerns - [Area you're unsure about] - [Specific question] ### Context [Background information reviewer needs] ### Deadline [When you need the review by] ``` ### Handoff Template ```markdown 🤝 Handoff **From:** /[your-agent] **To:** /[receiving-agent] **Type:** Handoff ### What's Being Handed Off [Clear description] ### Deliverables - [Deliverable 1] - [location/link] - [Deliverable 2] - [location/link] ### Current State - [x] [Completed item] - [x] [Completed item] - [ ] [Remaining for recipient] ### Important Notes - [Key information] - [Gotchas to watch out for] - [Dependencies] ### Next Steps for Recipient 1. [First thing to do] 2. [Second thing to do] 3. [Third thing to do] ### Questions/Support [How to reach you for questions] ``` ### Feedback Template ```markdown 💬 Feedback **From:** /[your-agent] **To:** /[recipient-agent] **Type:** Feedback **Regarding:** [What you're giving feedback on] ### Summary [Overall assessment: Positive/Mixed/Needs Work] ### What's Good ✅ - [Positive point] - [Positive point] ### Suggestions ⚠️ - [Suggestion with rationale] - [Suggestion with rationale] ### Critical Issues 🔴 - [Issue that must be addressed] ### Optional Improvements 💡 - [Nice to have] ### Next Steps [What should happen with this feedback] ``` --- ## 🔀 Conflict Resolution ### When Agents Disagree ```markdown ## Conflict Resolution Protocol **Conflict:** [Description of disagreement] **Parties:** /agent-a, /agent-b ### Step 1: Document Positions **Position A (/agent-a):** [Their view and reasoning] **Position B (/agent-b):** [Their view and reasoning] ### Step 2: Identify Common Ground - Both agree on: [shared points] - Core disagreement: [the actual conflict] ### Step 3: Evaluate Options | Option | Pros | Cons | Supported By | |--------|------|------|--------------| | A's approach | [...] | [...] | /agent-a | | B's approach | [...] | [...] | /agent-b | | Compromise | [...] | [...] | - | ### Step 4: Resolution **Method:** [Escalate to coordinator / Compromise / Domain expertise wins] **Decision:** [What was decided] **Rationale:** [Why] **Accepted by:** [Both parties] ### Step 5: Document for Future - This pattern should be handled as: [guideline] - Add to: [relevant documentation] ``` --- ## 📊 Communication Tracking ### Message Log ```markdown ## Communication Log **Session:** [session-id] **Date:** [date] | Time | From | To | Type | Subject | Status | |------|------|-----|------|---------|--------| | 10:00 | /backend-architect | /security-auditor | Request | Security review | ✅ Responded | | 10:30 | /security-auditor | /backend-architect | Response | Review complete | ✅ Read | | 11:00 | /backend-architect | /frontend-specialist | Handoff | API ready | ✅ Acknowledged | | 11:15 | /frontend-specialist | /backend-architect | Query | Pagination question | ⏳ Pending | **Statistics:** - Total messages: 4 - Avg response time: 15 min - Pending responses: 1 ``` ### Communication Health ```markdown ## Communication Health Report **Period:** Last 7 days ### Response Metrics - Messages sent: 45 - Messages responded: 42 (93%) - Avg response time: 18 min - Longest wait: 2h 15min ### By Agent | Agent | Sent | Received | Response Rate | Avg Time | |-------|------|----------|---------------|----------| | /backend-architect | 15 | 12 | 100% | 10 min | | /frontend-specialist | 10 | 8 | 87% | 25 min | | /security-auditor | 8 | 10 | 100% | 15 min | ### Issues Detected ⚠️ /frontend-specialist has 1 pending response (>2h) ⚠️ 3 messages had no acknowledgment ### Recommendations - Follow up on pending response - Establish acknowledgment protocol ``` --- ## 🔄 Self-Review Protocol Before sending any message: ```markdown ## Message Quality Check **Clarity:** - [ ] Subject is clear and specific - [ ] Context is sufficient for recipient - [ ] Action required is explicit - [ ] Deadline is stated if applicable **Completeness:** - [ ] All necessary information included - [ ] Files/links attached - [ ] Questions are specific **Appropriateness:** - [ ] Right recipient(s) - [ ] Correct message type - [ ] Priority accurately set - [ ] Tone is professional **Actionability:** - [ ] Recipient knows what to do - [ ] Expected response is clear - [ ] Follow-up plan if no response ``` --- ## 📋 Structured Output ```json { "message": { "id": "msg-20251129-143000-abc", "from": "backend-architect", "to": ["security-auditor"], "type": "request", "priority": "high", "timestamp": "2025-11-29T14:30:00Z", "thread_id": "thread-auth-review", "subject": "Security review for auth module", "content": "...", "attachments": ["src/auth/auth.py"], "expected_response": "review_feedback", "deadline": "2025-11-29T18:00:00Z", "status": "sent" }, "tracking": { "delivered_at": null, "read_at": null, "responded_at": null } } ``` --- ## 💡 Usage Examples ### Request a Review ``` /agent-communicator Send review request to /security-auditor for auth.py ``` ### Handoff Work ``` /agent-communicator Create handoff from /backend-architect to /frontend-specialist for API integration ``` ### Start Discussion ``` /agent-communicator Start collaborative discussion about caching strategy with /backend-architect, /devops-engineer ``` ### Check Communication Status ``` /agent-communicator Show pending messages and response status ``` --- ## 🎓 Best Practices 1. **Be specific** - Vague messages waste time 2. **Include context** - Recipients aren't mind readers 3. **Set expectations** - Deadlines and response types 4. **Acknowledge receipt** - Confirm messages received 5. **Close loops** - Follow up on open threads 6. **Document decisions** - Future reference 7. **Escalate appropriately** - Don't let conflicts fester --- *Inter-Agent Communication patterns from Actor Model, Message Queues, and distributed systems best practices* ## Reference Materials For detailed code examples and implementation patterns, see [references/examples.md](references/examples.md).

path: references/examples.md
content: # Agent Communicator — Code Examples

## Example 1

```markdown
## Review Request Flow

**Initiator:** /python-pro
**Reviewer:** /security-auditor

### Step 1: Request
📨 /python-pro → /security-auditor

Subject: Security review needed for auth module
Context: Implemented JWT authentication
Content: Please review auth.py for security issues
Files: src/auth/auth.py, src/auth/jwt_handler.py
Deadline: Before merge

### Step 2: Acknowledgment
📩 /security-auditor → /python-pro

Status: Review started
ETA: 30 minutes

### Step 3: Review Complete
📩 /security-auditor → /python-pro

Subject: Security review complete
Findings:
- 🔴 Critical: Token expiry not enforced (line 45)
- 🟡 Medium: Consider rate limiting (line 78)
- 🟢 Good: Proper password hashing

Action Required: Fix critical issue before merge

### Step 4: Resolution
📨 /python-pro → /security-auditor

Subject: Issues addressed
Content: Fixed token expiry, added rate limiting
Request: Re-review please

### Step 5: Approval
📩 /security-auditor → /python-pro

Subject: ✅ Approved
Content: All issues resolved, ready for merge
```

## Example 2

```markdown
## Handoff Flow

**From:** /backend-architect
**To:** /frontend-specialist

### Handoff Message
🤝 /backend-architect → /frontend-specialist

Subject: API ready for frontend integration
Context: User management API complete

**Deliverables:**
- OpenAPI spec: docs/api/users.yaml
- Base URL: /api/v1/users
- Auth: Bearer token required

**Endpoints:**
| Method | Path | Purpose |
|--------|------|---------|
| GET | /users | List users |
| GET | /users/:id | Get user |
| POST | /users | Create user |
| PUT | /users/:id | Update user |
| DELETE | /users/:id | Delete user |

**Notes:**
- Rate limit: 100 req/min
- Pagination: offset/limit params
- Error format: { error: string, code: number }

**Your tasks:**
1. Implement user list page
2. Implement user detail page
3. Implement user forms (create/edit)

**Questions?** Reply to this thread

### Acknowledgment
📩 /frontend-specialist → /backend-architect

Subject: Handoff received
Status: Starting implementation
Questions:
- Is there a search endpoint?
- What's the max page size?

### Clarification
📨 /backend-architect → /frontend-specialist

Answers:
- Search: GET /users?search=query
- Max page size: 100 items

Updated docs attached.
```

## Example 3

```markdown
## Feedback Loop Flow

**Designer:** /ux-designer
**Implementer:** /react-pro
**Reviewer:** /code-reviewer

### Initial Implementation
📢 /react-pro → [broadcast]

Subject: Dashboard component ready for review
Status: First implementation complete
Preview: localhost:3000/dashboard

### Design Feedback
💬 /ux-designer → /react-pro

Subject: Design feedback
Feedback:
- ✅ Layout matches wireframes
- ⚠️ Spacing inconsistent (use 8px grid)
- ⚠️ Colors slightly off (use design tokens)
- 💡 Consider adding loading skeleton

### Code Feedback
💬 /code-reviewer → /react-pro

Subject: Code review feedback
Feedback:
- ✅ Component structure good
- ⚠️ Extract repeated styles to shared components
- ⚠️ Add error boundary
- 💡 Consider React.memo for performance

### Iteration
📨 /react-pro → /ux-designer, /code-reviewer

Subject: Feedback addressed
Changes:
- Fixed spacing to 8px grid
- Applied design tokens
- Extracted shared styles
- Added error boundary
- Added loading skeleton

Request: Final review please

### Approval
💬 /ux-designer → /react-pro
Subject: ✅ Design approved

💬 /code-reviewer → /react-pro
Subject: ✅ Code approved

Ready for merge!
```

## Example 4

```markdown
## Collaborative Discussion

**Participants:** /backend-architect, /frontend-specialist, /security-auditor
**Topic:** Real-time updates implementation

### Discussion Thread

📨 /backend-architect [Thread Start]
Subject: How should we implement real-time updates?

Options:
1. WebSockets - bidirectional, complex
2. SSE - simpler, one-way
3. Polling - simplest, more load

My take: WebSockets for flexibility

---

💬 /frontend-specialist
Re: Real-time updates

Prefer SSE for our use case:
- We only need server → client
- Simpler to implement
- Better browser support
- Auto-reconnect built-in

---

💬 /security-auditor
Re: Real-time updates

Security considerations:
- WebSockets: Need to secure the upgrade
- SSE: Uses existing auth, easier
- Both: Rate limiting required

Recommendation: SSE is safer for our team's experience level

---

📨 /backend-architect
Subject: Decision: Using SSE

Based on feedback:
- SSE chosen for simplicity and security
- Will implement with auth token validation
- Rate limit: 1 connection per user

@/frontend-specialist - Can you handle SSE client?
@/security-auditor - Please review implementation

---

📩 /frontend-specialist
Confirmed: Will implement EventSource client

📩 /security-auditor
Confirmed: Will review when ready
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)