@controllerai/cli 0.2.20 → 0.2.22

package/skills/manifest.json

@@ -1,29 +1,29 @@
 {
   "schemaVersion": 1,
-  "skillSetVersion": "2026.09.06.4",
+  "skillSetVersion": "2026.09.15.2",
   "minCliVersion": "0.2.0",
-  "latestCliVersion": "0.2.20",
+  "latestCliVersion": "0.2.22",
   "skills": [
     {
       "name": "controllerai-start",
       "files": [
         {
           "path": "controllerai-start/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-start/SKILL.md",
-          "sha256": "68ee25aa5b3aebeb980d488a57bb4e3d5057fec2214d6769d84e56388ec37eec",
-          "size": 6424
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-start/SKILL.md",
+          "sha256": "5034c98ea02fe27fdb492a768c025deee7724a77e053e9d7ab204ce72b34cb08",
+          "size": 11414
         },
         {
           "path": "controllerai-start/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-start/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-start/agents/openai.yaml",
           "sha256": "3240c24df8ba5ebfb67bc3e9dbce97f4a78384c352123210197a2dbf27c51150",
           "size": 226
         },
         {
           "path": "controllerai-start/references/mcp-tool-map.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-start/references/mcp-tool-map.md",
-          "sha256": "856d376fd9b682b6b875504b6fa50e0986ab8bd52a09a160c5a9a117980293ef",
-          "size": 26708
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-start/references/mcp-tool-map.md",
+          "sha256": "d293310ed5fd7c7495579f717df0fa9ea59f27d5e494ca6bfb805f9975186ce9",
+          "size": 26919
         }
       ]
     },
@@ -32,27 +32,21 @@
       "files": [
         {
           "path": "controllerai-workflows/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-workflows/SKILL.md",
-          "sha256": "9a90de43233950e7514078cdb215ad65312a4b5c2e2a9638cacff90c49835239",
-          "size": 4219
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-workflows/SKILL.md",
+          "sha256": "a2419265809b6f822ed22be4cfbfc1c56107e7afffffc41a0f527fd93018dc8a",
+          "size": 9472
         },
         {
           "path": "controllerai-workflows/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-workflows/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-workflows/agents/openai.yaml",
           "sha256": "6fb00a93a5f83fc2664679eb633ab07b477105472f8790fcf6dbcca913921a84",
           "size": 251
         },
         {
           "path": "controllerai-workflows/references/command-map.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-workflows/references/command-map.md",
-          "sha256": "0911a52ac5d107d23c785343de537d31ef50982468f6ecdc720197fcb658f419",
-          "size": 4183
-        },
-        {
-          "path": "controllerai-workflows/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-workflows/references/command-reference.md",
-          "sha256": "47af388e64fe90c8801ae01d036c4bce732bd85f6887198c15d9e86317c838d4",
-          "size": 9732
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-workflows/references/command-map.md",
+          "sha256": "b99adeb3ff1e9c441805f533191c6b4435007ce8522d7965b4856f90db118e1a",
+          "size": 2126
         }
       ]
     },
@@ -61,27 +55,21 @@
       "files": [
         {
           "path": "controllerai-node-config/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-node-config/SKILL.md",
-          "sha256": "ca08876180e89012dac89b053ebea06feca590246220a725adbebd24df82b9b4",
-          "size": 3341
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-node-config/SKILL.md",
+          "sha256": "fb7ad0999e772079d7ce94f25d9fddca9b483b81a11bbaba47d618825d5585fe",
+          "size": 11614
         },
         {
           "path": "controllerai-node-config/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-node-config/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-node-config/agents/openai.yaml",
           "sha256": "7fbd6f0c1f9ea40c41051d532736a4718895cfa397608a2c716300bcf4256df1",
           "size": 242
         },
-        {
-          "path": "controllerai-node-config/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-node-config/references/command-reference.md",
-          "sha256": "ab71dc4bb614003b44496fb8bdf4661ebe6fc379337ced927268c5ceaaa6d284",
-          "size": 10761
-        },
         {
           "path": "controllerai-node-config/references/prop-and-readiness.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-node-config/references/prop-and-readiness.md",
-          "sha256": "9ac3cf181af585244689508d7999600f5c0059ae41caa30e07696a352e62cabe",
-          "size": 7371
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-node-config/references/prop-and-readiness.md",
+          "sha256": "6a1aa046bac6c5f1a68cbe242bdeb584f9a01e2de7248742460064a4d2708f75",
+          "size": 5583
         }
       ]
     },
@@ -90,27 +78,21 @@
       "files": [
         {
           "path": "controllerai-expressions/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-expressions/SKILL.md",
-          "sha256": "359f9b6a439c9910debcf92a5d115fdaf0c46b38b2e2356530835af4195a2144",
-          "size": 3995
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-expressions/SKILL.md",
+          "sha256": "01240f493ec5bbd1ed562f988d243e3797577eee5ccc9d207f8bc45485b99108",
+          "size": 10310
         },
         {
           "path": "controllerai-expressions/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-expressions/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-expressions/agents/openai.yaml",
           "sha256": "280d1f4d0a44cb5cfd3e5649e0a123b91b57b1484dcbc3a02ace988233234bc3",
           "size": 249
         },
-        {
-          "path": "controllerai-expressions/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-expressions/references/command-reference.md",
-          "sha256": "46701b5fbd5ccfaf56e84efde4f3725332d4585f6cbafb99ce8909f60f3b4507",
-          "size": 10015
-        },
         {
           "path": "controllerai-expressions/references/dsl-and-recipes.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-expressions/references/dsl-and-recipes.md",
-          "sha256": "81259b8b2a366e6ff607dd1557ab48c12e90805426388d4f238d0bfacb7b86ec",
-          "size": 4539
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-expressions/references/dsl-and-recipes.md",
+          "sha256": "efe4a5eba0ea7636387443af0a6cc082a41209404b92c3af5c8a029075db70f6",
+          "size": 5197
         }
       ]
     },
@@ -119,27 +101,21 @@
       "files": [
         {
           "path": "controllerai-flow-control/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-flow-control/SKILL.md",
-          "sha256": "075a9f5e57eedf0141506ecc30021c8eab5cb2c6817ebc40a9bba539146e3455",
-          "size": 2956
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-flow-control/SKILL.md",
+          "sha256": "c535a1ff61cc65cca53af083081935dc8672f7ce5d048dbb29334808428feec3",
+          "size": 11563
         },
         {
           "path": "controllerai-flow-control/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-flow-control/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-flow-control/agents/openai.yaml",
           "sha256": "164adf3b887bf9f67bba9cd210b5b49935c29ea0f52f76325fe5df517d279592",
           "size": 229
         },
-        {
-          "path": "controllerai-flow-control/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-flow-control/references/command-reference.md",
-          "sha256": "cfcf9bfeb1a613ad8187c7cdb5262e59787d50d2dcc20ef6e99dc822c3a31a79",
-          "size": 9968
-        },
         {
           "path": "controllerai-flow-control/references/patterns.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-flow-control/references/patterns.md",
-          "sha256": "21db644561770d97306bb16951f46b959c058bf489d104ffac78779ed9b57da5",
-          "size": 5631
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-flow-control/references/patterns.md",
+          "sha256": "f1a718de837dc541e58914f40b4a89e6e81ba80afac37731e381db73a4712d90",
+          "size": 4901
         }
       ]
     },
@@ -148,27 +124,21 @@
       "files": [
         {
           "path": "controllerai-runs/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-runs/SKILL.md",
-          "sha256": "1d34701659ccd6d85cd6e58045a320b433663afb2ab36e129e8e207c81eddbbe",
-          "size": 3193
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-runs/SKILL.md",
+          "sha256": "5eeda1f95f8c18c12b968d6c2ea9008c2dd99d8953268c4ffd06652f43a91516",
+          "size": 9196
         },
         {
           "path": "controllerai-runs/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-runs/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-runs/agents/openai.yaml",
           "sha256": "63180f12974e19ce7b714695944608760e4132bfb88947543e52616098a88f5c",
           "size": 234
         },
-        {
-          "path": "controllerai-runs/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-runs/references/command-reference.md",
-          "sha256": "3da84da5b6978ae5db60d131b39c2128fde5a54ad0760309dc497fdfd50aea23",
-          "size": 6459
-        },
         {
           "path": "controllerai-runs/references/debugging.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-runs/references/debugging.md",
-          "sha256": "8e4bdb686b766d1babf02a2a688e7f43c63b3a09430c2695b18515f3c6a36daa",
-          "size": 2375
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-runs/references/debugging.md",
+          "sha256": "341f9e056445bdffdcc67771fd62b28fb2125a661d5d8a5c4fb16bcac57417c0",
+          "size": 3127
         }
       ]
     },
@@ -177,27 +147,21 @@
       "files": [
         {
           "path": "controllerai-triggers/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-triggers/SKILL.md",
-          "sha256": "30b0d8b55b3feb246ac1a0e3e42add598483b5eaac9b5ec2c38c65e45e53764d",
-          "size": 2456
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-triggers/SKILL.md",
+          "sha256": "c8a88bb69a0e032f1fd2716e1a2cd0690e62ae0b9bb996bf30643d4bd3b8fab2",
+          "size": 11800
         },
         {
           "path": "controllerai-triggers/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-triggers/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-triggers/agents/openai.yaml",
           "sha256": "56aa1bd33e54045d88002ade0c420be7bca37ac39433e6eedccef2e22bbd9515",
           "size": 239
         },
-        {
-          "path": "controllerai-triggers/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-triggers/references/command-reference.md",
-          "sha256": "1984522b3883624fe1e174bc5394cb5923e27916cf95dda9536040a36fdd1563",
-          "size": 9943
-        },
         {
           "path": "controllerai-triggers/references/lifecycle.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-triggers/references/lifecycle.md",
-          "sha256": "8bfdb644c6e8aefca0a33f8c184a1b86060733c6de4b02b5c3ff174801d6a8aa",
-          "size": 2954
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-triggers/references/lifecycle.md",
+          "sha256": "4dce6484b6abaa0eaf4ddbe366e60480180fc5b5aeb7e3c975bbe316b88dc0e5",
+          "size": 3340
         }
       ]
     },
@@ -206,27 +170,21 @@
       "files": [
         {
           "path": "controllerai-data/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-data/SKILL.md",
-          "sha256": "1491f1473cf4533450366882993de5e4ffb67e65f92a82ea843ca04658299bbe",
-          "size": 5965
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-data/SKILL.md",
+          "sha256": "1418b287af30968634c69dbdbd54d22354f5f79f52389e6d1c94a87421c20e78",
+          "size": 12059
         },
         {
           "path": "controllerai-data/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-data/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-data/agents/openai.yaml",
           "sha256": "5c54b0a714086088213c679fb904a69a599374847f9aa1d6c0756172c2a2f227",
           "size": 219
         },
-        {
-          "path": "controllerai-data/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-data/references/command-reference.md",
-          "sha256": "aa51cc377ca808f5ec53ddaba3f97f860df16b13511ed0d1c648c7783afb3cc1",
-          "size": 10057
-        },
         {
           "path": "controllerai-data/references/data-rails.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-data/references/data-rails.md",
-          "sha256": "28bd3d6d82b3fec4c74eaaf869a6f9c3cede3e3e3620fb8f45f2b38a48a1e0aa",
-          "size": 1886
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-data/references/data-rails.md",
+          "sha256": "0c03f25a099d168b8ae1fe54087ce59d06fcfc8631046927a996a88f0c4f9835",
+          "size": 2819
         }
       ]
     },
@@ -235,27 +193,21 @@
       "files": [
         {
           "path": "controllerai-ai-nodes/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-ai-nodes/SKILL.md",
-          "sha256": "d40e0f3b5f499b55a3689e6f11ad3571f56286298fb2d9727ae06b560a39d1a3",
-          "size": 2101
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-ai-nodes/SKILL.md",
+          "sha256": "4e4bdf53e300adedf5e03f282687d0d20e200baf056cd59bf8df98d7b8b21403",
+          "size": 8940
         },
         {
           "path": "controllerai-ai-nodes/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-ai-nodes/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-ai-nodes/agents/openai.yaml",
           "sha256": "3ba8b8bb6f0cd4b0d5675ebda0af10bb79dc7a42e394eb98479343c83da92599",
           "size": 256
         },
-        {
-          "path": "controllerai-ai-nodes/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-ai-nodes/references/command-reference.md",
-          "sha256": "faca6d19e5fd81a615838fccdd92591ecc8c3b2d1272a623f00cf119180125ba",
-          "size": 4520
-        },
         {
           "path": "controllerai-ai-nodes/references/selection-and-testing.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-ai-nodes/references/selection-and-testing.md",
-          "sha256": "f14e3f95aa241b9cb4f7ea4b32777e105ce0e38568e186adce2f01b4234c7484",
-          "size": 1705
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-ai-nodes/references/selection-and-testing.md",
+          "sha256": "66b235b9e81645ab877b31443505c7b07ea3f2e5a357053f266c121415f8cf5c",
+          "size": 3111
         }
       ]
     },
@@ -264,21 +216,15 @@
       "files": [
         {
           "path": "controllerai-integration-actions/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-integration-actions/SKILL.md",
-          "sha256": "35683bf52bf6b8735eaf7923e6c46cb7e0b7907db847f4a7ba8573d068402c3f",
-          "size": 2232
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-integration-actions/SKILL.md",
+          "sha256": "6c8714ec7a700961e0d0f10f842396c6da2a23fdaebb7d3c6fd110676b23a1d1",
+          "size": 10401
         },
         {
           "path": "controllerai-integration-actions/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-integration-actions/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-integration-actions/agents/openai.yaml",
           "sha256": "82ee62aa48a644e658c9bb6a78c417dc15eb4f3ec9f4abc9081b6d24d16fe92d",
           "size": 262
-        },
-        {
-          "path": "controllerai-integration-actions/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-integration-actions/references/command-reference.md",
-          "sha256": "9ab30427d89e5567b24c1f32d8105378baf9473c722845f2dff5d5eab4ed5768",
-          "size": 7023
         }
       ]
     },
@@ -287,29 +233,43 @@
       "files": [
         {
           "path": "controllerai-agents/SKILL.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-agents/SKILL.md",
-          "sha256": "2775348eb8ca46790d62fda5ac0a1295bc2ef05361b311497ebaad62254cd16c",
-          "size": 5238
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-agents/SKILL.md",
+          "sha256": "b2424b525d7ae8b80e6f23bd9b8b8c3536e6f34cc6d9abdf92fcc6df898dc1e9",
+          "size": 12167
         },
         {
           "path": "controllerai-agents/agents/openai.yaml",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-agents/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-agents/agents/openai.yaml",
           "sha256": "f4684ec904f3ebb051bb48460375756899c3316fbb16304aad5fff3d89692b09",
           "size": 293
         },
         {
-          "path": "controllerai-agents/references/command-reference.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-agents/references/command-reference.md",
-          "sha256": "496146921b57de7ce7cf27a86dcc3746784120b7e5d497015657cacbb5f223b5",
-          "size": 10918
+          "path": "controllerai-agents/references/instructions-and-versioning.md",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-agents/references/instructions-and-versioning.md",
+          "sha256": "88b059e74aef03ccb12a53815d1090e5449090ff6dfd863b6cef5a12b434cb65",
+          "size": 5644
+        }
+      ]
+    },
+    {
+      "name": "controllerai-template-setup",
+      "files": [
+        {
+          "path": "controllerai-template-setup/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-template-setup/SKILL.md",
+          "sha256": "6ed665a2b33f8197fb990a30c296a69ab1d0e334bd10998e851508fa99d2d603",
+          "size": 9316
         },
         {
-          "path": "controllerai-agents/references/instructions-and-versioning.md",
-          "url": "https://getcontroller.ai/skills/2026.09.06.4/controllerai-agents/references/instructions-and-versioning.md",
-          "sha256": "28b7220b292d42ae6b5e7cc522c0a7f00709f3a2b0fc9db9bb23126e4fac7ca9",
-          "size": 5166
+          "path": "controllerai-template-setup/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.09.15.2/controllerai-template-setup/agents/openai.yaml",
+          "sha256": "0abb1b4691e3163eb6c2f27404ce3512aabf86d048f0eedbac587415004146e3",
+          "size": 275
         }
       ]
     }
-  ]
+  ],
+  "surfaces": {
+    "mcp": "skills-mcp"
+  }
 }

package/skills-mcp/controllerai-agents/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: controllerai-agents
+description: Design, assemble, test, publish and share user-facing Controller AI agents built from instructions, knowledge files, workflow tools and ready integration actions. Use when creating or editing an agent, choosing its tool architecture, attaching tools, verifying draft or live conversations, or publishing and sharing it.
+---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+
+# Agents
+
+## Use this when
+
+- The user wants something people chat with: an assistant, a copilot, a file-enrichment helper, an internal tool with judgment.
+- An existing agent needs new instructions, tools or knowledge, or must be verified, published or shared.
+- A capability must be placed: in the agent's instructions, in a workflow tool, in a direct action, or in a knowledge file.
+
+Direct actions belong to `controllerai-integration-actions`; the workflows behind workflow tools to `controllerai-workflows`; the wider deliverable choice to `controllerai-start`.
+
+## How it works
+
+**What an agent is.** A person chats with it; it reasons, reads conversation attachments and reference knowledge, calls tools, and creates files for the user. It is the right shape for judgment, conversation and file handling; deterministic business rules, custom workflow data and multi-step processing belong in workflow tools it calls, and one catalog-marked operation from a provider integration or native registry service is a direct action. Both direct-action sources follow the same attachment and approval rules; a native action may not need a connection.
+
+**One draft, immutable versions.** Editing changes only the mutable draft, and saving the draft updates the owner-only Test environment at once. Publishing snapshots the display name, instructions, tool identities, descriptions, approval policies and knowledge files into a new immutable version, moves the live pointer, and restamps every existing live conversation to it; that cutover interrupts in-flight answers and expires pending approvals. The runtime model is not part of the snapshot. There is no rollback: a bad version is corrected forward.
+
+**Test versus Live.**
+
+| Context | Test (draft) conversation | Live (shared) conversation |
+| --- | --- | --- |
+| Agent configuration | Current mutable draft | Latest published immutable agent version |
+| Workflow tools | Each workflow's current development head | Each workflow's latest live release; never pinned |
+| Reference files | Current draft knowledge files | Knowledge frozen into the published agent version |
+| Runtime files | Current live runtime files, overlaid by development/test runtime files at the same path | Current live runtime files only |
+| Access | Owner only | Owner, plus organization members when shared; non-owners never see the draft |
+
+**Three kinds of files.** Conversation attachments belong to one chat. Knowledge is versioned reference material in the draft: text types only (`txt`, `md`, `json`, `csv`, `html`, `xml`), each added once under the name the agent should see. When the user asks for a PDF or another unsupported format, store a supported text type under the plain requested name and say why; a name that still carries the wrong extension is not the same document. Shared runtime files are live workspace state, visible without a publish, and no substitute for an upload. Paths come from returned metadata; runtime mounts can prefix them.
+
+**Live-bound state.** Enabling or disabling is runtime state, independent of publication: disabling pauses live use, while the owner's Test conversations still work. A workflow publish changes every live agent that follows that workflow without an agent publish, and live workflow resolution is cached per session, so an in-flight turn may finish on the prior release. When a direct action needs a connection, that connection is a live grant: rebinding redirects it and revocation blocks it immediately. Detachment blocks every direct action immediately and still needs a later agent publish to remove the tool from the published list.
+
+**Slack approvals.** Approval requests can also go to Slack through `slackRoute`. Routes are draft tool settings published with the agent like approval settings. Test conversations use the draft; live ones use the published version. Only the connection owner and configured approvers can answer in Slack; the app's approval card still works.
+
+**Runtime usage.** Test and live conversations consume the organization's runtime usage and cause the connected providers' side effects; the builder's own subscription pays only for building.
+
+## Rules
+
+1. **Instructions hold judgment; tools hold work; knowledge holds sources.** Each tool description says when to use it, what to pass, what comes back.
+2. **Test every workflow tool on development before attaching it**, with a non-empty output contract the run actually returns, unless the user declined that test and asked for the attachment anyway.
+3. **Decide the approval policy before attaching a consequential tool.** The default is no approval, which is right for reads and searches; for a tool that sends, posts, spends or deletes, choose `requireConfirmation` or explicitly tell the user it will run unattended, and mention the choice in the report to the user. The policy is a runtime setting for the agent's users, not a permission gate on your own work, so honor a policy the user already specified.
+4. **Never promise a pinned workflow tool.** Live tools follow the latest release and nothing else is supported; when asked to freeze one, explain that, ask whether following the latest release is acceptable, and finish the independent work meanwhile.
+5. **One conversation per verification task, on an explicit rail.** Reuse its ID for follow-ups and approvals; never resend the request or open a replacement after an approval pause, and never approve merely to continue.
+6. **Resolve the task's pending requests, in its conversation and within the user's scope, before publishing**, because a publish expires the unexecuted requests in the affected live conversations.
+7. **Draft-only means stop at Test evidence.** Readiness authorizes nothing; a draft never proves the live agent.
+8. **Publish in dependency order**: attached workflows the user authorized, then agent preflight, then the agent, then one fresh live conversation. A preflight blocker on an unfinished workflow tool is cleared by detaching that tool; never delete its flow or publish the workflow to make preflight pass, because both release or destroy work the user did not ask to ship.
+9. **Failure instructions are specific.** Say what failed and what was attempted, retry at most once, distinguish reads from rejected validation from uncertain mutations, and name the integration when a connection breaks.
+10. **Keep internals out of the runtime user's view**: no workflow, flow, node, rail, prop or version names in instructions or replies.
+
+## Recipes
+
+### Create the draft
+
+- `agent_list` — `ownership`, `search`
+- `agent_create` — `disabled`, `instructions`, `name`
+- `agent_get` — `agentId`
+
+`agent_create` takes the complete Markdown in `instructions`; there is no file to read.
+A draft is private and by default enabled on creation, so the user can open it and start testing at once; nothing is live until a publish. Write instructions from the template in [references/instructions-and-versioning.md](references/instructions-and-versioning.md) and delete every sentence that does not change behavior.
+
+### Attach tools and knowledge
+
+- `run_flow` — `flowId`, `confirmLive`, `inputs`, `target`, `waitSeconds`, `workflowId`
+- `agent_tool_workflow_add` — `agentId`, `description`, `flow`, `requireConfirmation`, `workflowId`, `slackRoute`
+- `agent_knowledge_file_add` — `agentId`, `content`, `name`, `type` / `agent_workspace_file_add` — `agentId`, `content`, `name`, `space`, `type`
+- `agent_tool_list` — `agentId`
+- `agent_file_list` — `agentId`, `cursor`, `environment`, `folderPrefix`, `limit`, `live`, `search`, `space`
+
+`agent_tool_workflow_add` and `agent_tool_action_add` take `requireConfirmation`, optional and `false` by default. Files travel inline: `agent_knowledge_file_add` (`name`, `type`, `content`) for knowledge, `agent_workspace_file_add` with `space` for shared runtime files (live immediately); each call creates another file, so read the result before a second call. `agent_file_list` filters runtime files by `environment`.
+Flow inputs become the tool's parameters and its outputs the result.
+
+### Verify in Test
+
+- `agent_test` — `agentId`, `message`, `model`, `waitSeconds`, `title`, `rail`
+- `agent_conversation_create` — `agentId`, `model`, `title`, `rail`
+- `agent_conversation_send` — `conversationId`, `message`, `waitSeconds`
+- `agent_conversation_history` — `conversationId`, `last`
+- `agent_conversation_approve` — `conversationId`, `requestId`
+- `agent_conversation_deny` — `conversationId`, `message`, `requestId`
+
+`agent_test` takes `rail: "draft"` or `"live"` and `waitSeconds`; `agent_conversation_send` takes `waitSeconds`; when a wait returns unfinished, poll `agent_conversation_status` and read `agent_conversation_history` for that conversation instead of sending again; approve and deny take the `requestId` of the pending request.
+`agent_test` is a one-shot that always creates a conversation; use `agent_conversation_create` and `agent_conversation_send` when follow-up or an approval may be needed.
+ Test positive and negative tool selection, exact arguments, results, errors and knowledge. A workflow tool's side effect is proved by its terminal workflow execution; a direct action by its persisted action events, result and external effect, never by an execution ID it does not have. After removing a tool, test one request that must no longer use it and one that still uses a retained tool. Say before the first test that it consumes runtime usage and may reach providers.
+
+### Publish and share
+
+- `workflow_status` — `workflowId`
+- `workflow_publish` — `acknowledgeDualDispatch`, `acknowledgeValidationErrors`, `name`, `workflowId`
+- `agent_get` — `agentId`
+- `agent_publish_preflight` — `agentId`
+- `agent_publish` — `agentId`, `name`
+- `agent_version_list` — `agentId`
+- `agent_test` — `agentId`, `message`, `model`, `waitSeconds`, `title`, `rail`
+- `agent_visibility_set` — `agentId`, `value`
+
+`workflow_status` and `workflow_publish` take the explicit `workflowId` of each attached workflow; `agent_get` reports `hasUnpublishedChanges`; `agent_version_list` is the release history; `agent_visibility_set` takes `value`.
+Publish an attached workflow only when its verified development state must go live and the user authorized it. `hasUnpublishedChanges` on the agent read says whether a publish would change anything; do not publish an unchanged draft. Preflight is the arbiter of structural readiness: report blockers and stop; with none and an authorized release, publish unless an error you watched happen remains. Then verify with a fresh live conversation. Agents stay private unless the user asks for organization access: members use the published version through the owner's connected accounts and the organization's usage pool, and private visibility revokes access immediately. After a publish, offer the product's Slack setup.
+
+### Runtime state
+
+- `agent_update` — `agentId`, `instructions`, `name` / `agent_set_enabled` — `agentId`, `enabled`
+- `agent_delete` — `agentId`
+
+`agent_set_enabled` takes `enabled: false` to pause or `enabled: true` to resume; `agent_update` edits the draft; `agent_delete` has no confirmation parameter.
+Disable pauses live use without a publish; the owner's Test conversations keep working. Delete is a soft delete that revokes access and asks active sessions to stop; there is no restore.
+
+### Hand over
+
+Call `agent_present` for the finished agent and relay the returned card with its name, purpose, tools and link.
+
+## Verify
+
+The tool list shows the intended tools with exact identities, descriptions and confirmation policies; the knowledge list shows the intended files; the agent read-back matches the instructions; the captured conversation exists on the requested rail without duplicates, its history shows the intended arguments, terminal results and no unresolved request, and stateful behavior is proved by a same-rail record query; a release shows a clean preflight, the new version in the version list, and one fresh live conversation.
+
+## Report
+
+The agent ID and version, its tools with their confirmation policies, what the Test and live conversations proved, connections and access, and what is still unverified or unpublished.

package/skills-mcp/controllerai-agents/references/instructions-and-versioning.md

@@ -0,0 +1,76 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+# Agent instructions and versioning
+
+## Instruction template
+
+```markdown
+You are <role> for <audience>. You own <outcome>.
+
+## Actions
+
+- `<tool_name>`: Use when <specific situation>. Pass <inputs in user terms>. It returns <result>; <how to use it>.
+
+## Judgment
+
+- <decision threshold or boundary>
+- <what requires clarification or approval>
+- <what must never happen>
+
+## Responses
+
+- <tone, length, format>
+
+## When something fails
+
+- Tell the user what failed and what you were trying to do.
+- Retry a read once; do not retry a rejected validation; check the result before repeating an uncertain write.
+- If a connection is broken, name the integration that needs attention.
+```
+
+Delete any sentence that does not change behavior. Do not expose workflow, flow, node, rail, prop, schema-tier or version internals to the runtime user.
+
+## Draft and live model
+
+- Agent edits change only the mutable draft; saving the draft updates Test immediately.
+- Publishing snapshots display name, instructions, tool identities, descriptions and approval policies, and knowledge files into a new immutable version. The runtime model is not part of that snapshot.
+- Publishing moves the live pointer and restamps every existing live conversation to the new version; new and existing shared conversations therefore use the latest published agent version. In-flight answers are interrupted and pending approvals expire.
+- Non-owners never receive draft instructions, tools or knowledge. Test conversations are owner-only.
+- There is no rollback; correct a bad version by editing the draft and publishing forward. `agent versions` is the release history.
+- Test conversations run each workflow tool against its current development head; live conversations follow each workflow's latest live release and cannot pin a version.
+- Workflow and agent publishing are independent. A workflow publish changes every live agent that follows it without another agent publish. Live workflow resolution is cached per runtime session: an in-flight turn or approval episode may finish on the prior release, then the session refreshes. Use a fresh live conversation for post-publish proof and disclose any refresh warning.
+- A direct action's identity, description and confirmation policy are versioned; its connection and grant are live: rebinding can redirect an invocation, and failure, revocation or detachment can block it immediately. Confirmation is strictest-wins: turning it on for a direct action blocks the published action at once until the next publish carries it. Detachment also changes the draft tool list, so publish afterward to remove the tool from the published list.
+- Organization members use the owner's connected external accounts for direct actions, and usage comes from the organization's shared pool.
+- Development and live workflow records are separate; stateful live behavior needs live-store proof.
+
+## File context by mode
+
+- **Live:** knowledge frozen in the latest published agent version plus current live shared or runtime files.
+- **Test:** current draft knowledge plus current live shared or runtime files, overlaid by development/test files at the same sandbox path, where the development/test file wins.
+- Runtime files live outside the immutable snapshot, so a live runtime-file change appears in live conversations without a publish. Conversation attachments belong to one conversation only.
+
+## Updating a published agent
+
+1. Edit the draft.
+2. Read it back and verify it in a Test conversation.
+3. Publish any changed workflow dependency the user authorized.
+4. Run preflight and publish the agent.
+5. Verify with a new live conversation.
+
+Do not republish the agent merely to pick up a followed workflow's new release or a direct-action rebind, failure, revocation or detachment; those effects are already live. Verify and disclose every live-bound change.
+
+## Verification matrix
+
+| Layer | Evidence |
+| --- | --- |
+| Workflow tool | A completed development flow run; an intentional, authorized live flow run is stronger evidence of published behavior than a draft-agent proxy |
+| Direct action | Persisted conversation action events, the returned result, and the intended external effect |
+| Draft routing | A Test conversation that chooses the correct tool with the correct arguments |
+| Published workflow | `workflow status` reporting the intended live release and active state |
+| Published agent | The publish version plus a new live conversation |
+| Stateful live behavior | A live conversation or trigger run that reads and writes the expected live records |
+
+Direct actions do not create workflow execution IDs. Never claim a higher layer from lower-layer evidence alone.
+
+## File-handling agents
+
+An agent, not a workflow, reads a chat-uploaded file and produces the output file; workflows receive typed values extracted from the rows, and a workflow `file` value is hosted-file metadata, not an upload or a parser. For a per-row enrichment: build and test a typed one-item flow (clear match, ambiguous match, missing data, a failed lookup), attach it, instruct the agent to inspect the columns, process every row, keep failures on their original rows, preserve column and row order and append the new columns, then have the exported file checked (quoted commas, a missing company, an ambiguous name) for opening and retaining every input row. The upload and the download happen on the product's file surface, which the builder cannot drive, so that check is the user's; "saved the file" is not proof of an accessible download.