@ivannxbt/ai-config 0.1.0

package/.agents/skills/microsoft-foundry/foundry-agent/trace/references/kql-templates.md

@@ -0,0 +1,173 @@
+# KQL Templates — GenAI Trace Query Reference
+
+Ready-to-use KQL templates for querying GenAI OpenTelemetry traces in Application Insights.
+
+## App Insights Table Mapping
+
+| App Insights Table | GenAI Data |
+|-------------------|------------|
+| `dependencies` | GenAI spans: LLM inference (`chat`), tool execution (`execute_tool`), agent invocation (`invoke_agent`) |
+| `requests` | Incoming HTTP requests to the agent endpoint |
+| `customEvents` | GenAI evaluation results (`gen_ai.evaluation.result`) — scores, labels, explanations |
+| `traces` | Log events, including GenAI events (input/output messages) |
+| `exceptions` | Error details with stack traces |
+
+## Key GenAI OTel Attributes
+
+Stored in `customDimensions` on `dependencies` spans:
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `gen_ai.operation.name` | Operation type | `chat`, `invoke_agent`, `execute_tool`, `create_agent` |
+| `gen_ai.conversation.id` | Conversation/session ID | `conv_5j66UpCpwteGg4YSxUnt7lPY` |
+| `gen_ai.response.id` | Response ID | `chatcmpl-123` |
+| `gen_ai.agent.name` | Agent name | `my-support-agent` |
+| `gen_ai.agent.id` | Agent unique ID | `asst_abc123` |
+| `gen_ai.request.model` | Requested model | `gpt-4o` |
+| `gen_ai.response.model` | Actual model used | `gpt-4o-2024-05-13` |
+| `gen_ai.usage.input_tokens` | Input token count | `450` |
+| `gen_ai.usage.output_tokens` | Output token count | `120` |
+| `gen_ai.response.finish_reasons` | Stop reasons | `["stop"]`, `["tool_calls"]` |
+| `error.type` | Error classification | `timeout`, `rate_limited`, `content_filter` |
+| `gen_ai.provider.name` | Provider | `azure.ai.openai`, `openai` |
+
+Stored in `customDimensions` on `customEvents` (name == `gen_ai.evaluation.result`):
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `gen_ai.evaluation.name` | Evaluator name | `Relevance`, `IntentResolution` |
+| `gen_ai.evaluation.score.value` | Numeric score | `4.0` |
+| `gen_ai.evaluation.score.label` | Human-readable label | `pass`, `fail`, `relevant` |
+| `gen_ai.evaluation.explanation` | Free-form explanation | `"Response lacks detail..."` |
+| `gen_ai.response.id` | Correlates to the evaluated span | `chatcmpl-123` |
+| `gen_ai.conversation.id` | Correlates to conversation | `conv_5j66...` |
+
+> **Correlation:** Eval results do NOT link via id-parentId. Use `gen_ai.conversation.id` and/or `gen_ai.response.id` to join with `dependencies` spans.
+
+## Span Correlation
+
+| Field | Purpose |
+|-------|---------|
+| `operation_Id` | Trace ID — groups all spans in one request |
+| `id` | Span ID — unique identifier for this span |
+| `operation_ParentId` | Parent span ID — use with `id` to build span trees |
+
+## Hosted Agent Attributes
+
+Stored in `customDimensions` on `traces` (log events), NOT on `dependencies` spans:
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `azure.ai.agentserver.agent_name` | Hosted agent name | `hosted-agent-022-001` |
+| `azure.ai.agentserver.agent_id` | Internal agent ID | `code-asst-xmwokux85uqc7fodxejaxa` |
+| `azure.ai.agentserver.conversation_id` | Conversation ID | `conv_d7ab624de92d...` |
+| `azure.ai.agentserver.response_id` | Response ID (caresp format) | `caresp_d7ab624de92d...` |
+
+> **Important:** These attributes are on `traces` table entries, not `dependencies` spans. To correlate with GenAI spans, join on `operation_Id`.
+
+## Response ID Formats
+
+| Agent Type | Prefix | Example |
+|------------|--------|---------|
+| Hosted agent (AgentServer) | `caresp_` | `caresp_d7ab624de92da637008Rhr4U4E1y9FSE...` |
+| Prompt agent (Foundry Responses API) | `resp_` | `resp_4e2f8b016b5a0dad00697bd3c4c1b881...` |
+| Azure OpenAI chat completions | `chatcmpl-` | `chatcmpl-abc123def456` |
+
+When searching by response ID, use the appropriate prefix to narrow results. The `gen_ai.response.id` attribute appears on `dependencies` spans (for `chat` operations) and in `customEvents` (for evaluation results).
+
+## Common Query Templates
+
+### Overview — Conversations in last 24h
+```kql
+dependencies
+| where timestamp > ago(24h)
+| where isnotempty(customDimensions["gen_ai.operation.name"])
+| summarize
+    spanCount = count(),
+    errorCount = countif(success == false),
+    avgDuration = avg(duration),
+    totalInputTokens = sum(toint(customDimensions["gen_ai.usage.input_tokens"])),
+    totalOutputTokens = sum(toint(customDimensions["gen_ai.usage.output_tokens"]))
+  by bin(timestamp, 1h)
+| order by timestamp desc
+```
+
+### Error Rate by Operation
+```kql
+dependencies
+| where timestamp > ago(24h)
+| where isnotempty(customDimensions["gen_ai.operation.name"])
+| summarize
+    total = count(),
+    errors = countif(success == false),
+    errorRate = round(100.0 * countif(success == false) / count(), 1)
+  by operation = tostring(customDimensions["gen_ai.operation.name"])
+| order by errorRate desc
+```
+
+### Token Usage by Model
+```kql
+dependencies
+| where timestamp > ago(24h)
+| where customDimensions["gen_ai.operation.name"] == "chat"
+| summarize
+    calls = count(),
+    totalInput = sum(toint(customDimensions["gen_ai.usage.input_tokens"])),
+    totalOutput = sum(toint(customDimensions["gen_ai.usage.output_tokens"])),
+    avgInput = avg(todouble(customDimensions["gen_ai.usage.input_tokens"])),
+    avgOutput = avg(todouble(customDimensions["gen_ai.usage.output_tokens"]))
+  by model = tostring(customDimensions["gen_ai.request.model"])
+| order by totalInput desc
+```
+
+### Tool Call Details
+```kql
+dependencies
+| where operation_Id == "<operation_id>"
+| where customDimensions["gen_ai.operation.name"] == "execute_tool"
+| project timestamp, duration, success,
+    toolName = tostring(customDimensions["gen_ai.tool.name"]),
+    toolType = tostring(customDimensions["gen_ai.tool.type"]),
+    toolCallId = tostring(customDimensions["gen_ai.tool.call.id"]),
+    toolArgs = tostring(customDimensions["gen_ai.tool.call.arguments"]),
+    toolResult = tostring(customDimensions["gen_ai.tool.call.result"])
+| order by timestamp asc
+```
+
+Key tool attributes:
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `gen_ai.tool.name` | Tool function name | `remote_functions.bing_grounding`, `python` |
+| `gen_ai.tool.type` | Tool type | `extension`, `function` |
+| `gen_ai.tool.call.id` | Unique call ID | `call_db64aa6a004a...` |
+| `gen_ai.tool.call.arguments` | JSON arguments passed | `{"query": "latest AI news"}` |
+| `gen_ai.tool.call.result` | Tool output (may be truncated) | `<<ImageDisplayed>>` |
+
+### Evaluation Results by Conversation
+```kql
+customEvents
+| where timestamp > ago(24h)
+| where name == "gen_ai.evaluation.result"
+| extend
+    evalName = tostring(customDimensions["gen_ai.evaluation.name"]),
+    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
+    label = tostring(customDimensions["gen_ai.evaluation.score.label"]),
+    conversationId = tostring(customDimensions["gen_ai.conversation.id"])
+| summarize
+    evalCount = count(),
+    avgScore = avg(score),
+    failCount = countif(label == "fail" or label == "not_relevant" or label == "incorrect"),
+    evaluators = make_set(evalName)
+  by conversationId
+| order by failCount desc
+```
+
+> For detailed eval queries by response ID or conversation ID, see [Eval Correlation](eval-correlation.md).
+
+## OTel Reference Links
+
+- [GenAI Spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/)
+- [GenAI Agent Spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/)
+- [GenAI Events](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-events/)
+- [GenAI Metrics](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-metrics/)

package/.agents/skills/microsoft-foundry/foundry-agent/trace/references/search-traces.md

@@ -0,0 +1,141 @@
+# Search Traces — Conversation-Level Search
+
+Search agent traces at the conversation level. Returns summaries grouped by conversation or operation, not individual spans.
+
+## Prerequisites
+
+- App Insights resource resolved (see [trace.md](../trace.md) Before Starting)
+- Time range confirmed with user (default: last 24 hours)
+
+## Search by Conversation ID
+
+```kql
+dependencies
+| where timestamp > ago(24h)
+| where customDimensions["gen_ai.conversation.id"] == "<conversation_id>"
+| project timestamp, name, duration, resultCode, success,
+    operation = tostring(customDimensions["gen_ai.operation.name"]),
+    model = tostring(customDimensions["gen_ai.request.model"]),
+    inputTokens = toint(customDimensions["gen_ai.usage.input_tokens"]),
+    outputTokens = toint(customDimensions["gen_ai.usage.output_tokens"]),
+    operation_Id, id, operation_ParentId
+| order by timestamp asc
+```
+
+## Search by Response ID
+
+Auto-detect the response ID format to determine agent type:
+- `caresp_...` → Hosted agent (AgentServer)
+- `resp_...` → Prompt agent (Foundry Responses API)
+- `chatcmpl-...` → Azure OpenAI chat completions
+
+```kql
+dependencies
+| where timestamp > ago(24h)
+| where customDimensions["gen_ai.response.id"] == "<response_id>"
+| project timestamp, name, duration, resultCode, success,
+    operation = tostring(customDimensions["gen_ai.operation.name"]),
+    model = tostring(customDimensions["gen_ai.request.model"]),
+    inputTokens = toint(customDimensions["gen_ai.usage.input_tokens"]),
+    outputTokens = toint(customDimensions["gen_ai.usage.output_tokens"]),
+    operation_Id, id, operation_ParentId
+```
+
+Then drill into the full conversation:
+
+> ⚠️ **STOP — read [Conversation Detail](conversation-detail.md) before writing your own drill-down query.** It contains the correct span tree reconstruction logic, event/exception queries, and eval correlation steps.
+
+Quick drill-down using the `operation_Id` from above:
+
+```kql
+dependencies
+| where operation_Id == "<operation_id_from_above>"
+| project timestamp, name, duration, resultCode, success,
+    spanId = id, parentSpanId = operation_ParentId,
+    operation = tostring(customDimensions["gen_ai.operation.name"]),
+    model = tostring(customDimensions["gen_ai.request.model"]),
+    inputTokens = toint(customDimensions["gen_ai.usage.input_tokens"]),
+    outputTokens = toint(customDimensions["gen_ai.usage.output_tokens"]),
+    responseId = tostring(customDimensions["gen_ai.response.id"]),
+    errorType = tostring(customDimensions["error.type"]),
+    toolName = tostring(customDimensions["gen_ai.tool.name"])
+| order by timestamp asc
+```
+
+Also check for eval results: see [Eval Correlation](eval-correlation.md).
+
+## Search by Agent Name
+
+> **Note:** For hosted agents, `gen_ai.agent.name` in `dependencies` refers to *sub-agents* (e.g., `BingSearchAgent`), not the top-level hosted agent. See "Search by Hosted Agent Name" below.
+
+```kql
+dependencies
+| where timestamp > ago(24h)
+| where customDimensions["gen_ai.agent.name"] == "<agent_name>"
+    or customDimensions["gen_ai.agent.id"] == "<agent_name>"
+| summarize
+    startTime = min(timestamp),
+    endTime = max(timestamp),
+    totalDuration = max(timestamp) - min(timestamp),
+    spanCount = count(),
+    errorCount = countif(success == false),
+    totalInputTokens = sum(toint(customDimensions["gen_ai.usage.input_tokens"])),
+    totalOutputTokens = sum(toint(customDimensions["gen_ai.usage.output_tokens"]))
+  by conversationId = tostring(customDimensions["gen_ai.conversation.id"]),
+     operation_Id
+| order by startTime desc
+| take 50
+```
+
+## Search by Hosted Agent Name
+
+For hosted agents, the top-level agent name is recorded in the `traces` table under `azure.ai.agentserver.agent_name`, not in `dependencies`.
+
+```kql
+let ops = traces
+| where timestamp > ago(24h)
+| where customDimensions["azure.ai.agentserver.agent_name"] == "<agent_name>"
+| distinct operation_Id;
+dependencies
+| where timestamp > ago(24h)
+| where operation_Id in (ops)
+| where isnotempty(customDimensions["gen_ai.operation.name"])
+| summarize
+    startTime = min(timestamp),
+    endTime = max(timestamp),
+    spanCount = count(),
+    errorCount = countif(success == false),
+    totalInputTokens = sum(toint(customDimensions["gen_ai.usage.input_tokens"])),
+    totalOutputTokens = sum(toint(customDimensions["gen_ai.usage.output_tokens"]))
+  by operation_Id
+| order by startTime desc
+| take 50
+```
+
+## Conversation Summary Table
+
+Present results in this format:
+
+| Conversation ID | Start Time | Duration | Spans | Errors | Input Tokens | Output Tokens |
+|----------------|------------|----------|-------|--------|-------------|---------------|
+| conv_abc123 | 2025-01-15 10:30 | 4.2s | 12 | 0 | 850 | 320 |
+| conv_def456 | 2025-01-15 10:25 | 8.7s | 18 | 2 | 1200 | 450 |
+
+Highlight rows with errors in the summary. Offer to drill into any conversation via [Conversation Detail](conversation-detail.md).
+
+## Free-Text Search
+
+When the user provides a general search term (e.g., agent name, error message):
+
+```kql
+union dependencies, requests, exceptions, traces
+| where timestamp > ago(24h)
+| where * contains "<search_term>"
+| summarize count() by operation_Id
+| order by count_ desc
+| take 20
+```
+
+## After Successful Query
+
+> 📝 **Reminder:** If this is the first trace query in this session, ensure App Insights connection info was persisted to `.env` (see [trace.md — Before Starting](../trace.md#before-starting--resolve-app-insights-connection)).

package/.agents/skills/microsoft-foundry/foundry-agent/trace/trace.md

@@ -0,0 +1,57 @@
+# Foundry Agent Trace Analysis
+
+Analyze production traces for Foundry agents using Application Insights and GenAI OpenTelemetry semantic conventions. This skill provides **structured KQL-powered workflows** for searching conversations, diagnosing failures, and identifying latency bottlenecks. Use this skill instead of writing ad-hoc KQL queries against App Insights manually.
+
+## When to Use This Skill
+
+USE FOR: analyze agent traces, search agent conversations, find failing traces, slow traces, latency analysis, trace search, conversation history, agent errors in production, debug agent responses, App Insights traces, GenAI telemetry, trace correlation, span tree, production trace analysis, evaluation results, evaluation scores, eval run results, find by response ID, get agent trace by conversation ID, agent evaluation scores from App Insights.
+
+> **USE THIS SKILL INSTEAD OF** `azure-monitor` or `azure-applicationinsights` when querying Foundry agent traces, evaluations, or GenAI telemetry. This skill has correct GenAI OTel attribute mappings and tested KQL templates that those general tools lack.
+
+> ⚠️ **DO NOT manually write KQL queries** for GenAI trace analysis **without reading this skill first.** This skill provides tested query templates with correct GenAI OTel attribute mappings, proper span correlation logic, and conversation-level aggregation patterns.
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| Data source | Application Insights (App Insights) |
+| Query language | KQL (Kusto Query Language) |
+| Related skills | `azure-kusto` (KQL execution), `troubleshoot` (container logs) |
+| OTel conventions | [GenAI Spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/), [Agent Spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/) |
+
+## Entry Points
+
+| User Intent | Start At |
+|-------------|----------|
+| "Search agent conversations" / "Find traces" | [Search Traces](references/search-traces.md) |
+| "Tell me about response ID X" / "Look up response ID" | [Search Traces — Search by Response ID](references/search-traces.md#search-by-response-id) |
+| "Why is my agent failing?" / "Find errors" | [Analyze Failures](references/analyze-failures.md) |
+| "My agent is slow" / "Latency analysis" | [Analyze Latency](references/analyze-latency.md) |
+| "Show me this conversation" / "Trace detail" | [Conversation Detail](references/conversation-detail.md) |
+| "Find eval results for response ID" / "eval scores from traces" | [Eval Correlation](references/eval-correlation.md) |
+| "What KQL do I need?" | [KQL Templates](references/kql-templates.md) |
+
+## Before Starting — Resolve App Insights Connection
+
+1. Check `.env` (or the same config file hosting other project variables) for `APPLICATIONINSIGHTS_CONNECTION_STRING` or `AZURE_APPINSIGHTS_RESOURCE_ID`
+2. If not found, use `project_connection_list` (foundry-mcp tool) to discover App Insights linked to the Foundry project — this is the most reliable way to find the correct App Insights resource. Filter results for Application Insights connection type.
+3. **IMMEDIATELY write back to `.env`** — as soon as `project_connection_list` returns App Insights info, write it to `.env` (or the same config file where `AZURE_AI_PROJECT_ENDPOINT` etc. live) BEFORE running any queries. Do not defer this step. This ensures future sessions skip discovery entirely.
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `APPLICATIONINSIGHTS_CONNECTION_STRING` | App Insights connection string | `InstrumentationKey=...;IngestionEndpoint=...` |
+| `AZURE_APPINSIGHTS_RESOURCE_ID` | ARM resource ID | `/subscriptions/.../Microsoft.Insights/components/...` |
+
+If a `.env` file already exists, read it first and merge — do not overwrite existing values without confirmation.
+
+4. Confirm the App Insights resource with the user before querying
+5. Delegate KQL execution to the `azure-kusto` skill
+
+## Behavioral Rules
+
+1. **ALWAYS display the KQL query.** Before executing ANY KQL query, display it in a code block. Never run a query silently. This is a hard requirement, not a suggestion. Showing queries builds trust and helps users learn KQL patterns.
+2. **Start broad, then narrow.** Begin with conversation-level summaries, then drill into specific conversations or spans on user request.
+3. **Use time ranges.** Always scope queries with a time range (default: last 24 hours). Ask user for the range if not specified.
+4. **Explain GenAI attributes.** When displaying results, translate OTel attribute names to human-readable labels (e.g., `gen_ai.operation.name` → "Operation").
+5. **Link to conversation detail.** When showing search or failure results, offer to drill into any specific conversation.
+6. **Scope to the target agent.** An App Insights resource may contain traces from multiple agents. Always filter queries by the specific agent name. When showing overview summaries, group results by `gen_ai.agent.name` or `azure.ai.agentserver.agent_name` and warn the user if multiple agents are present.

package/.agents/skills/microsoft-foundry/foundry-agent/troubleshoot/troubleshoot.md

@@ -0,0 +1,93 @@
+# Foundry Agent Troubleshoot
+
+Troubleshoot and debug Foundry agents by collecting container logs, discovering observability connections, and querying Application Insights telemetry.
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| Agent types | Prompt (LLM-based), Hosted (container-based) |
+| MCP servers | `foundry-mcp` |
+| Key MCP tools | `agent_get`, `agent_container_status_get` |
+| Related skills | `azure-kusto` (for KQL telemetry queries) |
+| CLI references | `az cognitiveservices agent logs`, `az cognitiveservices account connection` |
+
+## When to Use This Skill
+
+- Agent is not responding or returning errors
+- Hosted agent container is failing to start
+- Need to view container logs for a hosted agent
+- Diagnose latency or timeout issues
+- Query Application Insights for agent traces and exceptions
+- Investigate agent runtime failures
+
+## MCP Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `agent_get` | Get agent details to determine type (prompt/hosted) | `projectEndpoint` (required), `agentName` (optional) |
+| `agent_container_status_get` | Check hosted agent container status | `projectEndpoint`, `agentName` (required); `agentVersion` |
+
+## Workflow
+
+### Step 1: Collect Agent Information
+
+Use the project endpoint and agent name from the project context (see Common: Project Context Resolution). Ask the user only for values not already resolved:
+- **Project endpoint** — AI Foundry project endpoint URL
+- **Agent name** — Name of the agent to troubleshoot
+
+### Step 2: Determine Agent Type
+
+Use `agent_get` with `projectEndpoint` and `agentName` to retrieve the agent definition. Check the `kind` field:
+- `"hosted"` → Proceed to Step 3 (Container Logs)
+- `"prompt"` → Skip to Step 4 (Discover Observability Connections)
+
+### Step 3: Retrieve Container Logs (Hosted Agents Only)
+
+First check the container status using `agent_container_status_get`. Report the current status to the user.
+
+Retrieve container logs using the Azure CLI command documented at:
+[az cognitiveservices agent logs show](https://learn.microsoft.com/en-us/cli/azure/cognitiveservices/agent/logs?view=azure-cli-latest#az-cognitiveservices-agent-logs-show)
+
+Refer to the documentation above for the exact command syntax and parameters. Present the logs to the user and highlight any errors or warnings found.
+
+### Step 4: Discover Observability Connections
+
+List the project connections to find Application Insights or Azure Monitor resources using the Azure CLI command documented at:
+[az cognitiveservices account connection](https://learn.microsoft.com/en-us/cli/azure/cognitiveservices/account/connection?view=azure-cli-latest)
+
+Refer to the documentation above for the exact command syntax and parameters. Look for connections of type `ApplicationInsights` or `AzureMonitor` in the output.
+
+If no observability connection is found, inform the user and suggest setting up Application Insights for the project. Ask if they want to proceed without telemetry data.
+
+### Step 5: Query Application Insights Telemetry
+
+Delegate telemetry querying to the `azure-kusto` skill. Provide it the Application Insights resource details discovered in Step 4 and the user's reported issue. The `azure-kusto` skill handles KQL query construction, execution via MCP tools, and result formatting.
+
+Use `* contains "<response_id>"` or `* contains "<agent_name>"` filters to narrow down results to the specific agent instance.
+
+### Step 6: Summarize Findings
+
+Present a summary to the user including:
+- **Agent type and status** — hosted/prompt, container status (if hosted)
+- **Container log errors** — key errors from logs (hosted only)
+- **Telemetry insights** — exceptions, failed requests, latency trends
+- **Recommended actions** — specific steps to resolve identified issues
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Agent not found | Invalid agent name or project endpoint | Use `agent_get` to list available agents and verify name |
+| Container logs unavailable | Agent is a prompt agent or container never started | Prompt agents don't have container logs — skip to telemetry |
+| No observability connection | Application Insights not configured for the project | Suggest configuring Application Insights for the Foundry project |
+| Kusto query failed | Invalid cluster/database or insufficient permissions | Verify Application Insights resource details and reader permissions |
+| No telemetry data | Agent not instrumented or too recent | Check if Application Insights SDK is configured; data may take a few minutes to appear |
+
+## Additional Resources
+
+- [Foundry Hosted Agents](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry)
+- [Agent Logs CLI Reference](https://learn.microsoft.com/en-us/cli/azure/cognitiveservices/agent/logs?view=azure-cli-latest)
+- [Account Connection CLI Reference](https://learn.microsoft.com/en-us/cli/azure/cognitiveservices/account/connection?view=azure-cli-latest)
+- [KQL Quick Reference](https://learn.microsoft.com/azure/data-explorer/kusto/query/kql-quick-reference)
+- [Foundry Samples](https://github.com/azure-ai-foundry/foundry-samples)

package/.agents/skills/microsoft-foundry/models/deploy-model/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: deploy-model
+description: "Unified Azure OpenAI model deployment skill with intelligent intent-based routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI policy), and capacity discovery across regions and projects. USE FOR: deploy model, deploy gpt, create deployment, model deployment, deploy openai model, set up model, provision model, find capacity, check model availability, where can I deploy, best region for model, capacity analysis. DO NOT USE FOR: listing existing deployments (use foundry_models_deployments_list MCP tool), deleting deployments, agent creation (use agent/create), project creation (use project/create)."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.0.0"
+---
+
+# Deploy Model
+
+Unified entry point for all Azure OpenAI model deployment workflows. Analyzes user intent and routes to the appropriate deployment mode.
+
+## Quick Reference
+
+| Mode | When to Use | Sub-Skill |
+|------|-------------|-----------|
+| **Preset** | Quick deployment, no customization needed | [preset/SKILL.md](preset/SKILL.md) |
+| **Customize** | Full control: version, SKU, capacity, RAI policy | [customize/SKILL.md](customize/SKILL.md) |
+| **Capacity Discovery** | Find where you can deploy with specific capacity | [capacity/SKILL.md](capacity/SKILL.md) |
+
+## Intent Detection
+
+Analyze the user's prompt and route to the correct mode:
+
+```
+User Prompt
+    │
+    ├─ Simple deployment (no modifiers)
+    │  "deploy gpt-4o", "set up a model"
+    │  └─> PRESET mode
+    │
+    ├─ Customization keywords present
+    │  "custom settings", "choose version", "select SKU",
+    │  "set capacity to X", "configure content filter",
+    │  "PTU deployment", "with specific quota"
+    │  └─> CUSTOMIZE mode
+    │
+    ├─ Capacity/availability query
+    │  "find where I can deploy", "check capacity",
+    │  "which region has X capacity", "best region for 10K TPM",
+    │  "where is this model available"
+    │  └─> CAPACITY DISCOVERY mode
+    │
+    └─ Ambiguous (has capacity target + deploy intent)
+       "deploy gpt-4o with 10K capacity to best region"
+       └─> CAPACITY DISCOVERY first → then PRESET or CUSTOMIZE
+```
+
+### Routing Rules
+
+| Signal in Prompt | Route To | Reason |
+|------------------|----------|--------|
+| Just model name, no options | **Preset** | User wants quick deployment |
+| "custom", "configure", "choose", "select" | **Customize** | User wants control |
+| "find", "check", "where", "which region", "available" | **Capacity** | User wants discovery |
+| Specific capacity number + "best region" | **Capacity → Preset** | Discover then deploy quickly |
+| Specific capacity number + "custom" keywords | **Capacity → Customize** | Discover then deploy with options |
+| "PTU", "provisioned throughput" | **Customize** | PTU requires SKU selection |
+| "optimal region", "best region" (no capacity target) | **Preset** | Region optimization is preset's specialty |
+
+### Multi-Mode Chaining
+
+Some prompts require two modes in sequence:
+
+**Pattern: Capacity → Deploy**
+When a user specifies a capacity requirement AND wants deployment:
+1. Run **Capacity Discovery** to find regions/projects with sufficient quota
+2. Present findings to user
+3. Ask: "Would you like to deploy with **quick defaults** or **customize settings**?"
+4. Route to **Preset** or **Customize** based on answer
+
+> 💡 **Tip:** If unsure which mode the user wants, default to **Preset** (quick deployment). Users who want customization will typically use explicit keywords like "custom", "configure", or "with specific settings".
+
+## Project Selection (All Modes)
+
+Before any deployment, resolve which project to deploy to. This applies to **all** modes (preset, customize, and after capacity discovery).
+
+### Resolution Order
+
+1. **Check `PROJECT_RESOURCE_ID` env var** — if set, use it as the default
+2. **Check user prompt** — if user named a specific project or region, use that
+3. **If neither** — query the user's projects and suggest the current one
+
+### Confirmation Step (Required)
+
+**Always confirm the target before deploying.** Show the user what will be used and give them a chance to change it:
+
+```
+Deploying to:
+  Project:  <project-name>
+  Region:   <region>
+  Resource: <resource-group>
+
+Is this correct? Or choose a different project:
+  1. ✅ Yes, deploy here (default)
+  2. 📋 Show me other projects in this region
+  3. 🌍 Choose a different region
+```
+
+If user picks option 2, show top 5 projects in that region:
+
+```
+Projects in <region>:
+  1. project-alpha (rg-alpha)
+  2. project-beta (rg-beta)
+  3. project-gamma (rg-gamma)
+  ...
+```
+
+> ⚠️ **Never deploy without showing the user which project will be used.** This prevents accidental deployments to the wrong resource.
+
+## Pre-Deployment Validation (All Modes)
+
+Before presenting any deployment options (SKU, capacity), always validate both of these:
+
+1. **Model supports the SKU** — query the model catalog to confirm the selected model+version supports the target SKU:
+   ```bash
+   az cognitiveservices model list --location <region> --subscription <sub-id> -o json
+   ```
+   Filter for the model, extract `.model.skus[].name` to get supported SKUs.
+
+2. **Subscription has available quota** — check that the user's subscription has unallocated quota for the SKU+model combination:
+   ```bash
+   az cognitiveservices usage list --location <region> --subscription <sub-id> -o json
+   ```
+   Match by usage name pattern `OpenAI.<SKU>.<model-name>` (e.g., `OpenAI.GlobalStandard.gpt-4o`). Compute `available = limit - currentValue`.
+
+> ⚠️ **Warning:** Only present options that pass both checks. Do NOT show hardcoded SKU lists — always query dynamically. SKUs with 0 available quota should be shown as ❌ informational items, not selectable options.
+
+> 💡 **Quota management:** For quota increase requests, usage monitoring, and troubleshooting quota errors, defer to the [quota skill](../../quota/quota.md) instead of duplicating that guidance inline.
+
+## Prerequisites
+
+All deployment modes require:
+- Azure CLI installed and authenticated (`az login`)
+- Active Azure subscription with deployment permissions
+- Azure AI Foundry project resource ID (or agent will help discover it via `PROJECT_RESOURCE_ID` env var)
+
+## Sub-Skills
+
+- **[preset/SKILL.md](preset/SKILL.md)** — Quick deployment to optimal region with sensible defaults
+- **[customize/SKILL.md](customize/SKILL.md)** — Interactive guided flow with full configuration control
+- **[capacity/SKILL.md](capacity/SKILL.md)** — Discover available capacity across regions and projects