[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-aws-labs-cao-workflow":3,"mdc-2u3gx2-key":36,"related-repo-aws-labs-cao-workflow":1768,"related-org-aws-labs-cao-workflow":1870},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":12,"stars":26,"repoUrl":27,"updatedAt":28,"license":29,"forks":30,"topics":31,"repo":32,"sourceUrl":34,"mdContent":35},"cao-workflow","author and run Python workflow scripts","Author and run CAO Python workflow scripts — multi-step, parameterized, fan-out orchestrations executed by `cao workflow run`. Use when the user wants a repeatable multi-step job (e.g. data analysis over many files, a review pipeline, a parameterized batch). Authoring ends at a validated script file; running it is a separate, user-approved step.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},"aws-labs","AWS Labs","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Faws-labs.png","awslabs",[13,17,20,23],{"name":14,"slug":15,"type":16},"Automation","automation","tag",{"name":18,"slug":19,"type":16},"Data Pipeline","data-pipeline",{"name":21,"slug":22,"type":16},"Orchestration","orchestration",{"name":24,"slug":25,"type":16},"Python","python",871,"https:\u002F\u002Fgithub.com\u002Fawslabs\u002Fcli-agent-orchestrator","2026-07-19T06:03:14.651744",null,164,[],{"repoUrl":27,"stars":26,"forks":30,"topics":33,"description":29},[],"https:\u002F\u002Fgithub.com\u002Fawslabs\u002Fcli-agent-orchestrator\u002Ftree\u002FHEAD\u002Fskills\u002Fcao-workflow","---\nname: cao-workflow\ndescription: Author and run CAO Python workflow scripts — multi-step, parameterized, fan-out\n  orchestrations executed by `cao workflow run`. Use when the user wants a repeatable multi-step\n  job (e.g. data analysis over many files, a review pipeline, a parameterized batch). Authoring\n  ends at a validated script file; running it is a separate, user-approved step.\n---\n\n# CAO Workflows\n\nA CAO workflow is a **Python script** you write, validate, and — only after asking the user —\nrun through `cao workflow run`. Each script drives one or more agent *steps* through CAO's\nshared substrate, so you can fan work out across agents, collect their results, and resume a\nrun that was interrupted.\n\n> Your job as an author ends at a **validated script file on disk**. Authoring does NOT run the\n> workflow. Never claim a workflow ran, or will run, when all you did was write it. Running is a\n> separate step the user must approve (see Lifecycle step c).\n\n## When to use\n\nReach for this skill when the user asks to **build or run a multi-step or parameterized\nworkflow** — for example:\n\n- \"Analyze every file in `reports\u002F` and summarize the findings.\"\n- \"Run a review pipeline: implement, then review, then verify.\"\n- \"Do the same batch job but with a different input directory each time.\"\n\nIf the work is a single one-off agent call, you don't need a workflow. Workflows earn their\nkeep when there are multiple steps, fan-out, parameterization, or a need to resume.\n\n## The script API\n\nAuthor scripts import from the `cao_workflow` package. This package runs **only in the script\nsubprocess** and imports nothing from `cli_agent_orchestrator.*` — it talks to CAO over HTTP.\nIts public surface:\n\n- `run_step(provider, agent, prompt, *, step_id=None, timeout=None, **opts) -> StepHandle` —\n  run one agent step. `StepHandle` has `.step_id`, `.terminal_id`, `.output`, `.status`.\n- `get_inputs() -> dict` — the run's resolved inputs (see Parameterized workflows). Returns\n  `{}` when nothing was declared; never raises on absence.\n- `emit_output(value)` — print the run-level `CAO_WORKFLOW_OUTPUT:` sentinel (the run's return).\n- `ShimError` (and `ShimIdentityError`, `ShimTransportError`, `ShimHTTPError`) — the failure\n  hierarchy `run_step` raises. Failures surface **unchanged** — the shim never retries.\n\n## Lifecycle\n\nFollow every step in order. **No step may be skipped** — validate is mandatory, and you must\nask before running.\n\n### a. AUTHOR\n\nWrite a `.py` file to `~\u002F.aws\u002Fcli-agent-orchestrator\u002Fworkflows\u002F\u003Cname>.py`. The workflow is\n**run by its stem** (`\u003Cname>`), so:\n\n- The name must be a bare stem — **no path separators**, no directory prefix.\n- Do **not** create a same-stem `.yaml` sibling — a `\u003Cname>.yaml` next to `\u003Cname>.py` collides\n  on the run surface.\n\n### b. VALIDATE (mandatory gate)\n\n```\ncao workflow validate ~\u002F.aws\u002Fcli-agent-orchestrator\u002Fworkflows\u002F\u003Cname>.py\n```\n\nFix **every** finding before proceeding — the lint findings are **load-bearing**, not style\nnits:\n\n- **`import cli_agent_orchestrator` is banned.** The script runs in a separate subprocess and\n  must reach CAO only over HTTP (the `cao_workflow` shim). Importing the server package breaks\n  that boundary.\n- **`random` \u002F `time` \u002F `datetime` \u002F `uuid` warnings.** Resume **re-executes the script\n  top-to-bottom** and replays journaled step results. Any nondeterministic value computed at\n  the top level will differ on replay and raise `ReplayDivergenceError`. Keep the script\n  deterministic: derive IDs from inputs, not from the clock or an RNG.\n\n### c. ASK the user — NEVER auto-run\n\nThe script tier executes generated Python. **Never run a workflow without the user's explicit\napproval.** Present the validated file and ask before doing anything in step d.\n\n### d. RUN with an explicit, pre-announced run-id\n\nAnnounce the run-id before you start so the user can cancel it:\n\"Starting run `kb-1` — cancel with `cao workflow cancel kb-1`.\"\n\nChoose the invocation by how the run is triggered, because the two paths have very\ndifferent client-side ceilings:\n\n- **`cao workflow run` (CLI)** uses a client socket timeout of **~8820s (~2.45h)** — the CLI\n  itself won't give up early.\n- **`workflow_run` MCP tool** is bounded by the **MCP host's own per-tool-call timeout** — a\n  host-dependent, much-shorter limit that can **drop a long blocking call and lose its return\n  value even though the server run keeps going**.\n\nSo:\n\n- **Short runs**: call the `workflow_run` MCP tool (blocking) and read the result directly.\n- **Long runs**: background the run and poll, rather than blocking on it —\n  ```\n  cao workflow run \u003Cname> --run-id \u003Cid> --json &\n  ```\n  Backgrounding keeps the run alive server-side without a short MCP host timeout silently\n  dropping the return.\n\n### e. RESUME\n\n```\ncao workflow resume \u003Crun-id>\n```\n\nResume replays completed steps from the journal and continues from the first incomplete one.\nDeterministic scripts (see step b) resume clean; nondeterministic ones diverge.\n\n## Parameterized workflows\n\nInstead of editing a constant per run, declare inputs once and pass values at invocation time.\n\nAdd a **module-level `INPUTS` dict** and read the resolved values at runtime with\n`get_inputs()`:\n\n```python\nfrom cao_workflow import get_inputs\n\nINPUTS = {\n    \"target_dir\": {\"type\": \"path\", \"required\": True},\n    \"max_files\":  {\"type\": \"int\",  \"required\": False, \"default\": 20},\n    \"verbose\":    {\"type\": \"bool\", \"required\": False, \"default\": False},\n}\n\ninputs = get_inputs()\ntarget_dir = inputs[\"target_dir\"]\nmax_files = inputs.get(\"max_files\", 20)\n```\n\nEach entry declares `type` (`string` | `int` | `bool` | `path`), `required`, and an optional\n`default`. This makes one authored script reusable — \"author once, invoke with inputs.\"\n\n## Operational discipline\n\nThese rules are load-bearing. Each is paired with the reason it exists.\n\n### R1 — Fan-out determinism\n\nTo run steps concurrently, use a `ThreadPoolExecutor` and give **every concurrent `run_step` an\nexplicit, stable `step_id`**. The sequential `call-N` counter fallback is race-free but *not*\ndeterministic across runs under concurrent scheduling — so resume would replay the wrong\nresults. Iterate over `sorted()` inputs so the mapping from item → step_id is stable.\n\nDefault `max_workers=2` for `claude_code` (measured: 4 starved the heaviest lens). Expose it as\na tunable input; higher values are fine when steps are light.\n\n### R2 — Secrets as references, never literals\n\nInputs are **journaled in plaintext and replayed on resume**. Never pass a literal secret\n(token, key, password) as an input. Pass a **name\u002Freference** and resolve the actual secret at\nstep time (env var, secrets manager) inside the step.\n\n### R3 — Role-capability matching\n\nOnly **write-capable roles** (e.g. `developer`) should be told to write files. A **read-only\nrole** (e.g. `reviewer`) instructed to write will **hang the full step budget** waiting on a\npermission it can't get. Read-only steps must READ their inputs and **RETURN findings inline**.\n\n### R4 — Per-unit fault tolerance\n\n**Catch `ShimError` inside each fan-out unit** so one step's timeout degrades to a survivor set\nrather than failing the whole run with a 504. Return a sentinel\u002F`None` for the failed unit and\nlet the aggregate proceed.\n\n### Big-outputs discipline\n\nFor large results, have the step **write to a file and return the path** — don't return\nmegabytes inline. Per-step output is `null` for schema-less steps; the files (and the aggregate\nyou build) are the source of truth.\n\n### R5 (INTERIM) — Prefer a headless provider\n\nPrefer **`claude_code`** as the step provider. `kiro_cli` currently launches an interactive TUI\nthat hangs `run_step`. **This is interim guidance** — a kiro mitigation is a tracked follow-up,\nnot a permanent verdict — but until it lands, use a headless provider.\n\n### Projection ranking\n\nThe **runtime journal is the primary truth** for progress and UI — it reflects what actually\nran. A static script→YAML preview is **optional and lossy**; never treat it as the truth source\nand never author against it.\n\n## Handoff when you're read-only\n\nIf you lack write permission (you can't create the `.py` file), **hand off authoring to a\n`developer` agent**, and pass this skill's name (`cao-workflow`) in the handoff message so the\ndeveloper follows the same lifecycle.\n\n## Honesty discipline\n\n- Never claim a workflow ran that didn't.\n- Authoring ends at a **validated file**; running is a separate, user-approved step.\n- Be honest about failures — surface `ShimError`s and non-zero validate findings; don't paper\n  over them.\n\n## Worked example — parameterized fan-out\n\nA script that summarizes each file in a directory concurrently, with a stable `step_id` per\nfile, per-unit fault tolerance, and results written to disk:\n\n```python\n\"\"\"summarize_dir — fan out a summary step over every file in target_dir.\"\"\"\nimport os\nfrom concurrent.futures import ThreadPoolExecutor\n\nfrom cao_workflow import run_step, emit_output, get_inputs, ShimError\n\n# Parameterized: author once, invoke with different inputs.\nINPUTS = {\n    \"target_dir\":  {\"type\": \"path\", \"required\": True},\n    \"max_workers\": {\"type\": \"int\",  \"required\": False, \"default\": 2},\n}\n\ninputs = get_inputs()\ntarget_dir = inputs[\"target_dir\"]\nmax_workers = inputs.get(\"max_workers\", 2)\n\n# sorted() → the item→step_id mapping is stable across runs (R1 determinism).\nfiles = sorted(\n    name for name in os.listdir(target_dir)\n    if os.path.isfile(os.path.join(target_dir, name))\n)\n\n\ndef summarize(filename: str):\n    path = os.path.join(target_dir, filename)\n    try:\n        # Explicit, STABLE step_id per concurrent call (R1). Read-only role\n        # RETURNS its summary inline (R3) — it does not write files.\n        handle = run_step(\n            provider=\"claude_code\",          # headless (R5)\n            agent=\"reviewer\",\n            prompt=f\"Summarize the file at {path} in 3 bullet points. Return the summary only.\",\n            step_id=f\"summarize:{filename}\",\n        )\n        return filename, handle.output\n    except ShimError as exc:\n        # Per-unit tolerance (R4): one timeout degrades to a survivor, not a 504.\n        return filename, f\"ERROR: {exc}\"\n\n\nwith ThreadPoolExecutor(max_workers=max_workers) as pool:\n    results = dict(pool.map(summarize, files))\n\n# Big output → write to a file, return the path (big-outputs discipline).\nout_path = os.path.join(target_dir, \"_summaries.json\")\nwith open(out_path, \"w\") as fh:\n    import json\n    json.dump(results, fh, indent=2)\n\nemit_output({\"summarized\": len(results), \"output_file\": out_path})\n```\n\nValidate it, ask the user, then run with a pre-announced run-id:\n\n```\ncao workflow validate ~\u002F.aws\u002Fcli-agent-orchestrator\u002Fworkflows\u002Fsummarize_dir.py\n# fix findings, then — after the user approves:\ncao workflow run summarize_dir --run-id sum-1 --json &\n```\n",{"data":37,"body":38},{"name":4,"description":6},{"type":39,"children":40},"root",[41,50,81,97,104,116,144,149,155,183,321,327,339,346,382,433,439,451,470,549,555,567,573,594,599,653,658,699,705,714,719,725,730,758,867,925,931,936,942,997,1018,1024,1043,1049,1096,1102,1127,1133,1153,1159,1196,1202,1221,1227,1260,1266,1298,1304,1316,1748,1753,1762],{"type":42,"tag":43,"props":44,"children":46},"element","h1",{"id":45},"cao-workflows",[47],{"type":48,"value":49},"text","CAO Workflows",{"type":42,"tag":51,"props":52,"children":53},"p",{},[54,56,62,64,71,73,79],{"type":48,"value":55},"A CAO workflow is a ",{"type":42,"tag":57,"props":58,"children":59},"strong",{},[60],{"type":48,"value":61},"Python script",{"type":48,"value":63}," you write, validate, and — only after asking the user —\nrun through ",{"type":42,"tag":65,"props":66,"children":68},"code",{"className":67},[],[69],{"type":48,"value":70},"cao workflow run",{"type":48,"value":72},". Each script drives one or more agent ",{"type":42,"tag":74,"props":75,"children":76},"em",{},[77],{"type":48,"value":78},"steps",{"type":48,"value":80}," through CAO's\nshared substrate, so you can fan work out across agents, collect their results, and resume a\nrun that was interrupted.",{"type":42,"tag":82,"props":83,"children":84},"blockquote",{},[85],{"type":42,"tag":51,"props":86,"children":87},{},[88,90,95],{"type":48,"value":89},"Your job as an author ends at a ",{"type":42,"tag":57,"props":91,"children":92},{},[93],{"type":48,"value":94},"validated script file on disk",{"type":48,"value":96},". Authoring does NOT run the\nworkflow. Never claim a workflow ran, or will run, when all you did was write it. Running is a\nseparate step the user must approve (see Lifecycle step c).",{"type":42,"tag":98,"props":99,"children":101},"h2",{"id":100},"when-to-use",[102],{"type":48,"value":103},"When to use",{"type":42,"tag":51,"props":105,"children":106},{},[107,109,114],{"type":48,"value":108},"Reach for this skill when the user asks to ",{"type":42,"tag":57,"props":110,"children":111},{},[112],{"type":48,"value":113},"build or run a multi-step or parameterized\nworkflow",{"type":48,"value":115}," — for example:",{"type":42,"tag":117,"props":118,"children":119},"ul",{},[120,134,139],{"type":42,"tag":121,"props":122,"children":123},"li",{},[124,126,132],{"type":48,"value":125},"\"Analyze every file in ",{"type":42,"tag":65,"props":127,"children":129},{"className":128},[],[130],{"type":48,"value":131},"reports\u002F",{"type":48,"value":133}," and summarize the findings.\"",{"type":42,"tag":121,"props":135,"children":136},{},[137],{"type":48,"value":138},"\"Run a review pipeline: implement, then review, then verify.\"",{"type":42,"tag":121,"props":140,"children":141},{},[142],{"type":48,"value":143},"\"Do the same batch job but with a different input directory each time.\"",{"type":42,"tag":51,"props":145,"children":146},{},[147],{"type":48,"value":148},"If the work is a single one-off agent call, you don't need a workflow. Workflows earn their\nkeep when there are multiple steps, fan-out, parameterization, or a need to resume.",{"type":42,"tag":98,"props":150,"children":152},{"id":151},"the-script-api",[153],{"type":48,"value":154},"The script API",{"type":42,"tag":51,"props":156,"children":157},{},[158,160,166,168,173,175,181],{"type":48,"value":159},"Author scripts import from the ",{"type":42,"tag":65,"props":161,"children":163},{"className":162},[],[164],{"type":48,"value":165},"cao_workflow",{"type":48,"value":167}," package. This package runs ",{"type":42,"tag":57,"props":169,"children":170},{},[171],{"type":48,"value":172},"only in the script\nsubprocess",{"type":48,"value":174}," and imports nothing from ",{"type":42,"tag":65,"props":176,"children":178},{"className":177},[],[179],{"type":48,"value":180},"cli_agent_orchestrator.*",{"type":48,"value":182}," — it talks to CAO over HTTP.\nIts public surface:",{"type":42,"tag":117,"props":184,"children":185},{},[186,235,254,273],{"type":42,"tag":121,"props":187,"children":188},{},[189,195,197,203,205,211,213,219,220,226,227,233],{"type":42,"tag":65,"props":190,"children":192},{"className":191},[],[193],{"type":48,"value":194},"run_step(provider, agent, prompt, *, step_id=None, timeout=None, **opts) -> StepHandle",{"type":48,"value":196}," —\nrun one agent step. ",{"type":42,"tag":65,"props":198,"children":200},{"className":199},[],[201],{"type":48,"value":202},"StepHandle",{"type":48,"value":204}," has ",{"type":42,"tag":65,"props":206,"children":208},{"className":207},[],[209],{"type":48,"value":210},".step_id",{"type":48,"value":212},", ",{"type":42,"tag":65,"props":214,"children":216},{"className":215},[],[217],{"type":48,"value":218},".terminal_id",{"type":48,"value":212},{"type":42,"tag":65,"props":221,"children":223},{"className":222},[],[224],{"type":48,"value":225},".output",{"type":48,"value":212},{"type":42,"tag":65,"props":228,"children":230},{"className":229},[],[231],{"type":48,"value":232},".status",{"type":48,"value":234},".",{"type":42,"tag":121,"props":236,"children":237},{},[238,244,246,252],{"type":42,"tag":65,"props":239,"children":241},{"className":240},[],[242],{"type":48,"value":243},"get_inputs() -> dict",{"type":48,"value":245}," — the run's resolved inputs (see Parameterized workflows). Returns\n",{"type":42,"tag":65,"props":247,"children":249},{"className":248},[],[250],{"type":48,"value":251},"{}",{"type":48,"value":253}," when nothing was declared; never raises on absence.",{"type":42,"tag":121,"props":255,"children":256},{},[257,263,265,271],{"type":42,"tag":65,"props":258,"children":260},{"className":259},[],[261],{"type":48,"value":262},"emit_output(value)",{"type":48,"value":264}," — print the run-level ",{"type":42,"tag":65,"props":266,"children":268},{"className":267},[],[269],{"type":48,"value":270},"CAO_WORKFLOW_OUTPUT:",{"type":48,"value":272}," sentinel (the run's return).",{"type":42,"tag":121,"props":274,"children":275},{},[276,282,284,290,291,297,298,304,306,312,314,319],{"type":42,"tag":65,"props":277,"children":279},{"className":278},[],[280],{"type":48,"value":281},"ShimError",{"type":48,"value":283}," (and ",{"type":42,"tag":65,"props":285,"children":287},{"className":286},[],[288],{"type":48,"value":289},"ShimIdentityError",{"type":48,"value":212},{"type":42,"tag":65,"props":292,"children":294},{"className":293},[],[295],{"type":48,"value":296},"ShimTransportError",{"type":48,"value":212},{"type":42,"tag":65,"props":299,"children":301},{"className":300},[],[302],{"type":48,"value":303},"ShimHTTPError",{"type":48,"value":305},") — the failure\nhierarchy ",{"type":42,"tag":65,"props":307,"children":309},{"className":308},[],[310],{"type":48,"value":311},"run_step",{"type":48,"value":313}," raises. Failures surface ",{"type":42,"tag":57,"props":315,"children":316},{},[317],{"type":48,"value":318},"unchanged",{"type":48,"value":320}," — the shim never retries.",{"type":42,"tag":98,"props":322,"children":324},{"id":323},"lifecycle",[325],{"type":48,"value":326},"Lifecycle",{"type":42,"tag":51,"props":328,"children":329},{},[330,332,337],{"type":48,"value":331},"Follow every step in order. ",{"type":42,"tag":57,"props":333,"children":334},{},[335],{"type":48,"value":336},"No step may be skipped",{"type":48,"value":338}," — validate is mandatory, and you must\nask before running.",{"type":42,"tag":340,"props":341,"children":343},"h3",{"id":342},"a-author",[344],{"type":48,"value":345},"a. AUTHOR",{"type":42,"tag":51,"props":347,"children":348},{},[349,351,357,359,365,367,372,374,380],{"type":48,"value":350},"Write a ",{"type":42,"tag":65,"props":352,"children":354},{"className":353},[],[355],{"type":48,"value":356},".py",{"type":48,"value":358}," file to ",{"type":42,"tag":65,"props":360,"children":362},{"className":361},[],[363],{"type":48,"value":364},"~\u002F.aws\u002Fcli-agent-orchestrator\u002Fworkflows\u002F\u003Cname>.py",{"type":48,"value":366},". The workflow is\n",{"type":42,"tag":57,"props":368,"children":369},{},[370],{"type":48,"value":371},"run by its stem",{"type":48,"value":373}," (",{"type":42,"tag":65,"props":375,"children":377},{"className":376},[],[378],{"type":48,"value":379},"\u003Cname>",{"type":48,"value":381},"), so:",{"type":42,"tag":117,"props":383,"children":384},{},[385,397],{"type":42,"tag":121,"props":386,"children":387},{},[388,390,395],{"type":48,"value":389},"The name must be a bare stem — ",{"type":42,"tag":57,"props":391,"children":392},{},[393],{"type":48,"value":394},"no path separators",{"type":48,"value":396},", no directory prefix.",{"type":42,"tag":121,"props":398,"children":399},{},[400,402,407,409,415,417,423,425,431],{"type":48,"value":401},"Do ",{"type":42,"tag":57,"props":403,"children":404},{},[405],{"type":48,"value":406},"not",{"type":48,"value":408}," create a same-stem ",{"type":42,"tag":65,"props":410,"children":412},{"className":411},[],[413],{"type":48,"value":414},".yaml",{"type":48,"value":416}," sibling — a ",{"type":42,"tag":65,"props":418,"children":420},{"className":419},[],[421],{"type":48,"value":422},"\u003Cname>.yaml",{"type":48,"value":424}," next to ",{"type":42,"tag":65,"props":426,"children":428},{"className":427},[],[429],{"type":48,"value":430},"\u003Cname>.py",{"type":48,"value":432}," collides\non the run surface.",{"type":42,"tag":340,"props":434,"children":436},{"id":435},"b-validate-mandatory-gate",[437],{"type":48,"value":438},"b. VALIDATE (mandatory gate)",{"type":42,"tag":440,"props":441,"children":445},"pre",{"className":442,"code":444,"language":48},[443],"language-text","cao workflow validate ~\u002F.aws\u002Fcli-agent-orchestrator\u002Fworkflows\u002F\u003Cname>.py\n",[446],{"type":42,"tag":65,"props":447,"children":449},{"__ignoreMap":448},"",[450],{"type":48,"value":444},{"type":42,"tag":51,"props":452,"children":453},{},[454,456,461,463,468],{"type":48,"value":455},"Fix ",{"type":42,"tag":57,"props":457,"children":458},{},[459],{"type":48,"value":460},"every",{"type":48,"value":462}," finding before proceeding — the lint findings are ",{"type":42,"tag":57,"props":464,"children":465},{},[466],{"type":48,"value":467},"load-bearing",{"type":48,"value":469},", not style\nnits:",{"type":42,"tag":117,"props":471,"children":472},{},[473,496],{"type":42,"tag":121,"props":474,"children":475},{},[476,487,489,494],{"type":42,"tag":57,"props":477,"children":478},{},[479,485],{"type":42,"tag":65,"props":480,"children":482},{"className":481},[],[483],{"type":48,"value":484},"import cli_agent_orchestrator",{"type":48,"value":486}," is banned.",{"type":48,"value":488}," The script runs in a separate subprocess and\nmust reach CAO only over HTTP (the ",{"type":42,"tag":65,"props":490,"children":492},{"className":491},[],[493],{"type":48,"value":165},{"type":48,"value":495}," shim). Importing the server package breaks\nthat boundary.",{"type":42,"tag":121,"props":497,"children":498},{},[499,532,534,539,541,547],{"type":42,"tag":57,"props":500,"children":501},{},[502,508,510,516,517,523,524,530],{"type":42,"tag":65,"props":503,"children":505},{"className":504},[],[506],{"type":48,"value":507},"random",{"type":48,"value":509}," \u002F ",{"type":42,"tag":65,"props":511,"children":513},{"className":512},[],[514],{"type":48,"value":515},"time",{"type":48,"value":509},{"type":42,"tag":65,"props":518,"children":520},{"className":519},[],[521],{"type":48,"value":522},"datetime",{"type":48,"value":509},{"type":42,"tag":65,"props":525,"children":527},{"className":526},[],[528],{"type":48,"value":529},"uuid",{"type":48,"value":531}," warnings.",{"type":48,"value":533}," Resume ",{"type":42,"tag":57,"props":535,"children":536},{},[537],{"type":48,"value":538},"re-executes the script\ntop-to-bottom",{"type":48,"value":540}," and replays journaled step results. Any nondeterministic value computed at\nthe top level will differ on replay and raise ",{"type":42,"tag":65,"props":542,"children":544},{"className":543},[],[545],{"type":48,"value":546},"ReplayDivergenceError",{"type":48,"value":548},". Keep the script\ndeterministic: derive IDs from inputs, not from the clock or an RNG.",{"type":42,"tag":340,"props":550,"children":552},{"id":551},"c-ask-the-user-never-auto-run",[553],{"type":48,"value":554},"c. ASK the user — NEVER auto-run",{"type":42,"tag":51,"props":556,"children":557},{},[558,560,565],{"type":48,"value":559},"The script tier executes generated Python. ",{"type":42,"tag":57,"props":561,"children":562},{},[563],{"type":48,"value":564},"Never run a workflow without the user's explicit\napproval.",{"type":48,"value":566}," Present the validated file and ask before doing anything in step d.",{"type":42,"tag":340,"props":568,"children":570},{"id":569},"d-run-with-an-explicit-pre-announced-run-id",[571],{"type":48,"value":572},"d. RUN with an explicit, pre-announced run-id",{"type":42,"tag":51,"props":574,"children":575},{},[576,578,584,586,592],{"type":48,"value":577},"Announce the run-id before you start so the user can cancel it:\n\"Starting run ",{"type":42,"tag":65,"props":579,"children":581},{"className":580},[],[582],{"type":48,"value":583},"kb-1",{"type":48,"value":585}," — cancel with ",{"type":42,"tag":65,"props":587,"children":589},{"className":588},[],[590],{"type":48,"value":591},"cao workflow cancel kb-1",{"type":48,"value":593},".\"",{"type":42,"tag":51,"props":595,"children":596},{},[597],{"type":48,"value":598},"Choose the invocation by how the run is triggered, because the two paths have very\ndifferent client-side ceilings:",{"type":42,"tag":117,"props":600,"children":601},{},[602,624],{"type":42,"tag":121,"props":603,"children":604},{},[605,615,617,622],{"type":42,"tag":57,"props":606,"children":607},{},[608,613],{"type":42,"tag":65,"props":609,"children":611},{"className":610},[],[612],{"type":48,"value":70},{"type":48,"value":614}," (CLI)",{"type":48,"value":616}," uses a client socket timeout of ",{"type":42,"tag":57,"props":618,"children":619},{},[620],{"type":48,"value":621},"~8820s (~2.45h)",{"type":48,"value":623}," — the CLI\nitself won't give up early.",{"type":42,"tag":121,"props":625,"children":626},{},[627,638,640,645,647,652],{"type":42,"tag":57,"props":628,"children":629},{},[630,636],{"type":42,"tag":65,"props":631,"children":633},{"className":632},[],[634],{"type":48,"value":635},"workflow_run",{"type":48,"value":637}," MCP tool",{"type":48,"value":639}," is bounded by the ",{"type":42,"tag":57,"props":641,"children":642},{},[643],{"type":48,"value":644},"MCP host's own per-tool-call timeout",{"type":48,"value":646}," — a\nhost-dependent, much-shorter limit that can ",{"type":42,"tag":57,"props":648,"children":649},{},[650],{"type":48,"value":651},"drop a long blocking call and lose its return\nvalue even though the server run keeps going",{"type":48,"value":234},{"type":42,"tag":51,"props":654,"children":655},{},[656],{"type":48,"value":657},"So:",{"type":42,"tag":117,"props":659,"children":660},{},[661,678],{"type":42,"tag":121,"props":662,"children":663},{},[664,669,671,676],{"type":42,"tag":57,"props":665,"children":666},{},[667],{"type":48,"value":668},"Short runs",{"type":48,"value":670},": call the ",{"type":42,"tag":65,"props":672,"children":674},{"className":673},[],[675],{"type":48,"value":635},{"type":48,"value":677}," MCP tool (blocking) and read the result directly.",{"type":42,"tag":121,"props":679,"children":680},{},[681,686,688,697],{"type":42,"tag":57,"props":682,"children":683},{},[684],{"type":48,"value":685},"Long runs",{"type":48,"value":687},": background the run and poll, rather than blocking on it —\n",{"type":42,"tag":440,"props":689,"children":692},{"className":690,"code":691,"language":48},[443],"cao workflow run \u003Cname> --run-id \u003Cid> --json &\n",[693],{"type":42,"tag":65,"props":694,"children":695},{"__ignoreMap":448},[696],{"type":48,"value":691},{"type":48,"value":698},"\nBackgrounding keeps the run alive server-side without a short MCP host timeout silently\ndropping the return.",{"type":42,"tag":340,"props":700,"children":702},{"id":701},"e-resume",[703],{"type":48,"value":704},"e. RESUME",{"type":42,"tag":440,"props":706,"children":709},{"className":707,"code":708,"language":48},[443],"cao workflow resume \u003Crun-id>\n",[710],{"type":42,"tag":65,"props":711,"children":712},{"__ignoreMap":448},[713],{"type":48,"value":708},{"type":42,"tag":51,"props":715,"children":716},{},[717],{"type":48,"value":718},"Resume replays completed steps from the journal and continues from the first incomplete one.\nDeterministic scripts (see step b) resume clean; nondeterministic ones diverge.",{"type":42,"tag":98,"props":720,"children":722},{"id":721},"parameterized-workflows",[723],{"type":48,"value":724},"Parameterized workflows",{"type":42,"tag":51,"props":726,"children":727},{},[728],{"type":48,"value":729},"Instead of editing a constant per run, declare inputs once and pass values at invocation time.",{"type":42,"tag":51,"props":731,"children":732},{},[733,735,748,750,756],{"type":48,"value":734},"Add a ",{"type":42,"tag":57,"props":736,"children":737},{},[738,740,746],{"type":48,"value":739},"module-level ",{"type":42,"tag":65,"props":741,"children":743},{"className":742},[],[744],{"type":48,"value":745},"INPUTS",{"type":48,"value":747}," dict",{"type":48,"value":749}," and read the resolved values at runtime with\n",{"type":42,"tag":65,"props":751,"children":753},{"className":752},[],[754],{"type":48,"value":755},"get_inputs()",{"type":48,"value":757},":",{"type":42,"tag":440,"props":759,"children":762},{"className":760,"code":761,"language":25,"meta":448,"style":448},"language-python shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","from cao_workflow import get_inputs\n\nINPUTS = {\n    \"target_dir\": {\"type\": \"path\", \"required\": True},\n    \"max_files\":  {\"type\": \"int\",  \"required\": False, \"default\": 20},\n    \"verbose\":    {\"type\": \"bool\", \"required\": False, \"default\": False},\n}\n\ninputs = get_inputs()\ntarget_dir = inputs[\"target_dir\"]\nmax_files = inputs.get(\"max_files\", 20)\n",[763],{"type":42,"tag":65,"props":764,"children":765},{"__ignoreMap":448},[766,777,787,796,805,814,823,832,840,849,858],{"type":42,"tag":767,"props":768,"children":771},"span",{"class":769,"line":770},"line",1,[772],{"type":42,"tag":767,"props":773,"children":774},{},[775],{"type":48,"value":776},"from cao_workflow import get_inputs\n",{"type":42,"tag":767,"props":778,"children":780},{"class":769,"line":779},2,[781],{"type":42,"tag":767,"props":782,"children":784},{"emptyLinePlaceholder":783},true,[785],{"type":48,"value":786},"\n",{"type":42,"tag":767,"props":788,"children":790},{"class":769,"line":789},3,[791],{"type":42,"tag":767,"props":792,"children":793},{},[794],{"type":48,"value":795},"INPUTS = {\n",{"type":42,"tag":767,"props":797,"children":799},{"class":769,"line":798},4,[800],{"type":42,"tag":767,"props":801,"children":802},{},[803],{"type":48,"value":804},"    \"target_dir\": {\"type\": \"path\", \"required\": True},\n",{"type":42,"tag":767,"props":806,"children":808},{"class":769,"line":807},5,[809],{"type":42,"tag":767,"props":810,"children":811},{},[812],{"type":48,"value":813},"    \"max_files\":  {\"type\": \"int\",  \"required\": False, \"default\": 20},\n",{"type":42,"tag":767,"props":815,"children":817},{"class":769,"line":816},6,[818],{"type":42,"tag":767,"props":819,"children":820},{},[821],{"type":48,"value":822},"    \"verbose\":    {\"type\": \"bool\", \"required\": False, \"default\": False},\n",{"type":42,"tag":767,"props":824,"children":826},{"class":769,"line":825},7,[827],{"type":42,"tag":767,"props":828,"children":829},{},[830],{"type":48,"value":831},"}\n",{"type":42,"tag":767,"props":833,"children":835},{"class":769,"line":834},8,[836],{"type":42,"tag":767,"props":837,"children":838},{"emptyLinePlaceholder":783},[839],{"type":48,"value":786},{"type":42,"tag":767,"props":841,"children":843},{"class":769,"line":842},9,[844],{"type":42,"tag":767,"props":845,"children":846},{},[847],{"type":48,"value":848},"inputs = get_inputs()\n",{"type":42,"tag":767,"props":850,"children":852},{"class":769,"line":851},10,[853],{"type":42,"tag":767,"props":854,"children":855},{},[856],{"type":48,"value":857},"target_dir = inputs[\"target_dir\"]\n",{"type":42,"tag":767,"props":859,"children":861},{"class":769,"line":860},11,[862],{"type":42,"tag":767,"props":863,"children":864},{},[865],{"type":48,"value":866},"max_files = inputs.get(\"max_files\", 20)\n",{"type":42,"tag":51,"props":868,"children":869},{},[870,872,878,879,885,887,893,894,900,901,907,909,915,917,923],{"type":48,"value":871},"Each entry declares ",{"type":42,"tag":65,"props":873,"children":875},{"className":874},[],[876],{"type":48,"value":877},"type",{"type":48,"value":373},{"type":42,"tag":65,"props":880,"children":882},{"className":881},[],[883],{"type":48,"value":884},"string",{"type":48,"value":886}," | ",{"type":42,"tag":65,"props":888,"children":890},{"className":889},[],[891],{"type":48,"value":892},"int",{"type":48,"value":886},{"type":42,"tag":65,"props":895,"children":897},{"className":896},[],[898],{"type":48,"value":899},"bool",{"type":48,"value":886},{"type":42,"tag":65,"props":902,"children":904},{"className":903},[],[905],{"type":48,"value":906},"path",{"type":48,"value":908},"), ",{"type":42,"tag":65,"props":910,"children":912},{"className":911},[],[913],{"type":48,"value":914},"required",{"type":48,"value":916},", and an optional\n",{"type":42,"tag":65,"props":918,"children":920},{"className":919},[],[921],{"type":48,"value":922},"default",{"type":48,"value":924},". This makes one authored script reusable — \"author once, invoke with inputs.\"",{"type":42,"tag":98,"props":926,"children":928},{"id":927},"operational-discipline",[929],{"type":48,"value":930},"Operational discipline",{"type":42,"tag":51,"props":932,"children":933},{},[934],{"type":48,"value":935},"These rules are load-bearing. Each is paired with the reason it exists.",{"type":42,"tag":340,"props":937,"children":939},{"id":938},"r1-fan-out-determinism",[940],{"type":48,"value":941},"R1 — Fan-out determinism",{"type":42,"tag":51,"props":943,"children":944},{},[945,947,953,955,973,975,981,983,987,989,995],{"type":48,"value":946},"To run steps concurrently, use a ",{"type":42,"tag":65,"props":948,"children":950},{"className":949},[],[951],{"type":48,"value":952},"ThreadPoolExecutor",{"type":48,"value":954}," and give ",{"type":42,"tag":57,"props":956,"children":957},{},[958,960,965,967],{"type":48,"value":959},"every concurrent ",{"type":42,"tag":65,"props":961,"children":963},{"className":962},[],[964],{"type":48,"value":311},{"type":48,"value":966}," an\nexplicit, stable ",{"type":42,"tag":65,"props":968,"children":970},{"className":969},[],[971],{"type":48,"value":972},"step_id",{"type":48,"value":974},". The sequential ",{"type":42,"tag":65,"props":976,"children":978},{"className":977},[],[979],{"type":48,"value":980},"call-N",{"type":48,"value":982}," counter fallback is race-free but ",{"type":42,"tag":74,"props":984,"children":985},{},[986],{"type":48,"value":406},{"type":48,"value":988},"\ndeterministic across runs under concurrent scheduling — so resume would replay the wrong\nresults. Iterate over ",{"type":42,"tag":65,"props":990,"children":992},{"className":991},[],[993],{"type":48,"value":994},"sorted()",{"type":48,"value":996}," inputs so the mapping from item → step_id is stable.",{"type":42,"tag":51,"props":998,"children":999},{},[1000,1002,1008,1010,1016],{"type":48,"value":1001},"Default ",{"type":42,"tag":65,"props":1003,"children":1005},{"className":1004},[],[1006],{"type":48,"value":1007},"max_workers=2",{"type":48,"value":1009}," for ",{"type":42,"tag":65,"props":1011,"children":1013},{"className":1012},[],[1014],{"type":48,"value":1015},"claude_code",{"type":48,"value":1017}," (measured: 4 starved the heaviest lens). Expose it as\na tunable input; higher values are fine when steps are light.",{"type":42,"tag":340,"props":1019,"children":1021},{"id":1020},"r2-secrets-as-references-never-literals",[1022],{"type":48,"value":1023},"R2 — Secrets as references, never literals",{"type":42,"tag":51,"props":1025,"children":1026},{},[1027,1029,1034,1036,1041],{"type":48,"value":1028},"Inputs are ",{"type":42,"tag":57,"props":1030,"children":1031},{},[1032],{"type":48,"value":1033},"journaled in plaintext and replayed on resume",{"type":48,"value":1035},". Never pass a literal secret\n(token, key, password) as an input. Pass a ",{"type":42,"tag":57,"props":1037,"children":1038},{},[1039],{"type":48,"value":1040},"name\u002Freference",{"type":48,"value":1042}," and resolve the actual secret at\nstep time (env var, secrets manager) inside the step.",{"type":42,"tag":340,"props":1044,"children":1046},{"id":1045},"r3-role-capability-matching",[1047],{"type":48,"value":1048},"R3 — Role-capability matching",{"type":42,"tag":51,"props":1050,"children":1051},{},[1052,1054,1059,1061,1067,1069,1074,1075,1081,1083,1088,1090,1095],{"type":48,"value":1053},"Only ",{"type":42,"tag":57,"props":1055,"children":1056},{},[1057],{"type":48,"value":1058},"write-capable roles",{"type":48,"value":1060}," (e.g. ",{"type":42,"tag":65,"props":1062,"children":1064},{"className":1063},[],[1065],{"type":48,"value":1066},"developer",{"type":48,"value":1068},") should be told to write files. A ",{"type":42,"tag":57,"props":1070,"children":1071},{},[1072],{"type":48,"value":1073},"read-only\nrole",{"type":48,"value":1060},{"type":42,"tag":65,"props":1076,"children":1078},{"className":1077},[],[1079],{"type":48,"value":1080},"reviewer",{"type":48,"value":1082},") instructed to write will ",{"type":42,"tag":57,"props":1084,"children":1085},{},[1086],{"type":48,"value":1087},"hang the full step budget",{"type":48,"value":1089}," waiting on a\npermission it can't get. Read-only steps must READ their inputs and ",{"type":42,"tag":57,"props":1091,"children":1092},{},[1093],{"type":48,"value":1094},"RETURN findings inline",{"type":48,"value":234},{"type":42,"tag":340,"props":1097,"children":1099},{"id":1098},"r4-per-unit-fault-tolerance",[1100],{"type":48,"value":1101},"R4 — Per-unit fault tolerance",{"type":42,"tag":51,"props":1103,"children":1104},{},[1105,1117,1119,1125],{"type":42,"tag":57,"props":1106,"children":1107},{},[1108,1110,1115],{"type":48,"value":1109},"Catch ",{"type":42,"tag":65,"props":1111,"children":1113},{"className":1112},[],[1114],{"type":48,"value":281},{"type":48,"value":1116}," inside each fan-out unit",{"type":48,"value":1118}," so one step's timeout degrades to a survivor set\nrather than failing the whole run with a 504. Return a sentinel\u002F",{"type":42,"tag":65,"props":1120,"children":1122},{"className":1121},[],[1123],{"type":48,"value":1124},"None",{"type":48,"value":1126}," for the failed unit and\nlet the aggregate proceed.",{"type":42,"tag":340,"props":1128,"children":1130},{"id":1129},"big-outputs-discipline",[1131],{"type":48,"value":1132},"Big-outputs discipline",{"type":42,"tag":51,"props":1134,"children":1135},{},[1136,1138,1143,1145,1151],{"type":48,"value":1137},"For large results, have the step ",{"type":42,"tag":57,"props":1139,"children":1140},{},[1141],{"type":48,"value":1142},"write to a file and return the path",{"type":48,"value":1144}," — don't return\nmegabytes inline. Per-step output is ",{"type":42,"tag":65,"props":1146,"children":1148},{"className":1147},[],[1149],{"type":48,"value":1150},"null",{"type":48,"value":1152}," for schema-less steps; the files (and the aggregate\nyou build) are the source of truth.",{"type":42,"tag":340,"props":1154,"children":1156},{"id":1155},"r5-interim-prefer-a-headless-provider",[1157],{"type":48,"value":1158},"R5 (INTERIM) — Prefer a headless provider",{"type":42,"tag":51,"props":1160,"children":1161},{},[1162,1164,1172,1174,1180,1182,1187,1189,1194],{"type":48,"value":1163},"Prefer ",{"type":42,"tag":57,"props":1165,"children":1166},{},[1167],{"type":42,"tag":65,"props":1168,"children":1170},{"className":1169},[],[1171],{"type":48,"value":1015},{"type":48,"value":1173}," as the step provider. ",{"type":42,"tag":65,"props":1175,"children":1177},{"className":1176},[],[1178],{"type":48,"value":1179},"kiro_cli",{"type":48,"value":1181}," currently launches an interactive TUI\nthat hangs ",{"type":42,"tag":65,"props":1183,"children":1185},{"className":1184},[],[1186],{"type":48,"value":311},{"type":48,"value":1188},". ",{"type":42,"tag":57,"props":1190,"children":1191},{},[1192],{"type":48,"value":1193},"This is interim guidance",{"type":48,"value":1195}," — a kiro mitigation is a tracked follow-up,\nnot a permanent verdict — but until it lands, use a headless provider.",{"type":42,"tag":340,"props":1197,"children":1199},{"id":1198},"projection-ranking",[1200],{"type":48,"value":1201},"Projection ranking",{"type":42,"tag":51,"props":1203,"children":1204},{},[1205,1207,1212,1214,1219],{"type":48,"value":1206},"The ",{"type":42,"tag":57,"props":1208,"children":1209},{},[1210],{"type":48,"value":1211},"runtime journal is the primary truth",{"type":48,"value":1213}," for progress and UI — it reflects what actually\nran. A static script→YAML preview is ",{"type":42,"tag":57,"props":1215,"children":1216},{},[1217],{"type":48,"value":1218},"optional and lossy",{"type":48,"value":1220},"; never treat it as the truth source\nand never author against it.",{"type":42,"tag":98,"props":1222,"children":1224},{"id":1223},"handoff-when-youre-read-only",[1225],{"type":48,"value":1226},"Handoff when you're read-only",{"type":42,"tag":51,"props":1228,"children":1229},{},[1230,1232,1237,1239,1251,1253,1258],{"type":48,"value":1231},"If you lack write permission (you can't create the ",{"type":42,"tag":65,"props":1233,"children":1235},{"className":1234},[],[1236],{"type":48,"value":356},{"type":48,"value":1238}," file), ",{"type":42,"tag":57,"props":1240,"children":1241},{},[1242,1244,1249],{"type":48,"value":1243},"hand off authoring to a\n",{"type":42,"tag":65,"props":1245,"children":1247},{"className":1246},[],[1248],{"type":48,"value":1066},{"type":48,"value":1250}," agent",{"type":48,"value":1252},", and pass this skill's name (",{"type":42,"tag":65,"props":1254,"children":1256},{"className":1255},[],[1257],{"type":48,"value":4},{"type":48,"value":1259},") in the handoff message so the\ndeveloper follows the same lifecycle.",{"type":42,"tag":98,"props":1261,"children":1263},{"id":1262},"honesty-discipline",[1264],{"type":48,"value":1265},"Honesty discipline",{"type":42,"tag":117,"props":1267,"children":1268},{},[1269,1274,1286],{"type":42,"tag":121,"props":1270,"children":1271},{},[1272],{"type":48,"value":1273},"Never claim a workflow ran that didn't.",{"type":42,"tag":121,"props":1275,"children":1276},{},[1277,1279,1284],{"type":48,"value":1278},"Authoring ends at a ",{"type":42,"tag":57,"props":1280,"children":1281},{},[1282],{"type":48,"value":1283},"validated file",{"type":48,"value":1285},"; running is a separate, user-approved step.",{"type":42,"tag":121,"props":1287,"children":1288},{},[1289,1291,1296],{"type":48,"value":1290},"Be honest about failures — surface ",{"type":42,"tag":65,"props":1292,"children":1294},{"className":1293},[],[1295],{"type":48,"value":281},{"type":48,"value":1297},"s and non-zero validate findings; don't paper\nover them.",{"type":42,"tag":98,"props":1299,"children":1301},{"id":1300},"worked-example-parameterized-fan-out",[1302],{"type":48,"value":1303},"Worked example — parameterized fan-out",{"type":42,"tag":51,"props":1305,"children":1306},{},[1307,1309,1314],{"type":48,"value":1308},"A script that summarizes each file in a directory concurrently, with a stable ",{"type":42,"tag":65,"props":1310,"children":1312},{"className":1311},[],[1313],{"type":48,"value":972},{"type":48,"value":1315}," per\nfile, per-unit fault tolerance, and results written to disk:",{"type":42,"tag":440,"props":1317,"children":1319},{"className":760,"code":1318,"language":25,"meta":448,"style":448},"\"\"\"summarize_dir — fan out a summary step over every file in target_dir.\"\"\"\nimport os\nfrom concurrent.futures import ThreadPoolExecutor\n\nfrom cao_workflow import run_step, emit_output, get_inputs, ShimError\n\n# Parameterized: author once, invoke with different inputs.\nINPUTS = {\n    \"target_dir\":  {\"type\": \"path\", \"required\": True},\n    \"max_workers\": {\"type\": \"int\",  \"required\": False, \"default\": 2},\n}\n\ninputs = get_inputs()\ntarget_dir = inputs[\"target_dir\"]\nmax_workers = inputs.get(\"max_workers\", 2)\n\n# sorted() → the item→step_id mapping is stable across runs (R1 determinism).\nfiles = sorted(\n    name for name in os.listdir(target_dir)\n    if os.path.isfile(os.path.join(target_dir, name))\n)\n\n\ndef summarize(filename: str):\n    path = os.path.join(target_dir, filename)\n    try:\n        # Explicit, STABLE step_id per concurrent call (R1). Read-only role\n        # RETURNS its summary inline (R3) — it does not write files.\n        handle = run_step(\n            provider=\"claude_code\",          # headless (R5)\n            agent=\"reviewer\",\n            prompt=f\"Summarize the file at {path} in 3 bullet points. Return the summary only.\",\n            step_id=f\"summarize:{filename}\",\n        )\n        return filename, handle.output\n    except ShimError as exc:\n        # Per-unit tolerance (R4): one timeout degrades to a survivor, not a 504.\n        return filename, f\"ERROR: {exc}\"\n\n\nwith ThreadPoolExecutor(max_workers=max_workers) as pool:\n    results = dict(pool.map(summarize, files))\n\n# Big output → write to a file, return the path (big-outputs discipline).\nout_path = os.path.join(target_dir, \"_summaries.json\")\nwith open(out_path, \"w\") as fh:\n    import json\n    json.dump(results, fh, indent=2)\n\nemit_output({\"summarized\": len(results), \"output_file\": out_path})\n",[1320],{"type":42,"tag":65,"props":1321,"children":1322},{"__ignoreMap":448},[1323,1331,1339,1347,1354,1362,1369,1377,1384,1392,1400,1407,1415,1423,1431,1440,1448,1457,1466,1475,1484,1493,1501,1509,1518,1527,1536,1545,1554,1563,1572,1581,1590,1599,1608,1617,1626,1635,1644,1652,1660,1669,1678,1686,1695,1704,1713,1722,1731,1739],{"type":42,"tag":767,"props":1324,"children":1325},{"class":769,"line":770},[1326],{"type":42,"tag":767,"props":1327,"children":1328},{},[1329],{"type":48,"value":1330},"\"\"\"summarize_dir — fan out a summary step over every file in target_dir.\"\"\"\n",{"type":42,"tag":767,"props":1332,"children":1333},{"class":769,"line":779},[1334],{"type":42,"tag":767,"props":1335,"children":1336},{},[1337],{"type":48,"value":1338},"import os\n",{"type":42,"tag":767,"props":1340,"children":1341},{"class":769,"line":789},[1342],{"type":42,"tag":767,"props":1343,"children":1344},{},[1345],{"type":48,"value":1346},"from concurrent.futures import ThreadPoolExecutor\n",{"type":42,"tag":767,"props":1348,"children":1349},{"class":769,"line":798},[1350],{"type":42,"tag":767,"props":1351,"children":1352},{"emptyLinePlaceholder":783},[1353],{"type":48,"value":786},{"type":42,"tag":767,"props":1355,"children":1356},{"class":769,"line":807},[1357],{"type":42,"tag":767,"props":1358,"children":1359},{},[1360],{"type":48,"value":1361},"from cao_workflow import run_step, emit_output, get_inputs, ShimError\n",{"type":42,"tag":767,"props":1363,"children":1364},{"class":769,"line":816},[1365],{"type":42,"tag":767,"props":1366,"children":1367},{"emptyLinePlaceholder":783},[1368],{"type":48,"value":786},{"type":42,"tag":767,"props":1370,"children":1371},{"class":769,"line":825},[1372],{"type":42,"tag":767,"props":1373,"children":1374},{},[1375],{"type":48,"value":1376},"# Parameterized: author once, invoke with different inputs.\n",{"type":42,"tag":767,"props":1378,"children":1379},{"class":769,"line":834},[1380],{"type":42,"tag":767,"props":1381,"children":1382},{},[1383],{"type":48,"value":795},{"type":42,"tag":767,"props":1385,"children":1386},{"class":769,"line":842},[1387],{"type":42,"tag":767,"props":1388,"children":1389},{},[1390],{"type":48,"value":1391},"    \"target_dir\":  {\"type\": \"path\", \"required\": True},\n",{"type":42,"tag":767,"props":1393,"children":1394},{"class":769,"line":851},[1395],{"type":42,"tag":767,"props":1396,"children":1397},{},[1398],{"type":48,"value":1399},"    \"max_workers\": {\"type\": \"int\",  \"required\": False, \"default\": 2},\n",{"type":42,"tag":767,"props":1401,"children":1402},{"class":769,"line":860},[1403],{"type":42,"tag":767,"props":1404,"children":1405},{},[1406],{"type":48,"value":831},{"type":42,"tag":767,"props":1408,"children":1410},{"class":769,"line":1409},12,[1411],{"type":42,"tag":767,"props":1412,"children":1413},{"emptyLinePlaceholder":783},[1414],{"type":48,"value":786},{"type":42,"tag":767,"props":1416,"children":1418},{"class":769,"line":1417},13,[1419],{"type":42,"tag":767,"props":1420,"children":1421},{},[1422],{"type":48,"value":848},{"type":42,"tag":767,"props":1424,"children":1426},{"class":769,"line":1425},14,[1427],{"type":42,"tag":767,"props":1428,"children":1429},{},[1430],{"type":48,"value":857},{"type":42,"tag":767,"props":1432,"children":1434},{"class":769,"line":1433},15,[1435],{"type":42,"tag":767,"props":1436,"children":1437},{},[1438],{"type":48,"value":1439},"max_workers = inputs.get(\"max_workers\", 2)\n",{"type":42,"tag":767,"props":1441,"children":1443},{"class":769,"line":1442},16,[1444],{"type":42,"tag":767,"props":1445,"children":1446},{"emptyLinePlaceholder":783},[1447],{"type":48,"value":786},{"type":42,"tag":767,"props":1449,"children":1451},{"class":769,"line":1450},17,[1452],{"type":42,"tag":767,"props":1453,"children":1454},{},[1455],{"type":48,"value":1456},"# sorted() → the item→step_id mapping is stable across runs (R1 determinism).\n",{"type":42,"tag":767,"props":1458,"children":1460},{"class":769,"line":1459},18,[1461],{"type":42,"tag":767,"props":1462,"children":1463},{},[1464],{"type":48,"value":1465},"files = sorted(\n",{"type":42,"tag":767,"props":1467,"children":1469},{"class":769,"line":1468},19,[1470],{"type":42,"tag":767,"props":1471,"children":1472},{},[1473],{"type":48,"value":1474},"    name for name in os.listdir(target_dir)\n",{"type":42,"tag":767,"props":1476,"children":1478},{"class":769,"line":1477},20,[1479],{"type":42,"tag":767,"props":1480,"children":1481},{},[1482],{"type":48,"value":1483},"    if os.path.isfile(os.path.join(target_dir, name))\n",{"type":42,"tag":767,"props":1485,"children":1487},{"class":769,"line":1486},21,[1488],{"type":42,"tag":767,"props":1489,"children":1490},{},[1491],{"type":48,"value":1492},")\n",{"type":42,"tag":767,"props":1494,"children":1496},{"class":769,"line":1495},22,[1497],{"type":42,"tag":767,"props":1498,"children":1499},{"emptyLinePlaceholder":783},[1500],{"type":48,"value":786},{"type":42,"tag":767,"props":1502,"children":1504},{"class":769,"line":1503},23,[1505],{"type":42,"tag":767,"props":1506,"children":1507},{"emptyLinePlaceholder":783},[1508],{"type":48,"value":786},{"type":42,"tag":767,"props":1510,"children":1512},{"class":769,"line":1511},24,[1513],{"type":42,"tag":767,"props":1514,"children":1515},{},[1516],{"type":48,"value":1517},"def summarize(filename: str):\n",{"type":42,"tag":767,"props":1519,"children":1521},{"class":769,"line":1520},25,[1522],{"type":42,"tag":767,"props":1523,"children":1524},{},[1525],{"type":48,"value":1526},"    path = os.path.join(target_dir, filename)\n",{"type":42,"tag":767,"props":1528,"children":1530},{"class":769,"line":1529},26,[1531],{"type":42,"tag":767,"props":1532,"children":1533},{},[1534],{"type":48,"value":1535},"    try:\n",{"type":42,"tag":767,"props":1537,"children":1539},{"class":769,"line":1538},27,[1540],{"type":42,"tag":767,"props":1541,"children":1542},{},[1543],{"type":48,"value":1544},"        # Explicit, STABLE step_id per concurrent call (R1). Read-only role\n",{"type":42,"tag":767,"props":1546,"children":1548},{"class":769,"line":1547},28,[1549],{"type":42,"tag":767,"props":1550,"children":1551},{},[1552],{"type":48,"value":1553},"        # RETURNS its summary inline (R3) — it does not write files.\n",{"type":42,"tag":767,"props":1555,"children":1557},{"class":769,"line":1556},29,[1558],{"type":42,"tag":767,"props":1559,"children":1560},{},[1561],{"type":48,"value":1562},"        handle = run_step(\n",{"type":42,"tag":767,"props":1564,"children":1566},{"class":769,"line":1565},30,[1567],{"type":42,"tag":767,"props":1568,"children":1569},{},[1570],{"type":48,"value":1571},"            provider=\"claude_code\",          # headless (R5)\n",{"type":42,"tag":767,"props":1573,"children":1575},{"class":769,"line":1574},31,[1576],{"type":42,"tag":767,"props":1577,"children":1578},{},[1579],{"type":48,"value":1580},"            agent=\"reviewer\",\n",{"type":42,"tag":767,"props":1582,"children":1584},{"class":769,"line":1583},32,[1585],{"type":42,"tag":767,"props":1586,"children":1587},{},[1588],{"type":48,"value":1589},"            prompt=f\"Summarize the file at {path} in 3 bullet points. Return the summary only.\",\n",{"type":42,"tag":767,"props":1591,"children":1593},{"class":769,"line":1592},33,[1594],{"type":42,"tag":767,"props":1595,"children":1596},{},[1597],{"type":48,"value":1598},"            step_id=f\"summarize:{filename}\",\n",{"type":42,"tag":767,"props":1600,"children":1602},{"class":769,"line":1601},34,[1603],{"type":42,"tag":767,"props":1604,"children":1605},{},[1606],{"type":48,"value":1607},"        )\n",{"type":42,"tag":767,"props":1609,"children":1611},{"class":769,"line":1610},35,[1612],{"type":42,"tag":767,"props":1613,"children":1614},{},[1615],{"type":48,"value":1616},"        return filename, handle.output\n",{"type":42,"tag":767,"props":1618,"children":1620},{"class":769,"line":1619},36,[1621],{"type":42,"tag":767,"props":1622,"children":1623},{},[1624],{"type":48,"value":1625},"    except ShimError as exc:\n",{"type":42,"tag":767,"props":1627,"children":1629},{"class":769,"line":1628},37,[1630],{"type":42,"tag":767,"props":1631,"children":1632},{},[1633],{"type":48,"value":1634},"        # Per-unit tolerance (R4): one timeout degrades to a survivor, not a 504.\n",{"type":42,"tag":767,"props":1636,"children":1638},{"class":769,"line":1637},38,[1639],{"type":42,"tag":767,"props":1640,"children":1641},{},[1642],{"type":48,"value":1643},"        return filename, f\"ERROR: {exc}\"\n",{"type":42,"tag":767,"props":1645,"children":1647},{"class":769,"line":1646},39,[1648],{"type":42,"tag":767,"props":1649,"children":1650},{"emptyLinePlaceholder":783},[1651],{"type":48,"value":786},{"type":42,"tag":767,"props":1653,"children":1655},{"class":769,"line":1654},40,[1656],{"type":42,"tag":767,"props":1657,"children":1658},{"emptyLinePlaceholder":783},[1659],{"type":48,"value":786},{"type":42,"tag":767,"props":1661,"children":1663},{"class":769,"line":1662},41,[1664],{"type":42,"tag":767,"props":1665,"children":1666},{},[1667],{"type":48,"value":1668},"with ThreadPoolExecutor(max_workers=max_workers) as pool:\n",{"type":42,"tag":767,"props":1670,"children":1672},{"class":769,"line":1671},42,[1673],{"type":42,"tag":767,"props":1674,"children":1675},{},[1676],{"type":48,"value":1677},"    results = dict(pool.map(summarize, files))\n",{"type":42,"tag":767,"props":1679,"children":1681},{"class":769,"line":1680},43,[1682],{"type":42,"tag":767,"props":1683,"children":1684},{"emptyLinePlaceholder":783},[1685],{"type":48,"value":786},{"type":42,"tag":767,"props":1687,"children":1689},{"class":769,"line":1688},44,[1690],{"type":42,"tag":767,"props":1691,"children":1692},{},[1693],{"type":48,"value":1694},"# Big output → write to a file, return the path (big-outputs discipline).\n",{"type":42,"tag":767,"props":1696,"children":1698},{"class":769,"line":1697},45,[1699],{"type":42,"tag":767,"props":1700,"children":1701},{},[1702],{"type":48,"value":1703},"out_path = os.path.join(target_dir, \"_summaries.json\")\n",{"type":42,"tag":767,"props":1705,"children":1707},{"class":769,"line":1706},46,[1708],{"type":42,"tag":767,"props":1709,"children":1710},{},[1711],{"type":48,"value":1712},"with open(out_path, \"w\") as fh:\n",{"type":42,"tag":767,"props":1714,"children":1716},{"class":769,"line":1715},47,[1717],{"type":42,"tag":767,"props":1718,"children":1719},{},[1720],{"type":48,"value":1721},"    import json\n",{"type":42,"tag":767,"props":1723,"children":1725},{"class":769,"line":1724},48,[1726],{"type":42,"tag":767,"props":1727,"children":1728},{},[1729],{"type":48,"value":1730},"    json.dump(results, fh, indent=2)\n",{"type":42,"tag":767,"props":1732,"children":1734},{"class":769,"line":1733},49,[1735],{"type":42,"tag":767,"props":1736,"children":1737},{"emptyLinePlaceholder":783},[1738],{"type":48,"value":786},{"type":42,"tag":767,"props":1740,"children":1742},{"class":769,"line":1741},50,[1743],{"type":42,"tag":767,"props":1744,"children":1745},{},[1746],{"type":48,"value":1747},"emit_output({\"summarized\": len(results), \"output_file\": out_path})\n",{"type":42,"tag":51,"props":1749,"children":1750},{},[1751],{"type":48,"value":1752},"Validate it, ask the user, then run with a pre-announced run-id:",{"type":42,"tag":440,"props":1754,"children":1757},{"className":1755,"code":1756,"language":48},[443],"cao workflow validate ~\u002F.aws\u002Fcli-agent-orchestrator\u002Fworkflows\u002Fsummarize_dir.py\n# fix findings, then — after the user approves:\ncao workflow run summarize_dir --run-id sum-1 --json &\n",[1758],{"type":42,"tag":65,"props":1759,"children":1760},{"__ignoreMap":448},[1761],{"type":48,"value":1756},{"type":42,"tag":1763,"props":1764,"children":1765},"style",{},[1766],{"type":48,"value":1767},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"items":1769,"total":1442},[1770,1789,1804,1816,1832,1845,1859],{"slug":1771,"name":1771,"fn":1772,"description":1773,"org":1774,"tags":1775,"stars":26,"repoUrl":27,"updatedAt":1788},"add-app-to-server","add interactive UI to MCP servers","This skill should be used when the user asks to \"add an app to my MCP server\", \"add UI to my MCP server\", \"add a view to my MCP tool\", \"enrich MCP tools with UI\", \"add interactive UI to existing server\", \"add MCP Apps to my server\", or needs to add interactive UI capabilities to an existing MCP server that already has tools. Provides guidance for analyzing existing tools and adding MCP Apps UI resources.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1776,1779,1782,1785],{"name":1777,"slug":1778,"type":16},"Frontend","frontend",{"name":1780,"slug":1781,"type":16},"MCP","mcp",{"name":1783,"slug":1784,"type":16},"Plugin Development","plugin-development",{"name":1786,"slug":1787,"type":16},"UI Components","ui-components","2026-07-12T08:41:40.4008",{"slug":1790,"name":1790,"fn":1791,"description":1792,"org":1793,"tags":1794,"stars":26,"repoUrl":27,"updatedAt":1803},"agui-author","emit interactive dashboard UI components","Author live dashboard UI from an agent via the `emit_ui` MCP tool. Emit one of six allow-listed components (approval_card, choice_prompt, diff_summary, progress, metric, agent_card) with JSON props and it renders in any AG-UI client watching the fleet. Use when you want the operator to see a decision, a diff, or a status readout instead of scrolling terminal text. Arbitrary HTML\u002Fmarkup is refused.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1795,1798,1801,1802],{"name":1796,"slug":1797,"type":16},"Agents","agents",{"name":1799,"slug":1800,"type":16},"Dashboards","dashboards",{"name":1780,"slug":1781,"type":16},{"name":1786,"slug":1787,"type":16},"2026-07-22T05:35:50.851108",{"slug":1805,"name":1805,"fn":1806,"description":1807,"org":1808,"tags":1809,"stars":26,"repoUrl":27,"updatedAt":1815},"cao-agent-routing","route tasks to appropriate CAO agents","Find and select the best installed CAO agent profile for a task before delegating with assign or handoff. Use when a supervisor needs to route coding, documentation, infrastructure, review, research, or other specialist work and the user has not already chosen an agent profile.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1810,1811,1814],{"name":1796,"slug":1797,"type":16},{"name":1812,"slug":1813,"type":16},"AWS","aws",{"name":21,"slug":22,"type":16},"2026-07-25T05:56:34.255071",{"slug":1817,"name":1817,"fn":1818,"description":1819,"org":1820,"tags":1821,"stars":26,"repoUrl":27,"updatedAt":1831},"cao-learning","report task outcomes and distill lessons","Report task outcomes and distill lessons so the team improves across runs — report_outcome after each unit of work, retrospector handoffs at natural boundaries, and applying injected lessons. Use in workflows that run repeatedly over similar work items. Requires memory.learning_enabled; degrade silently when the tools report disabled.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1822,1825,1828],{"name":1823,"slug":1824,"type":16},"Best Practices","best-practices",{"name":1826,"slug":1827,"type":16},"Engineering","engineering",{"name":1829,"slug":1830,"type":16},"Operations","operations","2026-07-29T06:00:28.147989",{"slug":1833,"name":1833,"fn":1834,"description":1835,"org":1836,"tags":1837,"stars":26,"repoUrl":27,"updatedAt":1844},"cao-mcp-apps","operate CAO MCP application surfaces","Enable, operate, and extend CAO's MCP Apps surface — the host-rendered fleet dashboard visible inside MCP App hosts (Claude Desktop, ChatGPT, VS Code Copilot, Goose, Postman). Use when the user says \"enable MCP Apps in CAO\", \"the ui:\u002F\u002Fcao views aren't rendering\", \"rebuild MCP Apps bundles\", \"add a new ui:\u002F\u002Fcao\u002F* view\", or \"configure the MCP Apps OAuth scope layer\". Operates on the CAO_MCP_APPS_ENABLED surface and cao_mcp_apps\u002F build system. Not for the localhost:9889 browser dashboard, not for plugins, providers, or session management.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1838,1839,1842,1843],{"name":1796,"slug":1797,"type":16},{"name":1840,"slug":1841,"type":16},"CLI","cli",{"name":1780,"slug":1781,"type":16},{"name":1786,"slug":1787,"type":16},"2026-07-22T05:35:52.952289",{"slug":1846,"name":1846,"fn":1847,"description":1848,"org":1849,"tags":1850,"stars":26,"repoUrl":27,"updatedAt":1858},"cao-memory","manage durable agent memory and preferences","Store, recall, and forget durable facts with CAO memory — user preferences, project conventions, decisions, and corrections that should persist across sessions and agents. Use proactively to check memory before asking the user, and to save anything worth remembering. Distinct from any provider-native memory.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1851,1852,1855],{"name":1796,"slug":1797,"type":16},{"name":1853,"slug":1854,"type":16},"Memory","memory",{"name":1856,"slug":1857,"type":16},"Productivity","productivity","2026-07-12T08:37:03.180421",{"slug":1860,"name":1860,"fn":1861,"description":1862,"org":1863,"tags":1864,"stars":26,"repoUrl":27,"updatedAt":1869},"cao-plugin","scaffold CAO agent plugins","Create a new CAO (CLI Agent Orchestrator) plugin. Use this skill whenever the user wants to add a plugin that reacts to CAO lifecycle or messaging events, scaffold a plugin package, understand plugin requirements, or integrate an external system (Discord, Slack, dashboards, logging, metrics) with CAO. Also use when the user asks what plugin events are available, how plugin discovery works, or how to install a plugin into a CAO environment.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1865,1866,1867,1868],{"name":1796,"slug":1797,"type":16},{"name":14,"slug":15,"type":16},{"name":1840,"slug":1841,"type":16},{"name":1783,"slug":1784,"type":16},"2026-07-12T08:36:49.784639",{"items":1871,"total":2047},[1872,1891,1912,1922,1935,1948,1958,1968,1989,2004,2019,2032],{"slug":1873,"name":1873,"fn":1874,"description":1875,"org":1876,"tags":1877,"stars":1888,"repoUrl":1889,"updatedAt":1890},"agentcore-investigation","investigate Bedrock AgentCore runtime sessions","Investigate Bedrock AgentCore runtime sessions via CloudWatch Logs Insights — resolve session\u002Ftrace IDs, query OTEL spans, filter noise, build timelines. Use when debugging AgentCore agent sessions, tracing tool calls, or analyzing latency.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1878,1879,1882,1885],{"name":1812,"slug":1813,"type":16},{"name":1880,"slug":1881,"type":16},"Debugging","debugging",{"name":1883,"slug":1884,"type":16},"Logs","logs",{"name":1886,"slug":1887,"type":16},"Observability","observability",9427,"https:\u002F\u002Fgithub.com\u002Fawslabs\u002Fmcp","2026-07-12T08:37:22.601527",{"slug":1892,"name":1893,"fn":1894,"description":1895,"org":1896,"tags":1897,"stars":1888,"repoUrl":1889,"updatedAt":1911},"amazon-aurora-dsql","amazon aurora dsql","build applications with Aurora DSQL","Build with Aurora DSQL — manage schemas, execute queries, handle migrations, diagnose query plans, load data, and develop applications with a serverless, distributed SQL database. Covers IAM auth, multi-tenant patterns, MySQL-to-DSQL and PostgreSQL-to-DSQL schema conversion, FK replacement code generation, OCC retry patterns, ORM migration (Django\u002FHibernate\u002FRails), DDL operations, query plan explainability, SQL compatibility validation, and bulk data loading. Triggers on phrases like: DSQL, Aurora DSQL, create DSQL table, DSQL schema, migrate to DSQL, distributed SQL database, serverless PostgreSQL-compatible database, DSQL query plan, DSQL EXPLAIN ANALYZE, why is my DSQL query slow, DSQL foreign key, DSQL OCC retry, DSQL multi-region, load into DSQL, load CSV into DSQL, bulk load DSQL, aurora-dsql-loader.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1898,1901,1902,1905,1908],{"name":1899,"slug":1900,"type":16},"Aurora","aurora",{"name":1812,"slug":1813,"type":16},{"name":1903,"slug":1904,"type":16},"Database","database",{"name":1906,"slug":1907,"type":16},"Serverless","serverless",{"name":1909,"slug":1910,"type":16},"SQL","sql","2026-07-12T08:36:45.053393",{"slug":1913,"name":1914,"fn":1894,"description":1895,"org":1915,"tags":1916,"stars":1888,"repoUrl":1889,"updatedAt":1921},"aurora-dsql","aurora dsql",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1917,1918,1919,1920],{"name":1812,"slug":1813,"type":16},{"name":1903,"slug":1904,"type":16},{"name":1906,"slug":1907,"type":16},{"name":1909,"slug":1910,"type":16},"2026-07-12T08:36:42.694299",{"slug":1923,"name":1924,"fn":1894,"description":1895,"org":1925,"tags":1926,"stars":1888,"repoUrl":1889,"updatedAt":1934},"aws-dsql","aws dsql",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1927,1928,1929,1932,1933],{"name":1812,"slug":1813,"type":16},{"name":1903,"slug":1904,"type":16},{"name":1930,"slug":1931,"type":16},"Migration","migration",{"name":1906,"slug":1907,"type":16},{"name":1909,"slug":1910,"type":16},"2026-07-12T08:36:38.584057",{"slug":1936,"name":1937,"fn":1894,"description":1895,"org":1938,"tags":1939,"stars":1888,"repoUrl":1889,"updatedAt":1947},"distributed-postgres","distributed postgres",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1940,1941,1942,1945,1946],{"name":1812,"slug":1813,"type":16},{"name":1903,"slug":1904,"type":16},{"name":1943,"slug":1944,"type":16},"PostgreSQL","postgresql",{"name":1906,"slug":1907,"type":16},{"name":1909,"slug":1910,"type":16},"2026-07-12T08:36:46.530743",{"slug":1949,"name":1950,"fn":1894,"description":1895,"org":1951,"tags":1952,"stars":1888,"repoUrl":1889,"updatedAt":1957},"distributed-sql","distributed sql",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1953,1954,1955,1956],{"name":1812,"slug":1813,"type":16},{"name":1903,"slug":1904,"type":16},{"name":1906,"slug":1907,"type":16},{"name":1909,"slug":1910,"type":16},"2026-07-12T08:36:48.104182",{"slug":1959,"name":1959,"fn":1894,"description":1895,"org":1960,"tags":1961,"stars":1888,"repoUrl":1889,"updatedAt":1967},"dsql",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1962,1963,1964,1965,1966],{"name":1812,"slug":1813,"type":16},{"name":1903,"slug":1904,"type":16},{"name":1930,"slug":1931,"type":16},{"name":1906,"slug":1907,"type":16},{"name":1909,"slug":1910,"type":16},"2026-07-12T08:36:36.374512",{"slug":1969,"name":1969,"fn":1970,"description":1971,"org":1972,"tags":1973,"stars":1986,"repoUrl":1987,"updatedAt":1988},"cost-efficiency-analyzer","analyze cost efficiency and expenses","Analyzes cost structure, cost efficiency, and expense management from P&L data. Use when the user asks about costs, expenses, COGS, operating expenses, cost ratios, cost control, spending efficiency, margin compression from cost side, or wants to understand where money is going. Also use for \"are we spending too much\", \"cost breakdown\", \"expense analysis\", or \"how efficient are our operations\". NOT for revenue or top-line analysis.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1974,1977,1980,1983],{"name":1975,"slug":1976,"type":16},"Accounting","accounting",{"name":1978,"slug":1979,"type":16},"Analytics","analytics",{"name":1981,"slug":1982,"type":16},"Cost Optimization","cost-optimization",{"name":1984,"slug":1985,"type":16},"Finance","finance",3176,"https:\u002F\u002Fgithub.com\u002Fawslabs\u002Fagentcore-samples","2026-07-12T08:40:03.29555",{"slug":1990,"name":1990,"fn":1991,"description":1992,"org":1993,"tags":1994,"stars":1986,"repoUrl":1987,"updatedAt":2003},"executive-financial-briefing","generate executive financial briefings","Generates a concise executive-level financial briefing or summary suitable for a CEO, CFO, or board presentation. Use when the user asks for a summary, briefing, executive summary, board update, financial overview, financial health check, or \"how is the business doing\". Covers the full P&L picture in one page. Also use for \"give me the highlights\", \"what do I need to know\", or \"quick financial update\".",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1995,1996,1997,2000],{"name":1812,"slug":1813,"type":16},{"name":1984,"slug":1985,"type":16},{"name":1998,"slug":1999,"type":16},"Management","management",{"name":2001,"slug":2002,"type":16},"Reporting","reporting","2026-07-12T08:40:02.066471",{"slug":2005,"name":2005,"fn":2006,"description":2007,"org":2008,"tags":2009,"stars":1986,"repoUrl":1987,"updatedAt":2018},"multi-quarter-trend-analysis","analyze multi-quarter financial trends","Analyzes financial trends across multiple quarters by comparing P&L metrics over time. Use when the user wants to see trends, patterns, trajectories, or directional movement across 3 or more quarters. Also use for \"how are we trending\", \"show me the trend\", \"track performance over time\", \"quarter over quarter comparison across all quarters\", or any multi-period longitudinal analysis.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2010,2011,2012,2015],{"name":1978,"slug":1979,"type":16},{"name":1984,"slug":1985,"type":16},{"name":2013,"slug":2014,"type":16},"Financial Statements","financial-statements",{"name":2016,"slug":2017,"type":16},"Variance Analysis","variance-analysis","2026-07-12T08:40:00.79141",{"slug":2020,"name":2020,"fn":2021,"description":2022,"org":2023,"tags":2024,"stars":1986,"repoUrl":1987,"updatedAt":2031},"pdf","process and manipulate PDF documents","Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text\u002Ftables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting\u002Fdecrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2025,2026,2029],{"name":14,"slug":15,"type":16},{"name":2027,"slug":2028,"type":16},"Documents","documents",{"name":2030,"slug":2020,"type":16},"PDF","2026-07-12T08:41:44.135656",{"slug":2033,"name":2033,"fn":2034,"description":2035,"org":2036,"tags":2037,"stars":1986,"repoUrl":1987,"updatedAt":2046},"quarterly-kpi-calculator","calculate quarterly financial KPIs","Calculates quarterly financial KPIs from P&L data. P&L figures can be provided directly by the user or fetched from the financial data MCP server. Use when the user wants KPI calculations such as Gross Margin %, EBITDA Margin %, Operating Expense Ratio, or Revenue Growth % QoQ. Also use for quarterly performance review, P&L analysis, or interpreting financial ratios against benchmarks.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2038,2039,2042,2043],{"name":1975,"slug":1976,"type":16},{"name":2040,"slug":2041,"type":16},"Data Analysis","data-analysis",{"name":1984,"slug":1985,"type":16},{"name":2044,"slug":2045,"type":16},"KPI","kpi","2026-07-12T08:39:59.54971",150]