{"id":"901bc963-93bd-4fd8-baf8-0ff473437b83","shortId":"pGbXpm","kind":"skill","title":"talk-to-agent","tagline":"Use this skill when the user wants to contact another person's Aicoo agent (agent-to-agent RPC), send human inbox messages, request/accept agent access, bridge from share links to friend+agent connections, or chat via public share link (`/a/<token>`). Triggers on: 'contact their ","description":"# Talk to Agent — Unified Message Route + Handshake + Link Bridge + Share Link\n\nUse this skill when the user wants AI-to-AI communication in Aicoo.\n\nAicoo supports four related flows:\n\n1. `Unified Message Route` (`/v1/agent/message`)\n2. `Friend Request Handshake` (`/v1/network/request|requests|accept`)\n3. `Share Link -> Friend+Agent Bridge` (`/v1/network/connect`)\n4. `Share Link Guest` (`/api/chat/guest-v04`)\n\n## Channel Selection\n\n| Channel | Use when | Auth | Endpoint |\n|---|---|---|---|\n| Unified Message Route | You want one endpoint for human inbox and agent RPC | API key | `POST /api/v1/agent/message` |\n| Friend Request Handshake | You do not have agent access yet | API key | `POST /api/v1/network/request`, `GET /api/v1/network/requests`, `POST /api/v1/network/accept` |\n| Link Bridge | You have a share token and want instant friend+agent connection | API key | `POST /api/v1/network/connect` |\n| Share Link Guest | You only have a shared link (`https://www.aicoo.io/a/<token>`) | No API key for anonymous links; API key or browser session for `requireSignIn:true` | `GET/POST /api/chat/guest-v04` |\n\n---\n\n## Channel A: Unified Message Route (`/v1/agent/message`)\n\n### A1) Discover reachable contacts\n\n```bash\ncurl -s \"https://www.aicoo.io/api/v1/network\" \\\n  -H \"Authorization: Bearer $AICOO_API_KEY\" | jq .\n```\n\nLook at `network.contacts` for usernames and direction (`mutual`, `inbound`, `outbound`).\n\n### A2) Send to agent (`username_coo`)\n\nUse `_coo` suffix for agent RPC:\n\n```bash\ncurl -s -X POST \"https://www.aicoo.io/api/v1/agent/message\" \\\n  -H \"Authorization: Bearer $AICOO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"to\": \"alice_coo\",\n    \"message\": \"Hi, can you summarize what Alice is focused on this week?\",\n    \"intent\": \"query\"\n  }' | jq .\n```\n\nExpected response shape:\n\n```json\n{\n  \"success\": true,\n  \"agentName\": \"Alice's AI COO\",\n  \"ownerName\": \"Alice\",\n  \"response\": \"...\",\n  \"toolsUsed\": 0,\n  \"conversationId\": 1234\n}\n```\n\nExpected response shape (agent RPC):\n\n```json\n{\n  \"success\": true,\n  \"mode\": \"agent\",\n  \"agentName\": \"Alice's AI COO\",\n  \"ownerName\": \"Alice\",\n  \"response\": \"...\",\n  \"toolsUsed\": 0,\n  \"conversationId\": 1234\n}\n```\n\n### A3) Send to human inbox (`username`)\n\nUse plain username for human delivery (no AI response):\n\n```bash\ncurl -s -X POST \"https://www.aicoo.io/api/v1/agent/message\" \\\n  -H \"Authorization: Bearer $AICOO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"to\": \"alice\",\n    \"message\": \"Meeting starts in 30 minutes.\",\n    \"intent\": \"inform\"\n  }' | jq .\n```\n\nExpected response shape (human delivery):\n\n```json\n{\n  \"success\": true,\n  \"mode\": \"human\",\n  \"delivered\": true,\n  \"response\": null\n}\n```\n\n### A4) Internal tool routing (Aicoo agent runtime)\n\nInside Aicoo agent runtime, use:\n\n- `contact_agent` for agent-to-agent request/response (waits for reply)\n- `send_message_to_human` for human inbox fire-and-forget\n\nDo not use `send_message_to_human` when user asks for agent dialogue.\n\n---\n\n## Channel B: Friend Request Handshake\n\nIf `alice_coo` returns 403, request access first.\n\n### B1) Send request\n\n- `alice` -> friend request\n- `alice_coo` -> agent access request\n\n```bash\ncurl -s -X POST \"https://www.aicoo.io/api/v1/network/request\" \\\n  -H \"Authorization: Bearer $AICOO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"to\": \"alice_coo\" }' | jq .\n```\n\n### B2) Check pending\n\n```bash\ncurl -s \"https://www.aicoo.io/api/v1/network/requests\" \\\n  -H \"Authorization: Bearer $AICOO_API_KEY\" | jq .\n```\n\n### B3) Accept or reject incoming\n\n```bash\ncurl -s -X POST \"https://www.aicoo.io/api/v1/network/accept\" \\\n  -H \"Authorization: Bearer $AICOO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"requestId\": 42,\n    \"type\": \"agent\",\n    \"action\": \"accept\",\n    \"permissions\": {\n      \"notesAccess\": { \"scope\": \"all\", \"access\": \"read\" },\n      \"calendarAccess\": { \"read\": \"free_busy\", \"write\": false },\n      \"emailAccess\": { \"read\": false },\n      \"todoAccess\": { \"read\": false, \"create\": false }\n    }\n  }' | jq .\n```\n\n---\n\n## Channel C: Share Link -> Friend+Agent Bridge\n\nIf you already have a share token, connect instantly without waiting for request/accept:\n\n```bash\ncurl -s -X POST \"https://www.aicoo.io/api/v1/network/connect\" \\\n  -H \"Authorization: Bearer $AICOO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"shareToken\": \"MwFyATaW0w\" }' | jq .\n```\n\nThis creates:\n- friendship (bidirectional)\n- agent permission (owner -> you) using link metadata defaults\n- shared_agent conversation\n\n---\n\n## Channel D: Share Link Guest (Public Sandbox)\n\nUse this when you only have an `aicoo.io/a/<token>` link. If the link has `requireSignIn:false`, anonymous guest access works as before. If the link has `requireSignIn:true`, call `guest-v04` with either a browser session cookie or an Aicoo API key; the API key is treated as the caller's signed-in identity. Use `POST /api/v1/network/connect` when the user wants to turn the link into a durable friend + agent connection.\n\n### C1) Inspect link metadata\n\n```bash\ncurl -s \"https://www.aicoo.io/api/chat/guest-v04?token=<TOKEN>&meta=true\" | jq .\n```\n\n### C2) Send message (JSON mode)\n\n```bash\ncurl -s -X POST \"https://www.aicoo.io/api/chat/guest-v04\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"token\": \"<TOKEN>\",\n    \"message\": \"What can you help with?\",\n    \"stream\": false\n  }' | jq .\n```\n\nKeep `sessionKey` for multi-turn continuation.\n\nFor `requireSignIn:true` links from Claude Code or another headless agent, include the caller's API key:\n\n```bash\ncurl -s -X POST \"https://www.aicoo.io/api/chat/guest-v04\" \\\n  -H \"Authorization: Bearer $AICOO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"token\": \"<TOKEN>\",\n    \"message\": \"What can you help with?\",\n    \"stream\": false\n  }' | jq .\n```\n\n---\n\n## Error Handling\n\n| Status | Meaning | Action |\n|---|---|---|\n| 401 | Share link requires sign-in (`requireSignIn:true`) | Open `/a/<token>` in browser and sign in, pass `Authorization: Bearer $AICOO_API_KEY` to `guest-v04`, or use `POST /v1/network/connect` for durable access |\n| 403 | No agent access to target agent (`<username>_coo`) | Use `POST /v1/network/request` or `POST /v1/network/connect` if token exists |\n| 404 | User or link not found | Verify username/token |\n| 429 | Rate/message limit hit | Retry later |\n| 500 | Server error | Retry once, then surface error |\n\n---\n\n## Practical Patterns\n\n### Pattern 1: Fast A2A query\n\n1. `GET /v1/network` to confirm username\n2. `POST /v1/agent/message` to `<username>_coo`\n3. Return `response` to user\n\n### Pattern 2: Human escalation from agent runtime\n\nIf user asks to notify the person (not their agent), use `send_message_to_human` tool from Aicoo runtime.\n\n### Pattern 3: No relationship yet\n\nIf direct channel fails with 403:\n\n1. `POST /v1/network/request` to `<username>_coo`\n2. Wait for acceptance (`GET /v1/network/requests`)\n3. Retry `POST /v1/agent/message`\n\n### Pattern 4: Fast bridge from link\n\n1. `POST /v1/network/connect` with `shareToken`\n2. Call `POST /v1/agent/message` to `<username>_coo`\n3. Continue on private channel instead of guest link\n\n---\n\n## Security Notes\n\n- Friend Agent Direct is permission-gated and private.\n- Share links are sandboxed by link capabilities; anonymous guest chat only works when `requireSignIn:false`, while `requireSignIn:true` requires a browser session or the caller's API key.\n- Never expose `AICOO_API_KEY` or legacy `PULSE_API_KEY` in outputs.\n- Use `_coo` for agent targets in `/v1/agent/message` and for agent access requests in `/v1/network/request`.","tags":["talk","agent","aicoo","skills","aicoo-team","agent-skills","agentic-ai"],"capabilities":["skill","source-aicoo-team","skill-talk-to-agent","topic-agent","topic-agent-skills","topic-agentic-ai"],"categories":["AICOO-Skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Aicoo-Team/AICOO-Skills/talk-to-agent","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Aicoo-Team/AICOO-Skills","source_repo":"https://github.com/Aicoo-Team/AICOO-Skills","install_from":"skills.sh"}},"qualityScore":"0.456","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 12 github stars · SKILL.md body (7,581 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:07:07.768Z","embedding":null,"createdAt":"2026-05-09T01:05:26.385Z","updatedAt":"2026-05-18T19:07:07.768Z","lastSeenAt":"2026-05-18T19:07:07.768Z","tsv":"'/a':45,787 '/a/':174,611 '/api/chat/guest-v04':103,190,701,749 '/api/chat/guest-v04?token=':685 '/api/v1/agent/message':127,243,336 '/api/v1/network':206 '/api/v1/network/accept':145,497 '/api/v1/network/connect':162,564,661 '/api/v1/network/request':141,452 '/api/v1/network/requests':143,477 '/v1/agent/message':84,196,864,923,938,1007 '/v1/network':858 '/v1/network/connect':98,806,823,932 '/v1/network/request':89,820,911,1014 '/v1/network/requests':919 '0':289,311 '1':80,852,856,909,930 '1234':291,313 '2':85,862,873,914,935 '3':92,867,899,920,941 '30':355 '4':99,925 '401':777 '403':430,810,908 '404':827 '42':511 '429':835 '500':841 'a1':197 'a2':224 'a2a':854 'a3':314 'a4':374 'accept':91,486,515,917 'access':30,136,432,443,520,621,809,813,1011 'action':514,776 'agent':4,18,20,22,29,37,52,96,122,135,157,227,234,295,301,379,383,387,390,392,419,442,513,542,584,593,674,735,812,816,877,888,953,1004,1010 'agent-to-ag':19,389 'agentnam':280,302 'ai':69,71,283,305,327 'ai-to-ai':68 'aicoo':17,74,75,210,247,340,378,382,456,481,501,568,643,753,796,896,991 'aicoo.io':610 'aicoo.io/a/':609 'alic':257,265,281,286,303,308,350,427,437,440,466 'alreadi':546 'anonym':179,619,968 'anoth':14,733 'api':124,138,159,176,181,211,248,341,457,482,502,569,644,647,740,754,797,987,992,997 'application/json':254,347,463,508,575,706,760 'ask':417,881 'auth':109 'author':208,245,338,454,479,499,566,751,794 'b':422 'b1':434 'b2':469 'b3':485 'bash':201,236,329,445,472,490,557,680,694,742 'bearer':209,246,339,455,480,500,567,752,795 'bidirect':583 'bridg':31,58,97,147,543,927 'browser':184,638,789,981 'busi':525 'c':538 'c1':676 'c2':689 'calendaraccess':522 'call':631,936 'caller':653,738,985 'capabl':967 'channel':104,106,191,421,537,595,905,945 'chat':40,970 'check':470 'claud':730 'code':731 'communic':72 'confirm':860 'connect':38,158,551,675 'contact':13,48,200,386 'content':252,345,461,506,573,704,758 'content-typ':251,344,460,505,572,703,757 'continu':724,942 'convers':594 'conversationid':290,312 'coo':229,231,258,284,306,428,441,467,817,866,913,940,1002 'cooki':640 'creat':534,581 'curl':202,237,330,446,473,491,558,681,695,743 'd':255,348,464,509,576,596,707,761 'default':591 'deliv':370 'deliveri':325,364 'dialogu':420 'direct':220,904,954 'discov':198 'durabl':672,808 'either':636 'emailaccess':528 'endpoint':110,117 'error':772,843,848 'escal':875 'exist':826 'expect':274,292,360 'expos':990 'fail':906 'fals':527,530,533,535,618,716,770,975 'fast':853,926 'fire':405 'fire-and-forget':404 'first':433 'flow':79 'focus':267 'forget':407 'found':832 'four':77 'free':524 'friend':36,86,95,128,156,423,438,541,673,952 'friendship':582 'gate':958 'get':142,857,918 'get/post':189 'guest':102,165,599,620,633,801,948,969 'guest-v04':632,800 'h':207,244,250,337,343,453,459,478,498,504,565,571,702,750,756 'handl':773 'handshak':56,88,130,425 'headless':734 'help':713,767 'hi':260 'hit':838 'human':25,119,317,324,363,369,400,402,414,874,893 'ident':658 'inbound':222 'inbox':26,120,318,403 'includ':736 'incom':489 'inform':358 'insid':381 'inspect':677 'instant':155,552 'instead':946 'intent':271,357 'intern':375 'jq':213,273,359,468,484,536,579,688,717,771 'json':277,297,365,692 'keep':718 'key':125,139,160,177,182,212,249,342,458,483,503,570,645,648,741,755,798,988,993,998 'later':840 'legaci':995 'limit':837 'link':34,44,57,60,94,101,146,164,171,180,540,589,598,612,615,627,669,678,728,779,830,929,949,962,966 'look':214 'mean':775 'meet':352 'messag':27,54,82,112,194,259,351,398,412,691,709,763,891 'meta':686 'metadata':590,679 'minut':356 'mode':300,368,693 'multi':722 'multi-turn':721 'mutual':221 'mwfyataw0w':578 'network.contacts':216 'never':989 'note':951 'notesaccess':517 'notifi':883 'null':373 'one':116 'open':786 'outbound':223 'output':1000 'owner':586 'ownernam':285,307 'pass':793 'pattern':850,851,872,898,924 'pend':471 'permiss':516,585,957 'permission-g':956 'person':15,885 'plain':321 'post':126,140,144,161,240,333,449,494,561,660,698,746,805,819,822,863,910,922,931,937 'practic':849 'privat':944,960 'public':42,600 'puls':996 'queri':272,855 'rate/message':836 'reachabl':199 'read':521,523,529,532 'reject':488 'relat':78 'relationship':901 'repli':396 'request':87,90,129,424,431,436,439,444,1012 'request/accept':28,556 'request/response':393 'requestid':510 'requir':780,979 'requiresignin':187,617,629,726,784,974,977 'respons':275,287,293,309,328,361,372,869 'retri':839,844,921 'return':429,868 'rout':55,83,113,195,377 'rpc':23,123,235,296 'runtim':380,384,878,897 'sandbox':601,964 'scope':518 'secur':950 'select':105 'send':24,225,315,397,411,435,690,890 'server':842 'session':185,639,982 'sessionkey':719 'shape':276,294,362 'share':33,43,59,93,100,151,163,170,539,549,592,597,778,961 'sharetoken':577,934 'sign':656,782,791 'sign-in':781 'signed-in':655 'skill':7,63 'skill-talk-to-agent' 'source-aicoo-team' 'start':353 'status':774 'stream':715,769 'success':278,298,366 'suffix':232 'summar':263 'support':76 'surfac':847 'talk':2,50 'talk-to-ag':1 'target':815,1005 'todoaccess':531 'token':152,550,708,762,825 'tool':376,894 'toolsus':288,310 'topic-agent' 'topic-agent-skills' 'topic-agentic-ai' 'treat':650 'trigger':46 'true':188,279,299,367,371,630,687,727,785,978 'turn':667,723 'type':253,346,462,507,512,574,705,759 'unifi':53,81,111,193 'use':5,61,107,230,320,385,410,588,602,659,804,818,889,1001 'user':10,66,416,664,828,871,880 'usernam':218,228,319,322,861 'username/token':834 'v04':634,802 'verifi':833 'via':41 'wait':394,554,915 'want':11,67,115,154,665 'week':270 'without':553 'work':622,972 'write':526 'www.aicoo.io':173,205,242,335,451,476,496,563,684,700,748 'www.aicoo.io/a/':172 'www.aicoo.io/api/chat/guest-v04':699,747 'www.aicoo.io/api/chat/guest-v04?token=':683 'www.aicoo.io/api/v1/agent/message':241,334 'www.aicoo.io/api/v1/network':204 'www.aicoo.io/api/v1/network/accept':495 'www.aicoo.io/api/v1/network/connect':562 'www.aicoo.io/api/v1/network/request':450 'www.aicoo.io/api/v1/network/requests':475 'x':239,332,448,493,560,697,745 'yet':137,902","prices":[{"id":"5b2249b9-4d25-4a28-b4a3-0c1f3627c605","listingId":"901bc963-93bd-4fd8-baf8-0ff473437b83","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Aicoo-Team","category":"AICOO-Skills","install_from":"skills.sh"},"createdAt":"2026-05-09T01:05:26.385Z"}],"sources":[{"listingId":"901bc963-93bd-4fd8-baf8-0ff473437b83","source":"github","sourceId":"Aicoo-Team/AICOO-Skills/talk-to-agent","sourceUrl":"https://github.com/Aicoo-Team/AICOO-Skills/tree/main/skills/talk-to-agent","isPrimary":false,"firstSeenAt":"2026-05-09T01:05:26.385Z","lastSeenAt":"2026-05-18T19:07:07.768Z"}],"details":{"listingId":"901bc963-93bd-4fd8-baf8-0ff473437b83","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Aicoo-Team","slug":"talk-to-agent","github":{"repo":"Aicoo-Team/AICOO-Skills","stars":12,"topics":["agent","agent-skills","agentic-ai"],"license":"mit","html_url":"https://github.com/Aicoo-Team/AICOO-Skills","pushed_at":"2026-05-05T14:10:59Z","description":"An official set of skills to share, maintain and connect personal AI Agents.","skill_md_sha":"b806951656829e64121fa8128ce00a7967aef214","skill_md_path":"skills/talk-to-agent/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Aicoo-Team/AICOO-Skills/tree/main/skills/talk-to-agent"},"layout":"multi","source":"github","category":"AICOO-Skills","frontmatter":{"name":"talk-to-agent","description":"Use this skill when the user wants to contact another person's Aicoo agent (agent-to-agent RPC), send human inbox messages, request/accept agent access, bridge from share links to friend+agent connections, or chat via public share link (`/a/<token>`). Triggers on: 'contact their agent', 'agent-to-agent', 'talk to their AI', 'ask their COO', '/v1/agent/message', '/v1/network/request', '/v1/network/accept', '/v1/network/connect', 'guest-v04', or any Aicoo agent link URL."},"skills_sh_url":"https://skills.sh/Aicoo-Team/AICOO-Skills/talk-to-agent"},"updatedAt":"2026-05-18T19:07:07.768Z"}}