
关于
为使用 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