Scope Skills preview flag to toolbox version creation

Stable azure-ai-projects 2.3.x toolboxes.create_version does not auto-inject the Skills preview header, so passing a non-empty skills= would fail. Conditionally send headers={'Foundry-Features': 'Skills=V1Preview'} on all three version-creation paths (normal, search-first, RAI-guarded) only when skills is present, and correct the Section 4l prose that claimed skills CRUD was the only preview-gated flow.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: lindazqli

notebooks/mastering-foundry-toolbox.ipynb

@@ -1305,9 +1305,11 @@
     "reference it in the **separate `skills=` list** with `ToolboxSkillReference(name, version)`. Omit\n",
     "`version` to track the skill's **default** version; pin it to freeze on an immutable version.\n",
     "\n",
-    "> Skills CRUD (`project.beta.skills.*` create / update-default) is the **only** flow that needs a\n",
-    "> preview feature flag, and the `beta.skills` SDK sends it for you. Reading skills as MCP resources\n",
-    "> (section 10b) and regular toolbox/tool calls need **no** preview header.\n",
+    "> Two flows need the **Skills preview flag** (`Foundry-Features: Skills=V1Preview`): skills CRUD\n",
+    "> (`project.beta.skills.*` create / update-default), where the `beta.skills` SDK sends it for you,\n",
+    "> **and** creating a toolbox version that references a skill. Stable `toolboxes.create_version`\n",
+    "> does **not** inject it, so section 4m sets it explicitly whenever `skills` is non-empty. Reading\n",
+    "> skills as MCP resources (section 10b) and regular toolbox/tool calls need **no** preview header.\n",
     "\n",
     "**Key parameters** (`ToolboxSkillReference`):\n",
     "- `name` - **required** `str`; the published skill name.\n",
@@ -1402,11 +1404,15 @@
    ],
    "source": [
     "# create_version(name, *, tools, description=None, metadata=None, skills=None, policies=None)\n",
+    "# Stable toolboxes.create_version does NOT auto-inject the Skills preview flag, so send it\n",
+    "# ourselves whenever this version references a skill (empty kwargs when there are no skills).\n",
+    "skill_kwargs = {\"headers\": {\"Foundry-Features\": \"Skills=V1Preview\"}} if skills else {}\n",
     "version = project.toolboxes.create_version(\n",
     "    name=TOOLBOX_NAME,\n",
     "    description=\"Diverse demo toolbox: search, code, knowledge, and connection-backed tools.\",\n",
     "    tools=tools,\n",
     "    skills=skills or None,\n",
+    "    **skill_kwargs,\n",
     ")\n",
     "created_resources[\"toolbox\"] = TOOLBOX_NAME\n",
     "created_resources[\"versions\"].append(version.version)\n",
@@ -1594,10 +1600,13 @@
     "    tool_configs=tool_configs,\n",
     "))\n",
     "\n",
+    "# Same rule as section 4m: only send the Skills preview flag when this version has skills.\n",
+    "skill_kwargs = {\"headers\": {\"Foundry-Features\": \"Skills=V1Preview\"}} if skills else {}\n",
     "search_version = project.toolboxes.create_version(\n",
     "    name=TOOLBOX_NAME,\n",
     "    tools=search_tools,\n",
     "    skills=skills or None,\n",
+    "    **skill_kwargs,\n",
     ")\n",
     "created_resources[\"versions\"].append(search_version.version)\n",
     "print(f\"✅ Search-first version {search_version.version} - tools/list will now return tool_search + pinned only\")"
@@ -1720,11 +1729,14 @@
     "#     RAI policy and Foundry screens tool inputs/outputs for that version.\n",
     "RAI_POLICY_NAME = os.getenv(\"RAI_POLICY_NAME\")\n",
     "if RAI_POLICY_NAME:\n",
+    "    # Only send the Skills preview flag when this version references a skill (see 4m).\n",
+    "    skill_kwargs = {\"headers\": {\"Foundry-Features\": \"Skills=V1Preview\"}} if skills else {}\n",
     "    guarded = project.toolboxes.create_version(\n",
     "        name=TOOLBOX_NAME,\n",
     "        tools=search_tools,\n",
     "        skills=skills or None,\n",
     "        policies=ToolboxPolicies(rai_config=RaiConfig(rai_policy_name=RAI_POLICY_NAME)),\n",
+    "        **skill_kwargs,\n",
     "    )\n",
     "    created_resources[\"versions\"].append(guarded.version)\n",
     "    project.toolboxes.update(name=TOOLBOX_NAME, default_version=guarded.version)\n",