skill-creator

技能创建器

创建技能以扩展 AI Agent 能力的指南，重点介绍 Azure SDK 和 Microsoft Foundry。

必需上下文： 创建 SDK 或 API 技能时，用户必须提供 SDK 包名称、文档 URL 或仓库引用，作为技能的依据。

关于技能

技能是模块化知识包，可将通用 Agent 转变为专业专家：

1. 流程知识 — 特定领域的多步骤工作流
2. SDK 专业知识 — Azure 服务的 API 模式、身份验证、错误处理
3. 领域背景 — 架构、业务逻辑、公司特定模式
4. 捆绑资源 — 用于复杂任务的脚本、参考资料、模板

---

核心原则

1. 简洁为要

上下文窗口是共享资源。审视每一部分：“它值得占用这些 token 吗？”

对于领域/流程技能：Agent 已具备相应能力。只添加它们尚不了解的内容。

对于 SDK/API 技能：用户必须提供 SDK 包名称、文档 URL 或仓库引用。没有这些上下文就无法创建技能。

2. 优先使用最新文档

Azure SDK 不断变化。 技能应指导 Agent 核实文档：

## Before Implementation

Search `microsoft-docs` MCP for current API patterns:

- Query: "[SDK name] [operation] python"
- Verify: Parameters match your installed SDK version

3. 自由度

根据实现约束调整具体程度。方法多样时给予较高自由度；需要精确执行时则降低自由度：

自由度	适用情况	示例
高	存在多种有效方法	文本指南
中	有首选模式，但允许变化	伪代码
低	必须精确执行	特定脚本

4. 渐进式披露

技能分三个层级加载：

1. 元数据（约 100 个词）— 始终位于上下文中
2. SKILL.md 正文（少于 5k 个词）— 技能触发时加载
3. 参考资料（不限）— 按需加载

SKILL.md 应少于 500 行。 接近此上限时，将内容拆分到参考文件中。

---

技能结构

快速参考：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      — Executable code
    ├── references/   — Documentation loaded as needed
    └── assets/       — Output resources (templates, images)

对于 Azure SDK 技能，请遵循下文的技能章节顺序。对于领域技能，可自行判断如何进行逻辑组织。

SKILL.md 要点

• Frontmatter：name 和 description（description 用于触发技能）
• 正文：少于 500 行；较大的技能应拆分到参考文件中

捆绑资源（可选）

类型	适用情况	示例
scripts/	重用的代码模式	身份验证设置、CLI 脚本
references/	功能深入说明和扩展示例	capabilities.md 索引、non-hero-scenarios.md、API 文档
assets/	输出模板	样板代码、图片

---

创建 Azure SDK 技能

为 Azure SDK 创建技能时，请始终遵循以下模式。

Token Budget 指南（必需）

每个 Azure SDK 技能都必须遵守以下 token 限制：

Section	Target	Absolute Max
安装 + 环境变量	100 个 token	150
身份验证与生命周期	200 个 token	300
核心工作流（1 个示例）	300 个 token	400
功能表格	200 个 token	300
最佳实践（6-8 项）	200 个 token	250
参考资料（reference/ 链接）	100 个 token	150
SKILL.md 总计	约 1100 个 token	约 1500 个 token

强制要求：

• 超出最大限制 → 重构并移至 /references/ 子目录
• 接近 500 行时 → 将整个章节移至参考文件
• 在技能的 H1 标题正下方添加 `` 注释

---

参考资料提取指南（必需）

根据以下信号决定哪些内容放在 SKILL.md 中，哪些内容放在 /references/ 中：

信号	移至 /references/	保留在 SKILL.md 中
使用频率	低于典型使用情况的 20%	约 80% 或更多的工作流
认知负荷	高级模式、多种选项	单一顺畅路径
示例长度	超过 10 行、多条路径	1-5 行、单一路径

内容提取规则：

• 批量操作 → /references/batch-operations.md
• 错误处理（超出 try-except 的内容） → /references/error-handling.md
• 性能调优 → /references/performance.md
• 替代工作流 → /references/workflows-comparison.md
• 流式处理/事件 → /references/streaming.md
• 高级身份验证 → /references/auth-strategies.md
• 工具集成 → /references/tools.md
• 破坏性变更 → /references/migration.md

**决策：**将常见情况保留在 SKILL.md 中，将边缘情况移至 /references/。

---

核心工作流规范（必需）

每个 Azure SDK 技能都必须说明其介绍了哪些工作流。

情况 1：单一明确的“核心工作流”（大多数服务）

如果一种模式能够处理约 80% 的用例：

1. 将其指定为核心工作流
2. 在 SKILL.md 中仅展示此工作流（一个完整、可运行的示例）
3. 将其他方案放在 /references/ 中：
   • 批量操作 → /references/batch-operations.md
   • 错误处理 → /references/error-handling.md
   • 性能调优 → /references/performance.md
   • 其他工作流 → /references/workflows-comparison.md

示例：Azure Key Vault Secrets（核心工作流：使用托管标识检索机密）。将其他身份验证工作流放在 /references/ 中：使用 DefaultAzureCredential 进行本地开发、工作负载标识，以及服务主体凭据（客户端机密或证书）。

情况 2：多个同样有效的“核心工作流”（例如，身份验证策略、部署目标）

如果没有一种模式占主导地位：

1. 在 SKILL.md 中纳入所有主要场景，即使这意味着包含多个同样有效的工作流
2. 在 SKILL.md 中为每个主要场景提供一个完整、可运行的示例
3. 使用 /references/workflows-comparison.md 介绍权衡、次要变体，以及其他可能导致主文件臃肿的深入内容
4. 不要将有效的替代方案视为“高级”用法，若它们是实际使用中的核心方案——它们同样有效，只是适用于不同场景

示例：Azure Identity SDK 有多个主要场景。在 SKILL.md 中保留主要的本地开发凭据流和适用于生产环境的安全凭据流，然后使用 /references/credential-types.md 深入比较 AzureCliCredential、工作负载标识、服务主体变体和其他次要凭据选项。

判断规则：如果不确定，请问：“选择另一种方法的用户会认为我写的方法是错误的吗？”如果会，那么另一种方法就是另一个主要场景，应纳入 SKILL.md。如果不会，则可以简要概述并链接到 /references/。

---

技能章节顺序

遵循此结构（基于现有 Azure SDK 技能）：

1. 标题 — # SDK Name
2. 安装 — pip install、npm install 等
3. 环境变量 — 必需的配置，并附带内联注释，说明何时需要此配置。如果在生产环境中使用 DefaultAzureCredential，请包含 AZURE_TOKEN_CREDENTIALS（设置为 prod 或 <specific_credential>）
4. 身份验证与生命周期 — 对于 Python 技能，优先使用 DefaultAzureCredential：在本地开发中直接使用；在生产环境中，将 AZURE_TOKEN_CREDENTIALS 设置为 prod（或特定的目标凭据名称）来约束凭据。也可以直接使用特定的 Microsoft Entra Token 凭据，例如 ManagedIdentityCredential 或 WorkloadIdentityCredential。对于 Python 技能，本节必须以标准提示块开头（见下文的必需的身份验证与生命周期提示块（Python））。
5. 核心工作流 — 最小可行示例（遵循上述核心工作流规范）
6. 功能表格 — 客户端、方法、工具
7. 最佳实践 — 编号列表
8. 参考链接 — 链接到 /references/*.md 的表格（对于 Azure SDK 技能，请包含 capabilities.md 和 non-hero-scenarios.md）

必需的身份验证与生命周期提示框（Python）

**范围：**仅适用于 Python 技能（后缀为 -py）。其他语言可以遵循各自的惯例。

每个 Python Azure SDK 技能的 ## Authentication & Lifecycle 部分都必须以以下提示框开头，且必须原样保留，并放在任何代码示例之前。这样，用户在阅读或复制任何客户端设置代码之前，就能看到这两条不可妥协的规则。

## Authentication & Lifecycle

> **🔑 Two rules apply to every code sample below:**
>
> 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI / VS Code / Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
>    - Local dev: `DefaultAzureCredential` works as-is.
>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_credential>`) to constrain the credential chain to production-safe credentials.
> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:
>    - Sync: `with <Client>(...) as client:`
>    - Async: `async with <Client>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)
>
> Snippets may abbreviate this setup, but production code should always follow both rules.

放置规则：

• 紧跟在 ## Authentication & Lifecycle 标题下方，并放在第一个代码示例之前。
• 不要改写或重组措辞——保持各技能之间的一致性正是重点。
• 如果 SDK 完全不支持 Entra ID（这种情况很少见，例如某些旧版语音 REST 终结点、要求使用订阅密钥的 WebSocket API），则保留规则 #2（上下文管理器），并将规则 #1 替换为一句话，说明该 SDK 要求使用 API 密钥身份验证，并解释 Entra ID 为何尚不可用。
• 如果 SDK 仅支持异步操作（例如 azure-ai-voicelive），则保留两条规则，但在项目符号中仅展示异步形式。
• 对于没有客户端生命周期的非 Azure Python 技能（例如 pydantic-models-py），完全跳过此提示框。

**代码示例要求。**技能正文中的每个客户端构造都必须遵守这两条规则：

• 在用法示例中，每次实例化客户端都要展示 with / async with（不能只在身份验证部分展示）。
• 在主要身份验证示例中展示 DefaultAzureCredential。对于仍正式支持密钥的 SDK，不要删除 API 密钥示例——许多现有用户（尤其是在受监管环境中仍在完成 Entra 推广的用户）需要可直接复制粘贴、能够运行的示例。将使用密钥的代码片段移至同一个 ## Authentication & Lifecycle 部分中主要 DefaultAzureCredential 代码块之后，并放入明确标注的 ### Legacy: API Key (existing keyed deployments) 小节。在此处加上一行说明：新代码应使用 DefaultAzureCredential，使用密钥的方式适用于现有部署。同时在环境变量部分恢复 <SERVICE>_KEY 环境变量，并附上注释 # Only required for the legacy API-key auth path below。
• 少数服务有值得在 Legacy 小节中说明的密钥使用注意事项（例如 azure-ai-translation-text 使用密钥访问全局终结点时需要设置 region= 参数，因为基于令牌凭据的身份验证要求使用自定义子域终结点）。应在移至 Legacy 小节的代码块中说明这些注意事项，而不是删除示例。
• 对于异步示例，请将 azure.identity.aio 中的 DefaultAzureCredential 与客户端一起放在 async with credential: 中。

身份验证模式（所有语言）

本地开发时，使用支持多种身份验证方式的 DefaultAzureCredential。生产环境中，使用特定凭据类型，或通过将环境变量 AZURE_TOKEN_CREDENTIALS 设置为 prod 来配置 DefaultAzureCredential，也可以指定目标凭据。

如果配置 Rust 技能，本地开发时使用 DeveloperToolsCredential，生产环境中使用 ManagedIdentityCredential。Rust SDK 不支持 DefaultAzureCredential，因此应在每种环境中明确使用相应凭据。

# Python — note: client is wrapped in `with` for deterministic cleanup
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
# Local dev: DefaultAzureCredential works as-is.
credential = DefaultAzureCredential()
# Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS.
# credential = DefaultAzureCredential(require_envvar=True)
# Or use a specific credential directly in production:
# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
with ServiceClient(endpoint, credential) as client:
    client.do_thing()

// C#
using Azure.Identity;

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes
// var credential = new ManagedIdentityCredential();
var client = new ServiceClient(new Uri(endpoint), credential);

// Java
import com.azure.identity.AzureIdentityEnvVars;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
TokenCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#credential-classes
// TokenCredential credential = new ManagedIdentityCredentialBuilder().build();
ServiceClient client = new ServiceClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();

// TypeScript
import {
  DefaultAzureCredential,
  ManagedIdentityCredential,
} from "@azure/identity";
// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
const credential = new DefaultAzureCredential({
  requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"],
});
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();
const client = new ServiceClient(endpoint, credential);

// Go
import (
  "context"

  "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
  "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

ctx := context.Background()

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
  panic(err)
}

// Or use a specific credential directly in production:
// cred, err := azidentity.NewManagedIdentityCredential(nil)

client, err := azblob.NewClient("https://<account>.blob.core.windows.net/", cred, nil)
if err != nil {
  panic(err)
}

_ = client
_ = ctx

// Rust
use azure_identity::DeveloperToolsCredential;
use azure_storage_blob::BlobServiceClient;

let credential = DeveloperToolsCredential::new(); // Local dev
let client = BlobServiceClient::new(
    "https://<account>.blob.core.windows.net/",
    credential,
    None,
)?;

切勿将凭据硬编码。请使用环境变量。

反模式：不要这样做（必读）

这些做法会导致内容臃肿、效率低下。每位技能编写者都必须在编写前阅读本节。

反模式 1：“穷举式 API 参考”

• ❌ 不要：在功能表中列出全部 50 个 SDK 方法，并为每种用法都提供代码示例
• ✅ 应该：在表格中展示 3～5 个核心方法；如需完整列表，请链接到 Azure 官方 API 参考
• 令牌成本：列出所有方法及示例会浪费 400～600 个令牌
• 对用户的影响：认知负担过重，用户不知道该使用哪些方法

反模式 2：“用多种方式解决同一个问题”

• ❌ 不要：在正文中写“以下是对结果进行分页的 A、B、C、D 四种方法”
• ✅ 应该：使用“同步分页请用 ItemPaged”（主要示例）；将其他方法链接到 /references/
• Token 成本：每种替代方法会增加 50-100 个 token；5 种方法会让技能变得低效
• 对用户的影响：难以抉择；用户会反复阅读所有内容

反模式 3：“在一个技能中涵盖初级、中级和高级内容”

• ❌ 不要：让技能从“什么是客户端？”讲到“自定义重试策略”，再讲到“断路器模式”
• ✅ 应该：核心工作流覆盖 80% 的使用场景；高级模式放在 /references/ 中
• Token 成本：每个技能等级会增加 200-300 个 token；三个等级会多出 600-900 个 token
• 对用户的影响：专家觉得无聊，初学者不堪重负；没人能得到自己需要的内容

反模式 4：“复述官方文档”

• ❌ 不要：“CosmosClient 构造函数接受 endpoint（字符串）和 credential（TokenCredential）。endpoint 用于标识 Azure Cosmos 资源……”
• ✅ 应该：展示代码：client = CosmosClient(endpoint, credential)。链接到官方文档：microsoft-docs MCP。
• Token 成本：冗长的说明会为每个参数增加 50-100 个 token；大型 API 会浪费 300 多个 token
• 对用户的影响：内容重复；官方文档更具权威性，技能应展示用法，而不是复述文档

反模式 5：“明明示例足以说明，却仍长篇解释”

• ❌ 不要：“要创建客户端，首先使用构造函数实例化该类，并传入 endpoint 和 credential 参数。endpoint 是用于标识资源的字符串……”
• ✅ 应该：立即展示代码：with CosmosClient(endpoint, credential) as client:

效率验证（必需 — 第 2 阶段）

编写期间，手动验证技能效率；如果技能在 tests/scenarios/<skill-name>/vally/ 下有 Vally 评估，则运行该评估。

1. 测量令牌数：

使用令牌计数器或模型 playground 测量每个部分。与上文的令牌预算指南目标进行比较。如果任何部分超过上限，请将内容移至 /references/。

2. 运行反模式检查清单：

• 不包含详尽的 API 参考（展示 3-5 个核心方法，而非 50 个）
• SKILL.md 中针对同一个问题不提供多种解决方案
• 不混合初级、中级和高级内容
• 不复述官方文档（优先提供代码，并链接到 microsoft-docs）
• 不使用冗长的文字（示例优先，文字精简）

3. 示例数量审查：

• SKILL.md 中记录的每个主要场景 / 核心工作流都提供 1 个完整示例。对于同时支持同步和异步的 Python SDK，同一工作流的成对同步 + 异步示例算作 1 个工作流，而不是 2 个。
• 功能表包含 3-5 个核心方法（非完整 API）
• 每条最佳实践至多提供 1 个示例

4. Frontmatter 验证：

• name 与 .github/skills/<name>/SKILL.md 匹配
• description 包含触发关键词
• description 简洁（约 200 个字符是合适的目标；架构上限为 1,024 个字符）
• 如果包含可选的 benchmark_tokens_* 和 benchmark_quality_* 元数据字段，它们应是 metadata 下的字符串值

4b. 身份验证指导验证（所有凭据都必须执行）：

• 如果技能使用 Azure Identity 凭据，请根据该语言 / 包的当前官方凭据文档核实指导（如有 Microsoft Learn 文档则优先使用；否则参考上游 SDK 存储库或包文档）
• 对于 Python 技能，开发指导可以建议使用 DefaultAzureCredential（支持多种开发凭据类型）
• 对于 Python 技能，生产指导：单独使用不受限制的 DefaultAzureCredential 并不足够；必须使用 AZURE_TOKEN_CREDENTIALS=prod（或指定目标凭据）限制凭据链，或者直接使用特定凭据（例如 ManagedIdentityCredential）
• 对于 Rust 技能，开发 / 生产指导应反映实际支持的凭据（本地开发使用 DeveloperToolsCredential；生产环境使用特定的生产凭据，例如 ManagedIdentityCredential）
• 链接到 /references/auth-strategies.md 或官方文档，说明如何选择生产凭据

4c. 运行 Vally lint/eval（如果技能在 tests/scenarios/<skill-name>/vally/ 下有规范）：

# If the eval spec uses the shared Rust custom grader plugin, build it first.
(cd tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure && npm install && npm run build)

vally lint --eval-spec tests/scenarios/<skill-name>/vally/eval.yaml \
  --grader-plugin tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure \
  --strict

vally eval --eval-spec tests/scenarios/<skill-name>/vally/eval.yaml \
  --grader-plugin tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure

• vally lint 运行通过，且没有错误
• 当 COPILOT_TOKEN 可用时，vally eval 运行通过（没有错误级别的问题）；否则只运行 lint 即可，符合 Vally Evaluation 工作流的行为
• 没有 vally/ 规范的技能跳过此步骤——此步骤对单个技能而言是可选的，并非每个技能都必须执行

5. 抽查：

• 用户能否复制核心工作流并立即运行？
• 所有示例是否都遵循最佳实践（上下文管理器、适当的凭据）？
• 是否记录了所有环境变量？

输出： 验证后，在技能标题中标注测得的令牌数：

# Azure Service SDK

---

标准动词模式

Azure SDK 在所有语言中使用一致的动词：

动词	行为
create	创建新项；若已存在则失败
upsert	创建或更新
get	获取；若缺失则报错
list	返回集合
delete	即使目标不存在也会成功
begin	启动长时间运行的操作

特定语言的模式

有关详细模式，请参阅 references/azure-sdk-patterns.md，包括：

• Python：ItemPaged、LROPoller、上下文管理器、Sphinx 文档字符串。如果 SDK 同时提供同步和异步客户端，则应将两种形式都作为一等选项介绍；不要偏向其中任何一种。如果 SDK 仅支持同步或异步，则只记录可用模式。不要在单个代码示例中混用同步和异步。始终展示 with / async with 上下文管理器。
• .NET：Response<T>、Pageable<T>、Operation<T>、模拟支持
• Java：Builder 模式、PagedIterable/PagedFlux、Reactor 类型
• TypeScript：PagedAsyncIterableIterator、AbortSignal、浏览器注意事项
• Go：将 context.Context 作为第一个参数，通过 New*Pager() + More()/NextPage(ctx) 使用 runtime.Pager[T]，通过 Begin* + PollUntilDone(ctx, nil) 使用 runtime.Poller[T]，to.Ptr(...) 辅助函数，以及有类型的 *azcore.ResponseError
• Rust：通过 cargo add 安装，azure_core 依赖规则、Response<T>、Pager<T>、RequestContent::from()、.into_model()、显式凭据类型、Entra ID 身份验证的 RBAC 角色

每项技能中必需的最佳实践（面向用户）

Python、.NET、Java、TypeScript 和 Go 语言

这两条规则不仅是技能本身的编写规范，还必须明确写入每个生成技能的 ## Best Practices 部分，以便遵循该技能的最终用户在自己的代码中应用这些规则。

将以下两项逐字添加为最佳实践列表中的前两项（仅可根据语言/SDK 的具体情况进行调整）。不要假设用户会从示例中自行推断。

标准措辞（Python；其他语言请相应调整）：

1. **Do not mix sync and async clients in the same call path.** Use either `azure.xxx` sync clients or `azure.xxx.aio` async clients within a single call path — do not combine both.
2. **Always use context managers for clients and async credentials.** Wrap every client in `with Client(...) as client:` (sync) or `async with Client(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up.
3. **Use `DefaultAzureCredential`** for code that runs locally. For code that runs in Azure, either constrain `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS=prod` (or a specific target credential) or use a specific token credential directly (e.g. `ManagedIdentityCredential`, `WorkloadIdentityCredential`).

SDK 形式不同时适用的变体：

Skill 类型	将第 1 项调整为	将第 2 项调整为
仅支持异步的 SDK（例如 voicelive）	“此 SDK 仅支持异步；请始终使用 .aio 命名空间。”	保持标准
面向异步的框架指南（例如某些 Agent 框架）	“在必要时使用框架文档中说明的异步模式，但不要声称 Azure Python SDK 普遍优先使用异步。”	保持标准
提供程序模式（OpenTelemetry 导出器／发行版）	保持标准	“在进程退出时调用 provider.shutdown() / flush() 以刷新遥测数据——提供程序不是上下文管理器。”
基于 httpx 的 REST 技能	保持标准	“使用 with httpx.Client(...) as client:（同步）或 async with httpx.AsyncClient(...) as client:（异步），以便连接池能够正常工作，并确定性地关闭连接。”
身份验证技能	保持标准	“当凭据管理了需要清理的令牌缓存／HTTP 传输时，请将凭据用作上下文管理器（with DefaultAzureCredential() as credential:）；对于异步场景，请对来自 azure.identity.aio 的凭据使用 async with。”
FastAPI（非 Azure）	“根据端点是否调用异步 I/O，选择 def 或 async def；不要在同一个处理程序中混用同步调用和阻塞调用。”	“在 lifespan 中管理长生命周期资源（数据库连接池、HTTP 客户端），并通过 Depends 注入；对每个请求的资源使用 with／async with。”
纯模型／架构技能（无 I/O，例如 pydantic）	跳过两项——不适用	跳过
代码示例中的规则执行。 技能中的每个代码示例都必须遵守这两条规则，以此展示技能所倡导的做法：

• 不要在单个示例中交错使用同步和异步调用。当 SDK 同时提供同步和异步客户端时，应分别用各自完整且独立的示例展示每种模式，即设置 ### Sync 和 ### Async 小节，并给予两者同等的篇幅。当 SDK 仅支持同步或异步时，只展示可用的模式。
• 每个示例中的每次客户端实例化都必须放在 with / async with 中。唯一允许的例外是必须提供的 Authentication 代码片段（用于说明凭据与客户端的构造模式），以及客户端由应用拥有的框架生命周期模式（例如 FastAPI lifespan）。
• 当示例中使用来自 azure.identity.aio 的异步凭据时，应将其与客户端一起放在 async with credential: 中。

Rust 语言

这些规则必须在每个 Rust 技能的 ## Best Practices 小节中明确列为最前面的条目：

1. 使用 cargo add 管理依赖项，绝不要直接编辑 Cargo.toml。 始终使用 cargo add <crate> 或 cargo remove <crate>，而不是手动修改清单文件。官方 crate 发布在 crates.io 上，应通过 cargo 添加。

2. 仅在直接导入 azure_core 类型时，才将 azure_core 添加到 Cargo.toml。 如果代码导入了 azure_core::http::Url、azure_core::http::RequestContent 或 azure_core::error::ErrorKind 等类型，请明确将 azure_core 添加为依赖项。如果只使用服务 crate 重新导出的类型（例如通过 use azure_storage_blob::BlobClient 导入），则可选是否直接依赖 azure_core。

3. 本地开发使用 DeveloperToolsCredential，生产环境使用 ManagedIdentityCredential。 Rust SDK 不支持 DefaultAzureCredential，因此请针对每种环境明确使用适当的凭据。

4. 使用 RequestContent::from() 封装上传数据。 上传数据（例如 Blob）时，请使用 RequestContent::from(your_data) 封装内容，确保 SDK 能正确处理。

5. 为 Entra ID 身份验证分配适当的 RBAC 角色。 在生产环境中使用 Entra ID 进行身份验证时，请确保该身份已分配所需的 RBAC 角色（例如，拥有 Blob 写入权限时分配 “Storage Blob Data Contributor”）。

6. 始终通过 crates.io 验证软件包版本。 使用软件包前，请在 crates.io 上检查其版本，确保使用的是稳定且受支持的发行版。

7. 让 #[non_exhaustive] 模型结构体和枚举面向未来。 Azure Rust SDK 的请求/响应模型经常带有 #[non_exhaustive]。对于同时派生了 Default 的可从外部构造结构体，应在初始化器末尾添加 ..Default::default()（即使当前已知的所有字段都已设置）；必要时可使用 #[allow(clippy::needless_update)] 在局部屏蔽 lint。对于真正的 #[non_exhaustive] 结构体（Rust 禁止外部结构体字面量，会产生 E0639），请使用提供的构造函数或构建器，或者先构造默认值，再修改所需字段。匹配 SDK 枚举时，请加入通配符（_）分支，以免服务未来新增变体导致匹配失效。如果技能说明了模型的构造方式，其代码示例必须展示这一模式。完整示例请参阅 references/azure-sdk-patterns.md（Model Types）。

有效技能示例（仅限结构合规的技能）

仅将已采用所需 references/ 布局（references/capabilities.md 和 references/non-hero-scenarios.md）的 Azure SDK 技能作为基准。较早、不符合此结构的技能仍可用于参考风格，但在其符合要求之前，不要直接照搬。

有效的基准技能应当：

1. 控制在 1,500 个 Token 以内（绝对上限；请参阅上方的 Token 预算指南）
2. 涵盖核心工作流（CRUD 或主要操作），而非每种功能变体
3. 每个概念提供 1–2 个示例，而非 3–5 个
4. 使用表格汇总 API（凭据类型、RBAC 角色、客户端层级）
5. 链接到官方文档，并通过 microsoft-docs MCP 获取，而不是重复编写
6. 将高级模式移至 /references/
7. 包含 references/capabilities.md 和 references/non-hero-scenarios.md

编写技能之前：直接应用上述检查清单，然后只参考适合你用例的结构模式。

---

处理已弃用或更名的 SDK

当 Azure SDK 已弃用或更名时，更新技能以引导用户使用当前包，同时保持向后兼容性：

1. 在技能顶部添加迁移通知：

> **⚠️ MIGRATION NOTICE**: The [Old Service Name] has been rebranded to **[New Service Name]**. While the package `old-package-name` remains available for compatibility, **new projects should use `new-package-name`** which provides the latest features and updates.
>
> **For new projects**: Use the `new-package-name` package instead.
>
> **This skill remains valid** for existing projects using `old-package-name`, but be aware you're using the legacy package name. The API patterns shown here are compatible with both packages.

2. 展示两种安装选项：

## Installation

### Legacy Package (Old Name)

\`\`\`xml
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-old-package</artifactId>
<version>4.2.0</version>
</dependency>
\`\`\`

### Recommended Package (New Name)

**For new projects, use the rebranded package:**

\`\`\`xml
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-new-package</artifactId>
<version>1.0.0</version>
</dependency>
\`\`\`

> **Note**: The API patterns in this skill apply to both packages. Replace package names and imports as needed when using `azure-new-package`.

3. 何时创建新技能，何时更新现有技能：

• 如果 API 基本兼容（类名和方法名相同或相似），则更新现有技能
• 如果 API 发生重大变化，则创建新技能和迁移指南（使用 references/migration.md）
• 始终在新旧技能之间交叉引用

示例：

• azure-ai-formrecognizer-java → azure-ai-documentintelligence（服务更名）
• azure-communication-callingserver-java → azure-communication-callautomation（已弃用，并附带迁移指南）

示例：Azure SDK 技能结构

---
name: skill-creator
description: |
  Azure AI Example SDK for Python. Use for [specific service features].
  Triggers: "example service", "create example", "list examples".
---

# Azure AI Example SDK

## Installation

\`\`\`bash
pip install azure-ai-example
\`\`\`

## Environment Variables

\`\`\`bash
AZURE_EXAMPLE_ENDPOINT=https://<resource>.example.azure.com
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production
\`\`\`

## Authentication & Lifecycle

> **🔑 Two rules apply to every code sample below:**
>
> 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI / VS Code / Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
>    - Local dev: `DefaultAzureCredential` works as-is.
>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_credential>`) to constrain the credential chain to production-safe credentials.
> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:
>    - Sync: `with <Client>(...) as client:`
>    - Async: `async with <Client>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)
>
> Snippets may abbreviate this setup, but production code should always follow both rules.

\`\`\`python
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
from azure.ai.example import ExampleClient

# Local dev: DefaultAzureCredential works as-is.
credential = DefaultAzureCredential()

# Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS.
# credential = DefaultAzureCredential(require_envvar=True)

# Or use a specific credential directly in production:

# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes

# credential = ManagedIdentityCredential()

with ExampleClient(
endpoint=os.environ["AZURE_EXAMPLE_ENDPOINT"],
credential=credential,
) as client:
item = client.get_item("example")
\`\`\`

## Core Workflow

\`\`\`python
with ExampleClient(endpoint=endpoint, credential=credential) as client: # Create
item = client.create_item(name="example", data={...})

    # List (pagination handled automatically)
    for item in client.list_items():
        print(item.name)

    # Long-running operation
    poller = client.begin_process(item.id)
    result = poller.result()

    # Cleanup
    client.delete_item(item.id)

\`\`\`

## Reference Files

| File                                                                 | Contents                                               |
| -------------------------------------------------------------------- | ------------------------------------------------------ |
| [references/capabilities.md](references/capabilities.md)             | Capability index (hero coverage + links to deep-dives) |
| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Concrete non-hero examples                             |
| [references/tools.md](references/tools.md)                           | Tool integrations                                      |
| [references/streaming.md](references/streaming.md)                   | Event streaming patterns                               |

---

技能创建流程

1. 收集 SDK 上下文 — 用户提供 SDK/API 参考（必需）
2. 了解 — 研究官方文档中的 SDK 模式
3. 规划 — 确定可复用资源和产品领域类别
4. 创建 — 在 .github/skills/<skill-name>/ 中编写 SKILL.md
5. 分类 — 在 skills/<language>/<category>/ 中创建符号链接
6. 测试 — 创建验收标准和测试场景
7. 记录文档 — 更新 README.md 技能目录
8. 迭代 — 根据实际使用情况进行改进

步骤 1：收集 SDK 上下文（必需）

创建任何 SDK 技能之前，用户必须提供：

必需项	示例	用途
SDK 包	azure-ai-agents、Azure.AI.OpenAI、azblob	确定具体的 SDK
文档 URL	https://learn.microsoft.com/en-us/azure/ai-services/...	主要信息来源
仓库（可选）	Azure/azure-sdk-for-python、Azure/azure-sdk-for-go	提供代码模式

若用户未提供，请向其询问：

To create this skill, I need:
1. The SDK package name (e.g., azure-ai-projects)
2. The Microsoft Learn documentation URL or GitHub repo
3. The target language (py/dotnet/ts/java/go)

先搜索官方文档：

# Use microsoft-docs MCP to get current API patterns
# Query: "[SDK name] [operation] [language]"
# Verify: Parameters match the latest SDK version

步骤 2：了解技能

收集具体示例：

• “此技能应涵盖哪些 SDK 操作？”
• “哪些触发条件应启用此技能？”
• “开发者常遇到哪些错误？”

示例任务	可复用资源
每次都使用相同的身份验证代码	SKILL.md 中的代码示例
复杂的流式处理模式	references/streaming.md
工具配置	references/tools.md
错误处理模式	references/error-handling.md

步骤 3：规划产品领域类别

技能通过符号链接，按语言和产品领域组织在 skills/ 目录中。

产品领域类别：

类别	说明	示例
foundry	AI Foundry、Agent、项目、推理	azure-ai-agents-py、azure-ai-projects-py
data	存储、Cosmos DB、表、Data Lake	azure-cosmos-py、azure-storage-blob-py
messaging	Event Hubs、Service Bus、Event Grid	azure-eventhub-py、azure-servicebus-py
monitoring	OpenTelemetry、App Insights、查询	azure-monitor-opentelemetry-py
identity	身份验证、DefaultAzureCredential	azure-identity-py
security	Key Vault、机密、密钥、证书	azure-keyvault-py
integration	API Management、App Configuration	azure-appconfiguration-py
compute	Batch、ML 计算	azure-compute-batch-java
container	Container Registry、ACR	azure-containerregistry-py

根据以下因素确定类别：

1. Azure 服务系列（Storage → data、Event Hubs → messaging）
2. 主要用例（AI Agent → foundry）
3. 同一服务领域中的现有技能

步骤 4：创建技能

位置： .github/skills/<skill-name>/SKILL.md

命名约定：

• azure-<service>-<subservice>-<language>
• 示例：azure-ai-agents-py、azure-cosmos-java、azure-storage-blob-ts、azure-storage-blob-go
• 在 Go 技能的文档正文中，使用简短的包名（例如 azblob）。
• 仅在代码/导入示例中使用完整的模块导入路径（例如 github.com/Azure/azure-sdk-for-go/sdk/storage/azblob）。

对于 Azure SDK 技能：

1. 在 microsoft-docs MCP 中搜索最新的 API 模式
2. 对照已安装的 SDK 版本进行验证
3. 按照上述章节顺序编写
4. 在示例中加入清理代码
5. 添加功能对比表

先编写捆绑资源，再编写 SKILL.md。

完成前的质量保障：

1. 编写时测量各章节的 token 数量（使用模型 playground 的 token 计数器）
2. 对照 Token Budget Guidelines 的目标
3. 根据反模式检查清单进行验证（参见 Anti-Patterns 章节）
4. 如果章节超过 token 上限，则提取到 /references/
5. 运行 Efficiency Validation 检查清单；如果技能有规范，也包括 vally lint/vally eval（参见 Efficiency Validation）
6. 可选：在 frontmatter 的 metadata 映射下添加 benchmark_tokens_* 和 benchmark_quality_* 字段（均为扁平字符串值）
7. 在技能标题中添加 token 数量注释，便于日后维护

Frontmatter（增强了基准测试元数据）：

---
name: azure-service-py
description: |
  Azure Service SDK for Python. Use for [specific features].
  Triggers: "service name", "create resource", "specific operation".
metadata:
  benchmark_tokens_estimated: "1180"
  benchmark_tokens_target: "1100"
  benchmark_tokens_max: "1500"
  benchmark_quality_single_core_workflow: "true"
  benchmark_quality_examples_focused: "true"
  benchmark_quality_no_prose_bloat: "true"
  benchmark_quality_anti_patterns_checked: "true"
---

元数据字段：（根据 Agent Skills metadata 规范，所有值均为字符串——字符串键映射到字符串值）

• benchmark_tokens_estimated — 实际测得的 token 数量
• benchmark_tokens_target — 效率目标（通常为 1100）
• benchmark_tokens_max — 绝对上限（1500；超过则拆分）
• benchmark_quality_* — 各项反模式检查，每项的值均为 "true"/"false" 字符串（例如 benchmark_quality_single_core_workflow）

步骤 5：使用符号链接分类

在 .github/skills/ 中创建技能后，在相应类别中创建符号链接：

# Pattern: skills/<language>/<category>/<short-name> -> ../../../.github/skills/<full-skill-name>

# Example for azure-ai-agents-py in python/foundry:
cd skills/python/foundry
ln -s ../../../.github/skills/azure-ai-agents-py agents

# Example for azure-cosmos-db-py in python/data:
cd skills/python/data
ln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db

# Example for azure-storage-blob-go in go/data:
cd skills/go/data
ln -s ../../../.github/skills/azure-storage-blob-go blob

符号链接命名：

• 使用简短且能描述用途的名称（例如 agents、cosmos、blob）
• 删除 azure- 前缀和语言后缀
• 遵循类别中的现有命名模式

验证符号链接：

ls -la skills/python/foundry/agents
# Should show: agents -> ../../../.github/skills/azure-ai-agents-py

步骤 6：创建测试

每项技能都必须有验收标准和测试场景。

6.1 创建验收标准

位置： tests/scenarios/<skill-name>/acceptance-criteria.md

将验收标准保存在 tests/ 目录树中（切勿放在技能文件夹内、与 SKILL.md 并列）。

资料来源（按优先级排序）：

1. Microsoft Learn 官方文档（通过 microsoft-docs MCP）
2. 仓库中的 SDK 源代码
3. 技能中的现有参考文件

格式：

# Acceptance Criteria: <skill-name>

**SDK**: `package-name`
**Repository**: https://github.com/Azure/azure-sdk-for-<language>
**Purpose**: Skill testing acceptance criteria

---

## 1. Correct Import Patterns

### 1.1 Client Imports

#### ✅ CORRECT: Main Client

\`\`\`python
from azure.ai.mymodule import MyClient
from azure.identity import DefaultAzureCredential
\`\`\`

#### ❌ INCORRECT: Wrong Module Path

\`\`\`python
from azure.ai.mymodule.models import MyClient # Wrong - Client is not in models
\`\`\`

## 2. Authentication Patterns

#### ✅ CORRECT: DefaultAzureCredential + context manager

\`\`\`python
credential = DefaultAzureCredential()
with MyClient(endpoint, credential) as client:
client.do_thing()
\`\`\`

#### ❌ INCORRECT: Hardcoded Credentials

\`\`\`python
client = MyClient(endpoint, api_key="hardcoded") # Security risk
\`\`\`

#### ❌ INCORRECT: Connection string / account key when Entra is supported

\`\`\`python
client = MyClient.from_connection_string(os.environ["CONNECTION_STRING"]) # Bypasses Entra audit/rotation
\`\`\`

#### ❌ INCORRECT: Bare client without context manager

\`\`\`python
client = MyClient(endpoint, credential) # Leaks HTTP transport on exception / interpreter exit
client.do_thing()
\`\`\`

需要记录的关键模式：

• 导入路径（不同 Azure SDK 之间差异很大）
• 身份验证模式
• 客户端初始化
• 异步变体（.aio 模块）
• 常见反模式

6.2 创建测试场景

位置： tests/scenarios/<skill-name>/scenarios.yaml

config:
  model: gpt-4
  max_tokens: 2000
  temperature: 0.3

scenarios:
  - name: basic_client_creation
    prompt: |
      Create a basic example using the Azure SDK.
      Include proper authentication and client initialization.
    expected_patterns:
      - "DefaultAzureCredential"
      - "MyClient"
      - "with MyClient" # enforce context manager
    forbidden_patterns:
      - "api_key="
      - "hardcoded"
      - "from_connection_string" # prefer Entra over connection strings
    tags:
      - basic
      - authentication
    mock_response: |
      import os
      from azure.identity import DefaultAzureCredential
      from azure.ai.mymodule import MyClient

      credential = DefaultAzureCredential()
      with MyClient(
          endpoint=os.environ["AZURE_ENDPOINT"],
          credential=credential,
      ) as client:
          # ... rest of working example
          pass

场景设计原则：

• 每个场景只测试一种特定模式或功能
• expected_patterns — 必须出现的模式
• forbidden_patterns — 绝不能出现的常见错误
• mock_response — 能通过所有检查的完整可运行代码
• tags — 用于筛选（basic、async、streaming、tools）

6.3 运行测试

cd tests
pnpm install

# Check skill is discovered
pnpm harness --list

# Run in mock mode (fast, deterministic)
pnpm harness <skill-name> --mock --verbose

# Run with Ralph Loop (iterative improvement)
pnpm harness <skill-name> --ralph --mock --max-iterations 5 --threshold 85

成功标准：

• 所有场景均通过（通过率为 100%）
• 没有误报（模拟响应始终通过）
• 模式能够捕获实际错误

第 7 步：更新文档

创建技能后：

1. 更新 README.md — 将技能添加到技能目录中相应的语言部分

   • 更新技能总数（第 ~73 行：> N skills in...）
   • 更新 Skill Explorer 链接数量（第 ~15 行：Browse all N skills）
   • 更新语言数量表（第 ~77-83 行）
   • 更新语言部分的技能数量（例如，> N skills • suffix: -py）
   • 更新类别数量（例如，<summary><strong>Foundry & AI</strong> (N skills)</summary>）
   • 在所属类别中按字母顺序添加技能行
   • 更新测试覆盖率摘要（第 ~622 行：**N skills with N test scenarios**）
   • 更新测试覆盖率表 — 更新该语言的技能数量、场景数量和热门技能

2. 重新生成 GitHub Pages 数据 — 运行提取脚本，并通过一次范围限定的目录变更重建文档站点

   (cd docs-site && npx tsx scripts/extract-skills.ts && npm run build)
   

   这会更新 docs-site/src/data/skills.json，该文件为基于 Astro 的文档站点提供数据；随后将站点重新构建到 docs/，由 GitHub Pages 提供服务。

3. 核对 AGENTS.md — 确保技能数量准确

---

第 8 步：根据最新 SDK 源码重新生成现有技能

当现有技能的示例过时、API 签名已更新或包使用指南发生变化时，使用此工作流。

1. 先确定规范源文件

对于 Azure SDK 语言技能，请以官方上游源文档和示例为准：

• Go：https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/<service>/<module>/README.md
• Go 示例：https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/<service>/<module>/
• Rust：https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/<service>/<crate>/README.md
• Rust 示例：https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/<service>/<crate>/examples/
• .NET/Java/Python/TS/Go：使用最新的 Microsoft Learn 包文档和官方 SDK 仓库

2. 针对性更新技能内容

• 更新代码片段，使其符合当前的构造函数/方法签名
• 确保 crate/包名称与官方发布方指南一致
• 保留技能结构/frontmatter，除非有意更改行为
• 上游建议发生变化时，更新“最佳实践”和“参考链接”
• 对于 Rust，如果代码直接使用 azure_core 类型/导入，请确保 Cargo.toml 中包含 azure_core；如果只使用服务 crate 重新导出的内容，则可以不添加直接的 azure_core 依赖

API 表面一致性门禁（每次重新生成技能时均为必需）

将语言对应的权威来源作为重新生成的技能中每个代码片段的契约：

• Python、.NET、Java、TypeScript、Go：以当前 Microsoft Learn API 参考为契约。
• Rust：以官方 SDK 仓库（https://github.com/Azure/azure-sdk-for-rust）和 crates.io 文档为契约；Rust 包没有 Learn API 参考页面。

完成任何重新生成的技能前：

1. 确定代码片段中展示的每个 SDK 类型／方法（客户端、操作组、模型构造函数、枚举成员、begin_* 等长时间运行方法）。
2. 根据该语言／包的权威来源（见上文）验证每个符号和签名。
3. 如果权威来源展示的形式不同（例如嵌套的 properties=... 模型、重命名的方法、begin_* LRO 方法），请相应更新代码片段。
4. 重新检查导入，确保模型／客户端模块与权威来源完全一致。
5. 主要代码片段中不得保留与权威示例相矛盾的兼容性捷径。

场景覆盖门禁（所有语言每次重新生成技能时均为必需）

代码片段能够编译并不代表重新生成已完成——技能还必须展示真实用法的广度。

完成任何重新生成的技能前：

1. 从该 SDK 当前的权威文档／示例中确定核心场景（有 Microsoft Learn 时优先使用；否则使用上游 SDK 仓库和包文档）。
2. 确保技能通过可复制粘贴的代码片段（或在内容过长时显式链接到附带的参考文件）展示每个核心场景。
3. 添加／更新测试场景，通过测试框架模式验证核心流程。
4. 在 SDK 支持的情况下，至少添加一个重要的非核心场景（例如更新／修补、删除／清理、导出／导入、高级身份验证模式、分页／筛选、重试／错误处理或 LRO 监控）。对于同时支持同步和异步客户端的 Python SDK，两种形式应具有同等优先级；不得将任一形式视为普遍首选。
5. 对于 Azure SDK 技能，按以下方式组织 references/：
   • references/capabilities.md：简明索引，记录每个核心场景及其覆盖位置（SKILL.md 或附带的参考文件），并链接到更深入的非核心参考，不得叙述历史／迁移过程。
   • references/non-hero-scenarios.md：具体的非核心示例，有意将其放在主 SKILL.md 之外。
   • 其他 references/*.md 文件：用于专门的深入内容（操作组、工具、评估器矩阵等）。
6. 如果 SDK 覆盖了广泛的操作组（管理 SDK 中较为常见），请加入操作组表格，并明确指出哪些组在代码片段中有所涵盖，哪些仅在参考资料中提及。
7. 除非技能确实展示了所有主要操作组，否则绝不可声称“完整 API 表面”；否则应说明该技能针对核心工作流和部分次要场景进行了优化。

重新生成工作流第 3 步：验证重新生成的技能行为

(cd tests && pnpm harness <skill-name> --mock --verbose)

如果技能包含 Vally 场景，也请在完成前运行相应评估（本地或在 CI 中）。

Rust 重新生成门禁（Rust 技能必需）：

重新生成任何 Rust 技能时，请验证生成的 ## Best Practices 部分包含以下原样的前两条规则：

1. Use cargo add to manage dependencies, never edit Cargo.toml directly
2. Add azure_core only when importing azure_core types directly

完成前使用内容检查：

rg -n "Use `cargo add` to manage dependencies, never edit `Cargo.toml` directly|Add `azure_core` only when importing `azure_core` types directly" .github/plugins/azure-sdk-rust/skills/**/SKILL.md

每个受影响的 Rust 技能都必须包含这两行，否则重新生成尚未完成。

重新生成工作流第 4 步：刷新后重新生成文档产物

(cd docs-site && npx tsx scripts/extract-skills.ts && npm run build)

再生成工作流第 5 步：记录变更内容

在 PR/提交说明中，请包括：

• 使用了哪些上游文档/示例
• 修正了哪些代码片段/签名
• 运行了哪些测试/评估及其结果

Python 插件批量处理方法：azure-sdk-python

当请求是“重新生成 azure-sdk-python 下的所有 Python 技能”时，请使用此方法。

1. 先明确具体目标

# Canonical source of truth for Python plugin skills
ls .github/plugins/azure-sdk-python/skills/*/SKILL.md

• 将 .github/plugins/azure-sdk-python/skills/ 视为规范目录。
• 编辑后保持 .github/skills/<name> 链接同步（请参阅下方的符号链接检查/修复步骤）。

2. 逐个技能从权威来源更新

• 对于最新的 Microsoft Learn API 指南，始终优先使用 microsoft-docs MCP。
• 使用 pip show <package> 验证已安装的包版本，然后检查已安装的包或官方 API 参考，以验证代码片段中使用的每个符号和签名。
• 对于 Azure SDK 技能，优先参考包概览和官方 SDK 仓库中的示例。
• 对于此插件中的非 Azure Python 技能（例如 fastapi-router-py、pydantic-models-py），保留语言特定的最佳实践变体；如果生命周期/身份验证不适用，则跳过 Azure 特定的身份验证提示。

3. 统一应用 Python 规则

• 为 Azure SDK Python 技能保留标准章节顺序。
• 在适用时，确保 ## Authentication & Lifecycle 以规定的提示块（原文不变）开头。
• 确保每个客户端示例都使用 with / async with 生命周期模式。
• 确保 ## Best Practices 以两条规定的面向用户的规则开头（或者采用仅异步/提供程序模式技能的文档变体）。
• 确保每个重新生成的 Azure SDK Python 技能都有 references/capabilities.md（索引）和 references/non-hero-scenarios.md（具体的非典型示例）。
• 保留现有参考资料/资源/脚本，除非它们已过时或不正确。

4. 验证所有重新生成的 Python 技能

# Fast frontmatter/structure validation for every Python skill
python .github/skills/skill-creator/scripts/quick_validate.py .github/plugins/azure-sdk-python/skills/<skill-name>

# Run Python skill harness in mock mode (all *-py scenarios)
(cd tests && pwsh ./run-harness-by-language.ps1 -Language py -Mock)

5. 同步技能链接和文档产物

# Ensure .github/skills links point at plugin canonical skills
python .github/scripts/sync_skill_links.py --plugin azure-sdk-python --check
python .github/scripts/sync_skill_links.py --plugin azure-sdk-python --apply

# Refresh docs site data after content changes
(cd docs-site && npx tsx scripts/extract-skills.ts && npm run build)

6. 批量重新生成的完成标准

• 每个目标 .github/plugins/azure-sdk-python/skills/*/SKILL.md 都已更新，或明确确认仍为最新版本。
• -py 技能的 Harness 模拟运行通过，且没有回归问题。
• azure-sdk-python 的技能链接保持同步。
• PR 说明包含所用的上游文档、签名修正和验证结果。

---

渐进式披露模式

模式 1：高级指南与参考资料

# SDK Name

## Quick Start

[Minimal example]

## Advanced Features

- **Streaming**: See [references/streaming.md](references/streaming.md)
- **Tools**: See [references/tools.md](references/tools.md)

模式 2：语言变体

azure-service-skill/
├── SKILL.md (overview + language selection)
└── references/
    ├── python.md
    ├── dotnet.md
    ├── go.md
    ├── java.md
    └── typescript.md

模式 3：功能组织

azure-ai-agents/
├── SKILL.md (core workflow)
└── references/
    ├── tools.md
    ├── streaming.md
    ├── async-patterns.md
    └── error-handling.md

---

设计模式参考

参考资料	内容
references/workflows.md	顺序和条件工作流
references/output-patterns.md	模板和示例
references/azure-sdk-patterns.md	特定语言的 Azure SDK 模式

反模式

不要	原因
在没有 SDK 上下文的情况下创建技能	用户必须提供包名或文档 URL
在正文中写入“适用场景”	正文会在触发后才加载
将凭据硬编码	存在安全风险
跳过身份验证部分	Agent 会自行摸索，效果不佳
使用过时的 SDK 模式	API 会变化；请先搜索文档
包含 README.md	Agent 不需要元文档
将引用嵌套得过深	保持一层嵌套
跳过验收标准	没有测试的技能无法验证
跳过符号链接分类	技能无法按类别被发现
使用错误的导入路径	Azure SDK 有特定的模块结构
在 Python 技能的最佳实践中省略同步/异步和上下文管理器要点	终端用户不会遵循没有明确写下的规则；仅有示例还不够
在同一个 Python 示例中混用同步和异步	这恰好展示了该技能旨在防止的反模式
发布重新生成但没有任何测试场景的技能	无法验证核心工作流和回归问题
根据单个顺利路径示例声称覆盖完整 API	掩盖用户在生产环境中需要了解的操作组和非核心场景缺口
对非核心功能省略 references/*.md 覆盖	高级功能无法在上下文中使用，API 覆盖范围也缺乏文档记录

---

检查清单

完成一项技能前：

前置条件：

• 用户提供了 SDK 包名称或文档 URL
• 已通过 microsoft-docs MCP 核实 SDK 用法模式
• 已根据该 SDK 当前官方的特定语言 API 参考文档核实每个代码片段的 API 接口（如有 Microsoft Learn 文档则使用，否则使用上游 SDK 仓库；参见上文的权威来源）

技能创建：

• 描述包含内容和适用时机（触发短语）
• SKILL.md 不超过 500 行
• 身份验证遵循语言规则（Python/.NET/Java/TS/Go 本地开发使用 DefaultAzureCredential；Rust 本地开发使用 DeveloperToolsCredential，生产环境使用 ManagedIdentityCredential）
• 示例中包含清理/删除操作
• 参考资料按功能组织（capabilities.md 索引 + 专门的深入介绍文件）
• 代码片段和测试明确涵盖该 SDK 当前权威文档/示例中的主要场景
• 如果 SDK 支持不同的非主要场景，至少包含一个有价值的非主要场景（否则注明不适用不同的非主要场景）
• 对于 Azure SDK 技能，references/capabilities.md 索引主要/非主要场景的覆盖情况，并链接到专门的非主要场景文档
• 对于 Azure SDK 技能，references/non-hero-scenarios.md 包含与主要场景代码片段不同的具体非主要场景示例
• 对于广泛的 SDK（尤其是管理 SDK），明确说明操作组的覆盖情况（代码片段中已覆盖还是仅供参考）
• （仅限 Python 技能）最佳实践部分包含两条面向用户的规则（保持同步或异步一致 + 对客户端和异步凭据使用上下文管理器），并采用与技能类型匹配的版本
• 对于 Rust 技能：## Best Practices 以 cargo 依赖规则 + azure_core 直接导入规则开头

分类：

• 技能创建于 .github/skills/<skill-name>/
• 在 skills/<language>/<category>/<short-name> 创建符号链接
• 符号链接指向 ../../../.github/skills/<skill-name>

测试：

• 创建 tests/scenarios/<skill-name>/acceptance-criteria.md，包含正确/错误模式
• 创建 tests/scenarios/<skill-name>/scenarios.yaml
• 至少有一个主要场景和一个非主要场景通过测试覆盖（当 SDK 同时支持两者时）
• 所有场景均通过（pnpm harness <skill> --mock）
• 精确记录导入路径

文档：

• 更新 README.md 技能目录
• 指示用户通过 microsoft-docs MCP 搜索当前 API