docs: complete IaC Code Skill documentation

README.md

@@ -96,6 +96,13 @@ By default it opens `http://127.0.0.1:8766` in your browser (loopback only). See
   <img src="website/static/img/screenshots/iac-code-web-en.jpg" alt="IaC Code Web app" width="100%">
 </p>
 
+### Agent Skill
+
+Add IaC Code to a compatible agent to plan cloud architectures, work with ROS or Terraform templates, estimate costs,
+operate stacks, and deploy Alibaba Cloud resources from the agent conversation. Download the
+[latest stable Skill package](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip)
+or compare the distributions in [Official IaC Code Skills](https://aliyun.github.io/iac-code/docs/a2a/skill-overview).
+
 ## Contributing
 
 Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:

readme/README.de.md

@@ -98,6 +98,10 @@ Standardmäßig öffnet sie `http://127.0.0.1:8766` in Ihrem Browser (nur Loopba
   <img src="../website/static/img/screenshots/iac-code-web-en.jpg" alt="IaC Code Web-App" width="100%">
 </p>
 
+### Agent Skill
+
+Fuegen Sie IaC Code einem kompatiblen Agenten hinzu, um im Gespraech Cloud-Architekturen zu planen, ROS- oder Terraform-Vorlagen zu bearbeiten, Kosten zu schaetzen, Stacks zu verwalten und Alibaba-Cloud-Ressourcen bereitzustellen. Laden Sie den [aktuellen stabilen Skill](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) herunter oder vergleichen Sie die Distributionen im [Ueberblick ueber offizielle IaC Code Skills](https://aliyun.github.io/iac-code/de/docs/a2a/skill-overview).
+
 ## Mitwirken
 
 Installieren Sie [uv](https://docs.astral.sh/uv/getting-started/installation/), dann:

readme/README.es.md

@@ -98,6 +98,10 @@ De forma predeterminada, abre `http://127.0.0.1:8766` en tu navegador (solo bucl
   <img src="../website/static/img/screenshots/iac-code-web-en.jpg" alt="Aplicación web de IaC Code" width="100%">
 </p>
 
+### Agent Skill
+
+Añade IaC Code a un agente compatible para diseñar arquitecturas cloud, trabajar con plantillas ROS o Terraform, estimar costes, gestionar stacks y desplegar recursos de Alibaba Cloud desde la conversación. Descarga el [último Skill estable](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) o compara las distribuciones en la [visión general de los Skills oficiales](https://aliyun.github.io/iac-code/es/docs/a2a/skill-overview).
+
 ## Contribuir
 
 Instale [uv](https://docs.astral.sh/uv/getting-started/installation/), luego:

readme/README.fr.md

@@ -98,6 +98,10 @@ Par défaut, elle ouvre `http://127.0.0.1:8766` dans votre navigateur (bouclage
   <img src="../website/static/img/screenshots/iac-code-web-en.jpg" alt="Application web IaC Code" width="100%">
 </p>
 
+### Agent Skill
+
+Ajoutez IaC Code à un agent compatible pour concevoir des architectures cloud, travailler sur des templates ROS ou Terraform, estimer les coûts, gérer des stacks et déployer des ressources Alibaba Cloud depuis la conversation. Téléchargez le [dernier Skill stable](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) ou comparez les distributions dans la [présentation des Skills IaC Code officiels](https://aliyun.github.io/iac-code/fr/docs/a2a/skill-overview).
+
 ## Contribuer
 
 Installez [uv](https://docs.astral.sh/uv/getting-started/installation/), puis :

readme/README.ja.md

@@ -98,6 +98,10 @@ iac-code web
   <img src="../website/static/img/screenshots/iac-code-web-en.jpg" alt="IaC Code Web アプリ" width="100%">
 </p>
 
+### Agent Skill
+
+IaC Code を対応エージェントに追加すると、会話からクラウド構成の設計、ROS/Terraform テンプレート、料金見積もり、スタック操作、Alibaba Cloud リソースのデプロイを行えます。[最新の安定版 Skill](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip)をダウンロードするか、[IaC Code 公式 Skills の概要](https://aliyun.github.io/iac-code/ja/docs/a2a/skill-overview)で配布方法を比較してください。
+
 ## コントリビュート
 
 [uv](https://docs.astral.sh/uv/getting-started/installation/) をインストールしてから：

readme/README.pt.md

@@ -98,6 +98,10 @@ Por padrão, ele abre `http://127.0.0.1:8766` no seu navegador (apenas loopback)
   <img src="../website/static/img/screenshots/iac-code-web-en.jpg" alt="Aplicativo web do IaC Code" width="100%">
 </p>
 
+### Agent Skill
+
+Adicione o IaC Code a um agente compatível para planejar arquiteturas em nuvem, trabalhar com templates ROS ou Terraform, estimar custos, operar stacks e implantar recursos do Alibaba Cloud a partir da conversa. Baixe o [Skill estável mais recente](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) ou compare as distribuições na [visão geral dos Skills oficiais](https://aliyun.github.io/iac-code/pt/docs/a2a/skill-overview).
+
 ## Contribuir
 
 Instale o [uv](https://docs.astral.sh/uv/getting-started/installation/), depois:

readme/README.zh.md

@@ -98,6 +98,10 @@ iac-code web
   <img src="../website/static/img/screenshots/iac-code-web-cn.jpg" alt="IaC Code Web 应用" width="100%">
 </p>
 
+### Agent Skill
+
+将 IaC Code 添加到兼容的 Agent，即可在对话中规划云架构、处理 ROS 或 Terraform 模板、估算费用、操作资源栈并部署阿里云资源。下载[最新稳定版 Skill](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip)，或通过 [IaC Code 官方 Skills 概览](https://aliyun.github.io/iac-code/zh-Hans/docs/a2a/skill-overview)对比不同发行版。
+
 ## 贡献
 
 安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)，然后：

tests/test_website_skill_docs.py

@@ -19,19 +19,54 @@
 def test_website_documents_external_skill_integration_in_all_locales() -> None:
     missing: list[str] = []
     checks = {
+        "a2a/skill-overview.md": [
+            "iac-code-skill.zip",
+            "alibabacloud-iac-code",
+            "alibabacloud-ros-agent",
+            "npx skills add",
+            "https://skills.aliyun.com/",
+            "/api/public/skills/alibabacloud-iac-code/download",
+            "/api/public/skills/alibabacloud-ros-agent/download",
+            "ros:StartChat",
+            "ros:StopChat",
+            "~/.iac-code/",
+            "skill-integration.md",
+            "skill-host-integration.md",
+        ],
         "a2a/skill-integration.md": [
             "ensure-runtime",
             "cache clean",
             "llm_not_configured",
             "cloud_credentials_not_configured",
+            "ask_user_question",
+            "candidate_selection",
+            "deployment_confirmation",
+            "incompatible_host",
+            "Pipeline",
+            "iac-code-skill.zip",
+            "~/.agents/skills/iac-code/",
+            "~/.claude/skills/iac-code/",
+            "/iac-code",
+            ".iac-code-skill-results/",
+            "127.0.0.1",
+            "skill-host-integration.md",
+        ],
+        "a2a/skill-host-integration.md": [
+            "config.json",
+            "preferredLanguage",
             "boundaryReached",
+            "presentationRequired",
             "inputRequired",
+            "turn_completed",
             "ask_user_question",
             "candidate_selection",
+            "deployment_confirmation",
             "allow_once",
+            "continue --job-id",
+            "poll --job-id",
+            "incompatible_host",
             "skill-package-contract.json",
             "skill-runtime/<runtime-tag>/<target>/",
-            ".iac-code-skill-results/",
             "127.0.0.1",
         ],
         "a2a/protocol-reference.md": [
@@ -44,7 +79,9 @@ def test_website_documents_external_skill_integration_in_all_locales() -> None:
             "schemaVersion",
         ],
         "a2a/overview.md": [
+            "skill-overview.md",
             "skill-integration.md",
+            "skill-host-integration.md",
             "preferredLanguage",
             "allow_once",
         ],
@@ -71,7 +108,16 @@ def test_website_documents_external_skill_integration_in_all_locales() -> None:
 
 def test_skill_integration_registered_in_sidebar() -> None:
     sidebars = (WEBSITE_ROOT / "sidebars.ts").read_text(encoding="utf-8")
+    assert "label: 'IaC Code Skill'" in sidebars, "IaC Code Skill category is not registered in sidebars.ts"
+    assert "'a2a/skill-overview'" in sidebars, "a2a/skill-overview is not registered in sidebars.ts"
     assert "'a2a/skill-integration'" in sidebars, "a2a/skill-integration is not registered in sidebars.ts"
+    assert "'a2a/skill-host-integration'" in sidebars, "a2a/skill-host-integration is not registered in sidebars.ts"
+    assert (WEBSITE_ROOT / "docs" / "a2a" / "skill-overview.md").exists(), (
+        "English source document for a2a/skill-overview is missing"
+    )
     assert (WEBSITE_ROOT / "docs" / "a2a" / "skill-integration.md").exists(), (
         "English source document for a2a/skill-integration is missing"
     )
+    assert (WEBSITE_ROOT / "docs" / "a2a" / "skill-host-integration.md").exists(), (
+        "English source document for a2a/skill-host-integration is missing"
+    )

website/docs/a2a/overview.md

@@ -22,7 +22,7 @@ Use A2A when another agent, workflow engine, or service needs to call iac-code a
 - **Workflow automation** — Internal tools can submit IaC generation, review, or conversion tasks over HTTP.
 - **Service discovery** — Clients can fetch the Agent Card and choose capabilities such as IaC generation or template review.
 - **Streaming integrations** — A chatops or dashboard client can show model text, tool activity, usage metadata, and final task state as the turn runs.
-- **External Skill integration** — External agents use the packaged iac-code Skill to drive a local authenticated A2A runtime through a standard-library-only bridge script, embedding iac-code as their Alibaba Cloud infrastructure capability. See [Skill integration](./skill-integration.md).
+- **External Skill integration** — External agents use an official IaC Code Skill to add Alibaba Cloud infrastructure capabilities to their workflows. See [Official IaC Code Skills](./skill-overview.md) to choose a distribution, [Install and Use the IaC Code Skill](./skill-integration.md), or the [Host Integration Reference](./skill-host-integration.md).
 
 ## Interaction Modes Comparison
 

website/docs/a2a/skill-host-integration.md

@@ -0,0 +1,175 @@
+---
+sidebar_position: 3
+title: IaC Code Skill Host Integration Reference
+description: Integrate the packaged IaC Code Skill bridge with a Skill-capable host agent.
+---
+
+# IaC Code Skill Host Integration Reference
+
+This document is for developers of agents and Skill distribution systems. It defines how a host invokes the packaged
+bridge, presents IaC Code results, handles user interaction, and resumes an existing task. End users should read
+[Install and Use the IaC Code Skill](./skill-integration.md).
+
+## Integration Model
+
+The Skill package contains `SKILL.md` and the standard-library-only `scripts/iac_code.py` bridge. The host invokes the
+bridge; the bridge installs and starts the pinned, verified Runtime and communicates with it over an authenticated
+local A2A connection.
+
+The host must:
+
+- use CPython 3.8–3.14 to run the bridge;
+- treat stdout as the stable JSON result and stderr as diagnostics and bounded progress;
+- preserve the current `jobId`, `contextId`, cursor, and input correlation fields;
+- show every user-facing boundary before continuing; and
+- fail closed on bridge errors instead of bypassing the bridge with direct cloud calls or another Runtime.
+
+## Optional Distribution Configuration
+
+A distributor can place `config.json` beside `SKILL.md`:
+
+```json
+{
+  "channel": "codex",
+  "pipelineName": "selling_solution_first",
+  "permissionWaitPolicy": {
+    "residentTimeoutSeconds": null,
+    "subPipelineTimeoutSeconds": null,
+    "timeoutGraceSeconds": 30
+  }
+}
+```
+
+- `channel` is the channel identifier; the bridge adds the `skill/` prefix.
+- `pipelineName` applies only after Pipeline mode is selected. The default is `selling_solution_first`; `selling` is
+  available for distributors that explicitly require the legacy workflow.
+- `permissionWaitPolicy` controls waits in the temporary A2A server owned by the Skill. `null` means unlimited for the
+  resident or Sub Pipeline timeout.
+
+The bridge rejects unknown fields and invalid values. This file is installation policy: do not derive it from a user
+request, expose it in task output, or modify it during a task.
+
+## Start a Job
+
+Write the complete request to a UTF-8 file in the workspace, resolve the workspace to an absolute path, and run:
+
+```text
+python3 scripts/iac_code.py start --mode normal --cwd <workspace> --prompt-file <prompt-file> --language <language> --follow
+```
+
+Use `normal` by default. Select `pipeline` only for a requested solution-comparison flow that needs candidate
+architectures, cost comparison, confirmation, and deployment. Set the language to `en`, `zh`, `es`, `fr`, `de`, `ja`,
+`pt`, or `auto`. Keep the returned `preferredLanguage` for every later turn.
+
+`start` performs a non-secret readiness check. `llm_not_configured` stops before job creation. Pipeline mode also
+requires cloud credentials and otherwise returns `cloud_credentials_not_configured`. Normal mode may proceed with a
+warning when the task does not need cloud APIs.
+
+## Follow Progress and Completion
+
+`--follow` stops at the next presentation or interaction boundary, `turn_completed`, or terminal Pipeline state. When
+a result has `boundaryReached: true`, show all strings in `userUpdates`, then immediately follow the same job using the
+returned cursor:
+
+```text
+python3 scripts/iac_code.py follow --job-id <job-id> --cursor <cursor> --wait-seconds 60
+```
+
+Do not treat `boundaryReached` as completion. `presentationRequired` means that the current update must be made visible
+before another bridge call. A normal-mode answer is authoritative only when `state` is `turn_completed`; use
+`finalText` and `artifacts`. For a terminal Pipeline state, use `pipelineResult` and `artifacts` and report cleanup
+failures instead of claiming success.
+
+If `follow` cannot be used during diagnosis or recovery, poll the same job:
+
+```text
+python3 scripts/iac_code.py poll --job-id <job-id> --cursor <cursor> --wait-seconds 5
+```
+
+When a result says `state: input-required` but does not contain `inputRequired`, report its latest text or error and
+leave the job unchanged. Do not submit a duplicate response or create a replacement job.
+
+## Handle User Input
+
+Treat every `inputRequired` object as a hard interaction boundary. Present it through the host's native question or
+approval UI, stop, and wait for an explicit answer. Never infer an answer from the original request or choose a
+default. Preserve `kind`, `inputId`, `requestTaskId`, `contextId`, and `toolUseId` when present.
+
+| `kind` | What the host must present | Response |
+|---|---|---|
+| `permission` | Purpose, effect, target, read-only status, deployment summary, safe summary, and returned actions | `allow_once` or `deny` |
+| `ask_user_question` | The prompt, options, and free-text prompt when allowed | Selected option or allowed free text |
+| `candidate_selection` | Every summary, Mermaid architecture diagram, monthly total, and cost items | Candidate ID or index |
+| `deployment_confirmation` | Solution, template URL, quote or quote failure, effective parameters, overrides, Preview status, and returned actions | `confirm`, `adjust`, `reselect`, or `cancel` |
+
+Write the correlated answer to a new UTF-8 JSON file and resume the same job:
+
+```text
+python3 scripts/iac_code.py respond --job-id <job-id> --input-file <answer-file> --follow
+```
+
+Example envelopes:
+
+```json
+{"kind":"permission","requestTaskId":"<requestTaskId>","contextId":"<contextId>","inputId":"<inputId>","toolUseId":"<toolUseId>","decision":"allow_once"}
+```
+
+```json
+{"kind":"ask_user_question","requestTaskId":"<requestTaskId>","contextId":"<contextId>","inputId":"<inputId>","answer":"<answer>"}
+```
+
+```json
+{"kind":"candidate_selection","requestTaskId":"<requestTaskId>","contextId":"<contextId>","inputId":"<inputId>","answer":"<candidate ID or index>"}
+```
+
+```json
+{"kind":"deployment_confirmation","requestTaskId":"<requestTaskId>","contextId":"<contextId>","inputId":"<inputId>","action":"<confirm|adjust|reselect|cancel>","parameterOverrides":{"<parameter>":"<value>"}}
+```
+
+Omit `parameterOverrides` when the user did not request an adjustment. A deployment request is not approval for a
+later `deployment_confirmation`, and an outer host approval must not override a denial from IaC Code.
+
+## Continue a Conversation
+
+After a normal turn completes, or after a completed Pipeline hands the conversation to normal mode, write the next
+message to a new prompt file and continue the existing job:
+
+```text
+python3 scripts/iac_code.py continue --job-id <job-id> --prompt-file <prompt-file> --follow
+```
+
+Keep the same `jobId` and `contextId`; a new `taskId` for each normal turn is expected. Do not use `start` merely
+because the previous turn completed. Keeping the job identity also allows the bridge to recover permission waits and
+resume after a host interruption.
+
+To cancel the whole operation, run:
+
+```text
+python3 scripts/iac_code.py cancel --job-id <job-id>
+```
+
+Cancellation is different from denying one permission request.
+
+## Errors and Runtime Lifecycle
+
+Treat a pre-job bridge error as authoritative. In particular, `incompatible_host` includes available host and Runtime
+compatibility facts; present them and stop. Do not fall back to pip installation, another Runtime artifact, or direct
+cloud calls.
+
+The downloaded Runtime is cached under
+`<IAC_CODE_CONFIG_DIR or ~/.iac-code>/skill-runtime/<runtime-tag>/<target>/`. The package layout and integrity metadata
+are defined by `skill-runtime/skill-package-contract.json` and the release manifest. The bridge verifies the package
+before use. Runtime cache cleanup must be a separate, explicitly requested operation; current and active packages are
+protected.
+
+The Runtime binds to a random `127.0.0.1` port and generates a process-specific Bearer token. Do not expose the token,
+local state, credentials, environment values, or raw tool inputs and results. Bounded result projections and display
+fields are the supported host interface.
+
+## Related Documentation
+
+- [Official IaC Code Skills](./skill-overview.md)
+- [Install and Use the IaC Code Skill](./skill-integration.md)
+- [A2A Protocol Overview](./overview.md)
+- [A2A Protocol Reference](./protocol-reference.md)
+- [Runtime Configuration](../configuration/runtime-configuration.md)