From 1be3a700459974eadf125cd29c04109bb95810e0 Mon Sep 17 00:00:00 2001
From: Xiaoping Liao <106010272+kyletser@users.noreply.github.com>
Date: Sun, 30 Aug 2026 18:16:11 +0800
Subject: [PATCH] docs(sdk): document launch-time skill overlays

---
 sdk/arch/agent-server.mdx | 41 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/sdk/arch/agent-server.mdx b/sdk/arch/agent-server.mdx
index 12259896f..5d3745897 100644
--- a/sdk/arch/agent-server.mdx
+++ b/sdk/arch/agent-server.mdx
@@ -123,6 +123,47 @@ conversation.close()
 
 If the server was started without `OH_SESSION_API_KEYS_0`, remove the `api_key=...` argument.
 
+## Add Deployment Context at Launch
+
+Services that start conversations through `POST /api/conversations` can add
+deployment-owned context without changing the stored Agent Profile. Set
+`agent_launch_additions` on the start request. The server applies these additions
+after resolving the requested agent.
+
+Use `skills_append` to attach complete `Skill` objects to the launched agent:
+
+```json
+{
+  "agent_profile_id": "00000000-0000-0000-0000-000000000000",
+  "workspace": {
+    "working_dir": "workspace/project"
+  },
+  "agent_launch_additions": {
+    "skills_append": [
+      {
+        "name": "deployment-automation",
+        "description": "Instructions for managing deployment automations.",
+        "content": "# Deployment Automations\nFollow the deployment procedure.",
+        "trigger": {
+          "type": "keyword",
+          "keywords": ["automation", "schedule"]
+        },
+        "disable_model_invocation": true
+      }
+    ]
+  }
+}
+```
+
+Existing agent skills remain authoritative when a name conflicts. Skills listed
+in the resolved agent context's `disabled_skills` are not added. The additions
+become part of the conversation's materialized agent and remain available after
+an Agent Server restart, but the stored Agent Profile is unchanged.
+
+Set `disable_model_invocation` to `true` for trigger-only skills that should not
+be advertised for direct model invocation. Their content is still injected when
+their trigger matches a user message.
+
 ## Expose It Safely
 
 If another service runs on the same machine, keep the server bound to `127.0.0.1` and let that service connect locally.