关于
为使用 Azure SDK 和 Microsoft Foundry 服务的 AI 编码代理创建有效技能的指南。适用于创建新技能或更新现有技能。
name: skill-creator-ms description: "为使用 Azure SDK 和 Microsoft Foundry 服务的 AI 编码代理创建有效技能的指南。在创建新技能或更新现有技能时使用。" risk: unknown source: community date_added: "2026-02-27"
技能创建器
为扩展 AI 代理能力创建技能的指南，重点关注 Azure SDK 和 Microsoft Foundry。
必需上下文： 创建 SDK 或 API 技能时，用户必须提供技能所基于的 SDK 包名称、文档 URL 或仓库引用。
关于技能
技能是模块化知识包，将通用代理转变为专业专家：
- 程序性知识 — 特定领域的多步骤工作流
- SDK 专业知识 — Azure 服务的 API 模式、认证、错误处理
- 领域上下文 — 模式、业务逻辑、公司特定模式
- 捆绑资源 — 复杂任务的脚本、参考、模板
核心原则
1. 简洁是关键
上下文窗口是共享资源。质疑每一条内容："这值得它的 token 成本吗？"
默认假设：代理已经很有能力。 只添加它们不知道的内容。
2. 优先使用最新文档
Azure SDK 不断变化。 技能应指导代理验证文档：
## 实施前
在 `microsoft-docs` MCP 中搜索当前 API 模式：
- 查询："[SDK 名称] [操作] python"
- 验证：参数与已安装的 SDK 版本匹配
3. 自由度
将具体性与任务脆弱性匹配：
| 自由度 | 何时 | 示例 | |---------|------|---------| | 高 | 多种有效方法 | 文本指南 | | 中 | 有变化的首选模式 | 伪代码 | | 低 | 必须精确 | 具体脚本 |
4. 渐进式披露
技能分三个层级加载：
- 元数据（约 100 词）— 始终在上下文中
- SKILL.md 正文（<5k 词）— 技能触发时
- 参考资料（无限制）— 按需
保持 SKILL.md 在 500 行以内。 接近此限制时拆分为参考文件。
技能结构
skill-name/
├── SKILL.md（必需）
│ ├── YAML frontmatter（name、description）
│ └── Markdown 说明
└── 捆绑资源（可选）
├── scripts/ — 可执行代码
├── references/ — 按需加载的文档
└── assets/ — 输出资源（模板、图片）
SKILL.md
- Frontmatter：
name和description。description 是触发机制。 - 正文：仅在触发后加载的说明。
捆绑资源
| 类型 | 用途 | 何时包含 |
|------|---------|-----------------|
| scripts/ | 确定性操作 | 相同代码反复重写时 |
| references/ | 详细模式 | API 文档、模式、详细指南 |
| assets/ | 输出资源 | 模板、图片、样板 |
不要包含：README.md、CHANGELOG.md、安装指南。
创建 Azure SDK 技能
创建 Azure SDK 技能时，始终遵循这些模式。
技能章节顺序
遵循此结构（基于现有 Azure SDK 技能）：
- 标题 —
# SDK 名称 - 安装 —
pip install、npm install等 - 环境变量 — 必需配置
- 认证 — 始终使用
DefaultAzureCredential - 核心工作流 — 最小可行示例
- 功能表 — 客户端、方法、工具
- 最佳实践 — 编号列表
- 参考链接 — 链接到
/references/*.md的表格
认证模式（所有语言）
始终使用 DefaultAzureCredential：
# Python
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
client = ServiceClient(endpoint, credential)
// C#
var credential = new DefaultAzureCredential();
var client = new ServiceClient(new Uri(endpoint), credential);
// Java
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
ServiceClient client = new ServiceClientBuilder()
.endpoint(endpoint)
.credential(credential)
.buildClient();
// TypeScript
import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();
const client = new ServiceClient(endpoint, credential);
永远不要硬编码凭据。使用环境变量。
标准动词模式
Azure SDK 在所有语言中使用一致的动词：
| 动词 | 行为 |
|------|----------|
| create | 创建新的；如果存在则失败 |
| upsert | 创建或更新 |
| get | 检索；如果缺失则报错 |
| list | 返回集合 |
| delete | 即使缺失也成功 |
| begin | 启动长时间运行的操作 |
语言特定模式
参见 references/azure-sdk-patterns.md 了解详细模式，包括：
- Python：
ItemPaged、LROPoller、上下文管理器、Sphinx 文档字符串 - .NET：
Response<T>、AsyncPageable、XML 文档注释 - Java：
PagedIterable、SyncPoller、Javadoc - TypeScript：
PagedAsyncIterableIterator、PollerLike