{"id":"f04ed1c8-8a47-4483-b5fc-9bb49cdded2f","shortId":"2XtuqV","kind":"skill","title":"hcom-workflow-scripts","tagline":"Build multi-agent workflow scripts using hcom. Use this skill when the user wants to create custom hcom scripts, design multi-agent pipelines, write automation that coordinates Claude and Codex agents, or build applications that use hcom as the communication backbone. Covers scri","description":"# hcom workflow scripts\n\nbuild custom multi-agent workflow scripts that launch, coordinate, and manage AI coding agents via hcom.\n\n## decision tree\n\n1. **write a new script** → use the script template below + read `references/script-template.md`\n2. **choose a multi-agent pattern** → read `references/patterns.md`\n3. **need hcom architecture details** → read `references/architecture.md`\n4. **cross-tool scripting (claude + codex)** → read `references/cross-tool-scripting.md`\n5. **debug a script** → read `references/debugging.md`\n6. **want pre-built scripts** → check `references/scripts/` directory\n\n## script template\n\nevery hcom workflow script follows this structure:\n\n```bash\n#!/usr/bin/env bash\n# description shown in `hcom run` listing.\nset -euo pipefail\n\nLAUNCHED_NAMES=()\ntrack_launch() {\n  local names=$(echo \"$1\" | grep '^Names: ' | sed 's/^Names: //')\n  for n in $names; do LAUNCHED_NAMES+=(\"$n\"); done\n}\ncleanup() {\n  for name in \"${LAUNCHED_NAMES[@]}\"; do\n    hcom kill \"$name\" --go 2>/dev/null || true\n  done\n}\ntrap cleanup ERR\n\nname_flag=\"\"\ntask=\"\"\nwhile [[ $# -gt 0 ]]; do\n  case \"$1\" in --name) name_flag=\"$2\"; shift 2 ;; -*) shift ;; *) task=\"$1\"; shift ;; esac\ndone\nname_arg=\"\"\n[[ -n \"$name_flag\" ]] && name_arg=\"--name $name_flag\"\n\nthread=\"workflow-$(date +%s)\"\n\n# --- your workflow logic ---\n\n# launch agent\nlaunch_out=$(hcom 1 claude --tag worker --go --headless \\\n  --hcom-prompt \"task: ${task}. when done: hcom send \\\"@reviewer-\\\" --thread ${thread} --intent inform -- \\\"DONE: <result>\\\". then: hcom stop\" 2>&1)\ntrack_launch \"$launch_out\"\nworker=$(echo \"$launch_out\" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')\n\n# wait for signal\nhcom events --wait 120 --sql \"type='message' AND msg_thread='${thread}' AND msg_text LIKE '%DONE%'\" $name_arg >/dev/null 2>&1\n\n# cleanup\ntrap - ERR\nfor name in \"${LAUNCHED_NAMES[@]}\"; do hcom kill \"$name\" --go 2>/dev/null || true; done\n```\n\nplace scripts in `~/.hcom/scripts/` as `.sh` or `.py`. run with `hcom run <name> \"task\"`.\n\n## agent topologies\n\n| topology | agents | hcom primitives |\n|----------|--------|-----------------|\n| worker-reviewer | 2 | worker sends result, reviewer reads transcript, sends APPROVED/FIX |\n| pipeline | N sequential | each stage reads previous via `hcom transcript`, signals via thread |\n| ensemble | N+1 (judge) | N agents answer independently, judge reads all via `hcom events --sql` |\n| hub-spoke | 1+N | coordinator broadcasts to `@tag-`, workers report back |\n| reactive | N | `hcom events sub` triggers agent actions on file edits/status changes |\n\n## communication primitives\n\n| what | how | latency |\n|------|-----|---------|\n| send message | `hcom send @name --thread T --intent X -- \"msg\"` | under 1s (claude), 1-3s (codex) |\n| wait for signal | `hcom events --wait N --sql \"...\"` | under 1s after match |\n| read agent's work | `hcom transcript @name --full --detailed` | under 1s |\n| react to file changes | `hcom events sub --file \"*.py\"` | under 2s |\n| react to agent idle | `hcom events sub --idle name` | under 2s |\n| cross-device | `hcom send @name:DEVICE -- \"msg\"` | 1-5s |\n| structured handoff | `hcom send --title X --transcript N-M:full --files a.py` | under 1s |\n\n## required flags for script launches\n\n| flag | why it's required |\n|------|-------------------|\n| `--go` | skips confirmation prompt — without it, script hangs forever |\n| `--headless` | runs agent as detached background process |\n| `--tag X` | groups agents for `@X-` routing (essential for scripts) |\n| `--hcom-prompt \"...\"` | sets the agent's initial task |\n\n## key rules\n\n- **never use `sleep`** — use `hcom events --wait` or `hcom listen`\n- **never hardcode agent names** — parse from `grep '^Names: '` in launch output\n- **always use `--thread`** — without it, messages leak across workflows\n- **always use `trap cleanup ERR`** — orphan headless agents run indefinitely\n- **always use `hcom kill` for cleanup** (not `stop`) — kill also closes the terminal pane\n- **always forward `--name`** — hcom injects it, scripts must propagate it\n- **wait for codex before messaging** — `hcom events --wait 30 --idle \"$codex_name\"`\n\n## timing reference (measured)\n\n| operation | claude | codex |\n|-----------|--------|-------|\n| launch to ready | 3-5s | 5-10s |\n| message delivery | under 1s | 1-3s |\n| transcript read | under 1s | under 1s |\n| full 2-agent round-trip | 15-25s | 25-40s |\n| full 4-agent ensemble | 25-35s | n/a |\n\n## integration with external systems\n\nhcom scripts are bash — they can call any CLI tool:\n\n```bash\n# ci/cd trigger\nhcom send @worker- --from \"github-actions\" -- \"PR merged, deploy\"\n\n# webhook notification\ncurl -X POST $WEBHOOK -d \"$(hcom events --sql \"msg_thread='${thread}'\" --last 5)\"\n\n# pipe output\necho \"complex task description\" | hcom send @worker-\n```\n\n## reference files\n\n| file | when to read |\n|------|-------------|\n| `references/script-template.md` | writing a new script from scratch — full template with commentary |\n| `references/patterns.md` | choosing and implementing multi-agent patterns — 6 tested examples |\n| `references/architecture.md` | understanding hcom internals — db schema, hooks, delivery pipeline, events |\n| `references/cross-tool-scripting.md` | claude + codex mixed scripts — per-tool quirks, timing, session binding |\n| `references/debugging.md` | fixing broken scripts — common failures, stale agents, message delivery |\n| `references/scripts/basic-messaging.sh` | tested: two agents exchange messages |\n| `references/scripts/review-loop.sh` | tested: worker-reviewer feedback loop |\n| `references/scripts/cross-tool-duo.sh` | tested: claude architect + codex engineer |\n| `references/scripts/ensemble-consensus.sh` | tested: 3 independent agents + judge |\n| `references/scripts/cascade-pipeline.sh` | tested: sequential plan then execute pipeline |\n| `references/scripts/codex-worker.sh` | tested: codex codes, claude reviews transcript |","tags":["hcom","workflow","scripts","aannoo","agent","agent-skills","ai-agents","ai-tools","automation","claude","claude-code","claude-code-hooks"],"capabilities":["skill","source-aannoo","skill-hcom-workflow-scripts","topic-agent","topic-agent-skills","topic-ai-agents","topic-ai-tools","topic-automation","topic-claude","topic-claude-code","topic-claude-code-hooks","topic-cli","topic-codex","topic-coding-agent","topic-communication"],"categories":["hcom"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/aannoo/hcom/hcom-workflow-scripts","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add aannoo/hcom","source_repo":"https://github.com/aannoo/hcom","install_from":"skills.sh"}},"qualityScore":"0.567","qualityRationale":"deterministic score 0.57 from registry signals: · indexed on github topic:agent-skills · 235 github stars · SKILL.md body (5,889 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-04-22T06:54:17.904Z","embedding":null,"createdAt":"2026-04-18T22:04:52.243Z","updatedAt":"2026-04-22T06:54:17.904Z","lastSeenAt":"2026-04-22T06:54:17.904Z","tsv":"'+1':357 '-10':623 '-25':645 '-3':413,630 '-35':655 '-40':648 '-5':470,620 '/.hcom/scripts':314 '/dev/null':179,291,308 '/usr/bin/env':134 '0':190 '1':72,152,193,203,229,254,293,373,412,469,629 '120':276 '15':644 '1s':410,425,438,486,628,635,637 '2':84,178,198,200,253,292,307,333,639 '25':647,654 '2s':449,460 '3':93,619,790 '30':606 '4':100,651 '5':109,622,699 '6':115,734 'a.py':484 'across':562 'action':389,681 'agent':8,28,37,57,67,89,225,324,327,360,388,429,452,508,516,528,546,571,640,652,732,766,772,792 'ai':65 'also':583 'alway':555,564,574,588 'answer':361 'applic':40 'approved/fix':341 'architect':785 'architectur':96 'arg':208,213,290 'autom':31 'back':381 'backbon':47 'background':511 'bash':133,135,665,672 'bind':758 'broadcast':376 'broken':761 'build':5,39,53 'built':119 'call':668 'case':192 'chang':393,442 'check':121 'choos':85,727 'ci/cd':673 'claud':34,105,230,411,614,748,784,805 'cleanup':167,183,294,567,579 'cli':670 'close':584 'code':66,804 'codex':36,106,415,600,608,615,749,786,803 'commentari':725 'common':763 'communic':46,394 'complex':703 'confirm':499 'coordin':33,62,375 'cover':48 'creat':21 'cross':102,462 'cross-devic':461 'cross-tool':101 'curl':687 'custom':22,54 'd':269,691 'date':219 'db':741 'debug':110 'decis':70 'deliveri':626,744,768 'deploy':684 'descript':136,705 'design':25 'detach':510 'detail':97,436 'devic':463,467 'directori':123 'done':166,181,206,241,249,288,310 'echo':151,260,702 'edits/status':392 'engin':787 'ensembl':355,653 'err':184,296,568 'esac':205 'essenti':520 'euo':143 'event':274,368,385,420,444,455,539,604,693,746 'everi':126 'exampl':736 'exchang':773 'execut':799 'extern':660 'failur':764 'feedback':780 'file':391,441,446,483,710,711 'fix':760 'flag':186,197,211,216,488,492 'follow':130 'forev':505 'forward':589 'full':435,482,638,650,722 'github':680 'github-act':679 'go':177,233,306,497 'grep':153,263,550 'group':515 'gt':189 'handoff':473 'hang':504 'hardcod':545 'hcom':2,12,23,43,50,69,95,127,139,174,228,236,242,251,273,303,321,328,350,367,384,401,419,432,443,454,464,474,524,538,542,576,591,603,662,675,692,706,739 'hcom-prompt':235,523 'hcom-workflow-script':1 'headless':234,506,570 'hook':743 'hub':371 'hub-spok':370 'idl':453,457,607 'implement':729 'indefinit':573 'independ':362,791 'inform':248 'initi':530 'inject':592 'integr':658 'intent':247,406 'intern':740 'judg':358,363,793 'key':532 'kill':175,304,577,582 'last':698 'latenc':398 'launch':61,145,148,163,171,224,226,256,257,261,300,491,553,616 'leak':561 'like':287 'list':141 'listen':543 'local':149 'logic':223 'loop':781 'm':481 'manag':64 'match':427 'measur':612 'merg':683 'messag':279,400,560,602,625,767,774 'mix':750 'msg':281,285,408,468,695 'multi':7,27,56,88,731 'multi-ag':6,26,55,87,730 'must':595 'n':159,165,209,343,356,359,374,383,422,480 'n-m':479 'n/a':657 'name':146,150,154,157,161,164,169,172,176,185,195,196,207,210,212,214,215,264,267,289,298,301,305,403,434,458,466,547,551,590,609 'need':94 'never':534,544 'new':75,718 'notif':686 'oper':613 'orphan':569 'output':554,701 'pane':587 'pars':548 'pattern':90,733 'per':753 'per-tool':752 'pipe':700 'pipefail':144 'pipelin':29,342,745,800 'place':311 'plan':797 'post':689 'pr':682 'pre':118 'pre-built':117 'previous':348 'primit':329,395 'process':512 'prompt':237,500,525 'propag':596 'py':318,447 'quirk':755 'react':439,450 'reactiv':382 'read':82,91,98,107,113,338,347,364,428,633,714 'readi':618 'refer':611,709 'references/architecture.md':99,737 'references/cross-tool-scripting.md':108,747 'references/debugging.md':114,759 'references/patterns.md':92,726 'references/script-template.md':83,715 'references/scripts':122 'references/scripts/basic-messaging.sh':769 'references/scripts/cascade-pipeline.sh':794 'references/scripts/codex-worker.sh':801 'references/scripts/cross-tool-duo.sh':782 'references/scripts/ensemble-consensus.sh':788 'references/scripts/review-loop.sh':775 'report':380 'requir':487,496 'result':336 'review':244,332,337,779,806 'round':642 'round-trip':641 'rout':519 'rule':533 'run':140,319,322,507,572 'schema':742 'scratch':721 'scri':49 'script':4,10,24,52,59,76,79,104,112,120,124,129,312,490,503,522,594,663,719,751,762 'sed':155,265 'send':243,335,340,399,402,465,475,676,707 'sequenti':344,796 'session':757 'set':142,526 'sh':316 'shift':199,201,204 'shown':137 'signal':272,352,418 'skill':15 'skill-hcom-workflow-scripts' 'skip':498 'sleep':536 'source-aannoo' 'spoke':372 'sql':277,369,423,694 'stage':346 'stale':765 'stop':252,581 'structur':132,472 'sub':386,445,456 'system':661 'tag':231,378,513 'task':187,202,238,239,323,531,704 'templat':80,125,723 'termin':586 'test':735,770,776,783,789,795,802 'text':286 'thread':217,245,246,282,283,354,404,557,696,697 'time':610,756 'titl':476 'tool':103,671,754 'topic-agent' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-tools' 'topic-automation' 'topic-claude' 'topic-claude-code' 'topic-claude-code-hooks' 'topic-cli' 'topic-codex' 'topic-coding-agent' 'topic-communication' 'topolog':325,326 'tr':268 'track':147,255 'transcript':339,351,433,478,632,807 'trap':182,295,566 'tree':71 'trigger':387,674 'trip':643 'true':180,309 'two':771 'type':278 'understand':738 'use':11,13,42,77,535,537,556,565,575 'user':18 'via':68,349,353,366 'wait':270,275,416,421,540,598,605 'want':19,116 'webhook':685,690 'without':501,558 'work':431 'worker':232,259,331,334,379,677,708,778 'worker-review':330,777 'workflow':3,9,51,58,128,218,222,563 'write':30,73,716 'x':407,477,514,518,688","prices":[{"id":"8e9e7f1b-ef48-481f-925a-5547114bea30","listingId":"f04ed1c8-8a47-4483-b5fc-9bb49cdded2f","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"aannoo","category":"hcom","install_from":"skills.sh"},"createdAt":"2026-04-18T22:04:52.243Z"}],"sources":[{"listingId":"f04ed1c8-8a47-4483-b5fc-9bb49cdded2f","source":"github","sourceId":"aannoo/hcom/hcom-workflow-scripts","sourceUrl":"https://github.com/aannoo/hcom/tree/main/skills/hcom-workflow-scripts","isPrimary":false,"firstSeenAt":"2026-04-18T22:04:52.243Z","lastSeenAt":"2026-04-22T06:54:17.904Z"}],"details":{"listingId":"f04ed1c8-8a47-4483-b5fc-9bb49cdded2f","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"aannoo","slug":"hcom-workflow-scripts","github":{"repo":"aannoo/hcom","stars":235,"topics":["agent","agent-skills","ai","ai-agents","ai-tools","automation","claude","claude-code","claude-code-hooks","cli","codex","coding-agent","communication","developer-tools","gemini-cli","multi-agent","opencode","orchestration","subagents","terminal"],"license":"mit","html_url":"https://github.com/aannoo/hcom","pushed_at":"2026-04-22T00:23:50Z","description":"Let AI agents message, watch, and spawn each other across terminals. Claude Code, Gemini CLI, Codex, OpenCode","skill_md_sha":"6ea209a91b4bd594a8b514132559435ba53ca722","skill_md_path":"skills/hcom-workflow-scripts/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/aannoo/hcom/tree/main/skills/hcom-workflow-scripts"},"layout":"multi","source":"github","category":"hcom","frontmatter":{"name":"hcom-workflow-scripts","description":"Build multi-agent workflow scripts using hcom. Use this skill when the user wants to create custom hcom scripts, design multi-agent pipelines, write automation that coordinates Claude and Codex agents, or build applications that use hcom as the communication backbone. Covers script patterns, agent topologies, hcom internals, and tested examples."},"skills_sh_url":"https://skills.sh/aannoo/hcom/hcom-workflow-scripts"},"updatedAt":"2026-04-22T06:54:17.904Z"}}