agent-collaboration

Design effective collaboration between humans and AI agents where strengths combine and weaknesses complement. Use when building agent systems that require human judgment, creating effective handoff p

SKILL.md

GitHub

Agent Human-AI Collaboration

The most effective systems aren't fully autonomous agents nor fully manual processes—they're collaborative. This skill covers designing human-AI partnerships that leverage each party's strengths.

Collaboration Strengths & Weaknesses

What Humans Do Better

  • Judgment calls: Values, tradeoffs, context-specific decisions
  • Nuance: Recognizing exceptions, seeing beyond data
  • Creativity: Generating novel solutions and approaches
  • Empathy: Understanding emotional and relational aspects
  • Ethics: Navigating moral complexity and ambiguity
  • Learning: Adapting quickly to new situations
  • Accountability: Taking responsibility for outcomes
  • Stakeholder management: Building trust and buy-in

What AI Agents Do Better

  • Scale: Process 1M records faster than any human
  • Speed: Answer in seconds what takes humans hours
  • Consistency: Apply same rules uniformly, no fatigue
  • Memory: Recall facts perfectly, no forgetting
  • Tireless: 24/7 availability, no vacation or sick days
  • Analysis: Spot patterns across massive datasets
  • Brainstorming: Generate many alternatives quickly
  • Execution: Perform repetitive tasks perfectly
  • Integration: Connect across many systems seamlessly

The Collaboration Advantage

TASK: Improve product recommendation system

HUMAN ALONE:
- Can't analyze 10M historical purchases
- Can't test 1000 algorithms
- Can identify best direction through intuition
- Limited by time

AI ALONE:
- Can analyze all 10M purchases
- Can test all 1000 algorithms
- Might miss novel insights
- Might over-optimize on metrics

TOGETHER:
- Human: "Focus on retention, not just conversion"
- AI: Analyzes 10M purchases with retention focus
- Human: Reviews AI's top 5 recommendations
- AI: Tests each recommendation on new data
- Result: Better system + faster development

Human-in-the-Loop Patterns

Pattern 1: AI Recommends, Human Decides

When to use: Important decisions, significant impact, clear reversibility

WORKFLOW:
Step 1: AI analyzes situation
Step 2: AI generates recommendation(s)
Step 3: AI explains reasoning
Step 4: Human reviews recommendation
Step 5: Human decides (approve/reject/modify)
Step 6: AI executes human decision

EXAMPLE: Loan approval
- Agent analyzes application (income, credit history, debt)
- Agent recommends: "Approve $250K loan at 5.2% rate"
- Agent explains: "Debt-to-income 0.32 (below 0.43 threshold), credit 750+"
- Human officer reviews
- Officer decides: "Approve $200K instead (more conservative)"
- Agent processes approval

Design for this pattern:

  • ✓ Clear recommendation (not ambiguous)
  • ✓ Reasoning is transparent and auditable
  • ✓ Explanation is concise (human's time is valuable)
  • ✓ Alternatives shown for context
  • ✓ Easy human override
  • ✓ Decision logged for accountability

Pattern 2: AI Executes, Human Monitors

When to use: Repetitive tasks, clear success criteria, easy to detect errors

WORKFLOW:
Step 1: Human sets parameters/rules
Step 2: AI executes autonomously
Step 3: AI reports progress/exceptions
Step 4: Human monitors for issues
Step 5: If anomaly, human intervenes
Step 6: Learnings improve rules for next time

EXAMPLE: Customer support triage
- Human defines: "Route complaints to X team, inquiries to Y team, feedback to Z"
- Agent automatically routes 1000 emails
- Agent reports: "99 correctly routed, 1 uncertain (flag for review)"
- Human spot-checks reports and exceptions
- Human adjusts rules based on any mistakes
- Next time, agent gets better

Design for this pattern:

  • ✓ AI exceptions are flagged (not silent failures)
  • ✓ Monitoring dashboard shows status
  • ✓ Human can intervene quickly
  • ✓ Error cases logged for improvement
  • ✓ Rules are easy to adjust

Pattern 3: Collaborative Ideation

When to use: Creative problem-solving, multiple perspectives valuable, exploration needed

WORKFLOW:
Step 1: Human articulates problem/goal
Step 2: AI generates multiple approaches (no judgment)
Step 3: Human selects promising directions
Step 4: AI elaborates on each direction
Step 5: Human refines selections
Step 6: AI prototypes or implements chosen direction

EXAMPLE: Marketing campaign
- Human: "Need holiday campaign for 18-35 demographic"
- AI generates: 10 completely different concepts (emotional, rational, humorous, etc.)
- Human picks: 3 most promising
- AI elaborates: Develops each concept with specific tactics, budget, timeline
- Human refines: "Combine concept A's emotional core with concept B's timing"
- AI: Implements refined campaign

Benefits:
- AI shows possibilities human might not consider
- Human applies judgment on what's appropriate
- Faster iteration than either working alone

Pattern 4: AI Prepares, Human Decides

When to use: Complex information, synthesis needed, human expertise valuable

WORKFLOW:
Step 1: AI gathers and organizes information
Step 2: AI surfaces key insights/questions
Step 3: AI prepares options with trade-offs
Step 4: Human reviews and reasons through decision
Step 5: Human decides based on informed judgment
Step 6: AI handles implementation details

EXAMPLE: Product roadmap prioritization
- AI gathers: Feature requests, bug reports, competitor analysis, engineering estimates
- AI surfaces: "3 major themes emerged from requests; engineering split 50/50 on approach"
- AI prepares: Option A (user feature focus), Option B (stability focus), Option C (competitor response)
- AI shows: Each option's trade-offs in user satisfaction, technical debt, time to market
- Human product manager reviews and decides: "Go with hybrid: 60% features, 40% stability"
- AI: Updates roadmap, tracks execution, reports progress

Pattern 5: AI Escalates, Human Judges

When to use: Edge cases, novel situations, stakes too high for AI

WORKFLOW:
Step 1: AI encounters situation it's uncertain about
Step 2: AI escalates to human with full context
Step 3: Human judges the situation (first-time or routine?)
Step 4: If routine, human sets rule for future
Step 5: If novel, human decides case-by-case
Step 6: AI learns and improves detection

EXAMPLE: Content moderation
- Agent encounters post: Ambiguous message that could be policy-violating
- Agent confidence: 45% (below 70% threshold)
- Agent escalates: Shows post + why it's unclear + what rules suggest + alternatives
- Human moderator: "This is similar to [previous case]; I'll set a rule"
- Agent: Stores rule for similar future content
- Or: "This is unique; I'll decide this time manually; unclear for others"
- Agent: Improves clarity around this edge case for future escalations

Designing for Human Understanding

Principle 1: Transparency Over Authority

Goal: Help humans understand and reason, not just obey

POOR APPROACH:
Agent: "You should do X"
Human: "Why?"
Agent: "It's optimal"

BETTER APPROACH:
Agent: "I recommend X because:
- Data shows X succeeds 85% vs Y at 60%
- X aligns with your stated priority of speed
- X has lower implementation cost
- Y would be better for long-term flexibility
Given your constraints, X is better in near term"

Principle 2: Show Your Work

Goal: Make reasoning auditable and checkable

WORK TO SHOW:
1. What data did you use? (Source, recency, coverage)
2. What assumptions did you make? (State them explicitly)
3. What did you consider? (Not just winner; also alternatives)
4. Where are you uncertain? (Confidence intervals, edge cases)
5. What could go wrong? (Risks and mitigations)

FORMAT:
Agent explains before recommending:
"I analyzed 150 historical cases:
- Success rate with approach A: 78% (95% CI: 72-84%)
- Success rate with approach B: 65% (95% CI: 58-72%)

Key assumption: Past patterns continue (market stable)
If market changes: Approaches might flip

Risks with A: Higher cost upfront
Risks with B: Longer timeline

I recommend A, but B is reasonable if you prioritize budget"

Principle 3: Calibrated Confidence

Goal: Human knows when to trust agent vs. verify

HIGH CONFIDENCE (80-95%):
"Based on clear pattern in data"
Example: "95% of accounts with 3+ failed logins get compromised within 7 days"
→ Human: Can probably trust for routine decisions

MEDIUM CONFIDENCE (50-80%):
"Evidence is mixed or situation is partially novel"
Example: "65% of features like this succeed (but your market is different)"
→ Human: Should double-check before high-stakes decisions

LOW CONFIDENCE (<50%):
"Situation is novel or data is sparse"
Example: "We've never done this before; similar companies had 40-60% success"
→ Human: Should get human expertise before deciding

Implementation:

Agent ALWAYS reports confidence:
"I recommend X (confidence: 85%)"

If confidence < threshold:
"I have low confidence here. I'd recommend human review.
I see 3 possible approaches; here's how they'd each work..."

Principle 4: Explainability Layers

Goal: Provide explanation depth human needs, not more/less

LAYER 1 - SUMMARY (30 seconds):
"Based on the data, customers in segment A like feature X
and customers in segment B prefer feature Y.
I recommend prioritizing segment A because they're higher-value."

LAYER 2 - EXPLANATION (2-3 minutes):
"Here's what I analyzed:
- Customer segments: Grouped by 5 characteristics
- Feature preferences: Analyzed 10K survey responses
- Value calculation: Weighted by revenue and growth rate
- Recommendation: Segment A (80% of revenue) prefers X
- Confidence: 82% based on 3K respondents"

LAYER 3 - DEEP DIVE (10-15 minutes):
"Full methodology:
- Statistical methods used: [details]
- Data limitations: [coverage, gaps]
- Alternative interpretations: [what I rejected and why]
- Code/formulas: [if they want to verify]
- Raw data: [links if they want to explore]"

Human chooses depth needed for decision

Collaboration Workflow Patterns

Pattern 1: Discovery Phase (AI Assists Human Exploration)

TYPICAL WORKFLOW:
Human: "What should we charge for this product?"
Agent: Gathers pricing data:
  - Competitor prices: $50-200 range
  - Value proposition: 50% time savings
  - Willingness to pay survey: Mean $150 (std $40)
  - Cost to deliver: $20/unit
Agent: "Here's what I found" [summarizes]
Human: "How much are customers willing to spend monthly?"
Agent: Reanalyzes for monthly pricing
  - Monthly adoption: Data suggests 70% of annual pay over 12 months
  - Price sensitivity: Steeper for >$200/month
Agent: "Suggests monthly pricing around $110-150"
Human: "What if we added premium tier?"
Agent: Analyzes 3-tier pricing model
  - Finds segmentation: 70% use basic, 25% use plus, 5% use premium
  - Recommends pricing: Basic $99, Plus $199, Premium $499

Result: Collaborative decision, much better than either alone

Pattern 2: Execution Phase (AI Handles Details, Human Oversees)

TYPICAL WORKFLOW:
Human: "Execute the pricing change, monitor for issues"
Agent:
  ✓ Day 1: Updates pricing in 5 systems
  ✓ Notifies customers of change
  ✓ Tracks first 100 sales: All successful
  ✗ Flag: 5% higher refund rate than baseline
  ? Question: Data system failed to update; using cache

Agent: "Execution 95% complete. 2 issues need attention:
  1. [Refund rate increase] - Should I investigate deeper?
  2. [Data system lag] - Impacting real-time reporting"