Back to Details

skill-creator-ms

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Creator

Skill Creator 技能创建指南

Guide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and Microsoft Foundry.
Required Context: When creating SDK or API skills, users MUST provide the SDK package name, documentation URL, or repository reference for the skill to be based on.
本指南用于创建可扩展AI Agent能力的技能，重点针对Azure SDK和Microsoft Foundry服务。
必填上下文： 创建SDK或API技能时，用户必须提供SDK包名称、文档URL或仓库引用作为技能的基础依据。

About Skills

关于Skills（技能）

Skills are modular knowledge packages that transform general-purpose agents into specialized experts:
  1. Procedural knowledge — Multi-step workflows for specific domains
  2. SDK expertise — API patterns, authentication, error handling for Azure services
  3. Domain context — Schemas, business logic, company-specific patterns
  4. Bundled resources — Scripts, references, templates for complex tasks
Skills是模块化知识包，可将通用Agent转变为领域专家：
  1. 过程知识 — 特定领域的多步骤工作流
  2. SDK专业知识 — Azure服务的API模式、身份验证、错误处理
  3. 领域上下文 — 架构、业务逻辑、企业特定模式
  4. 捆绑资源 — 用于复杂任务的脚本、参考资料、模板

Core Principles

核心原则

1. Concise is Key

1. 简洁为要

The context window is a shared resource. Challenge each piece: "Does this justify its token cost?"
Default assumption: Agents are already capable. Only add what they don't already know.
上下文窗口是共享资源。对每一部分都要质疑：“它是否值得占用token成本？”
默认假设：Agent已具备基础能力。 仅添加Agent尚不了解的内容。

2. Fresh Documentation First

2. 优先使用最新文档

Azure SDKs change constantly. Skills should instruct agents to verify documentation:
markdown
undefined
Azure SDKs会持续更新。 Skills应指导Agent验证文档：
markdown
undefined

Before Implementation

实现前准备

Search 
microsoft-docs
MCP for current API patterns:
  • Query: "[SDK name] [operation] python"
  • Verify: Parameters match your installed SDK version
undefined
在
microsoft-docs
MCP中搜索当前API模式：
  • 查询语句："[SDK名称] [操作] python"
  • 验证：参数与你安装的SDK版本匹配
undefined

3. Degrees of Freedom

3. 自由度分级

Match specificity to task fragility:
FreedomWhenExample
HighMultiple valid approachesText guidelines
MediumPreferred pattern with variationPseudocode
LowMust be exactSpecific scripts
根据任务的脆弱性匹配具体程度：
自由度适用场景示例
高存在多种有效实现方式文本指南
中有首选模式但允许变体伪代码
低必须严格执行特定脚本

4. Progressive Disclosure

4. 渐进式披露

Skills load in three levels:
  1. Metadata (~100 words) — Always in context
  2. SKILL.md body (<5k words) — When skill triggers
  3. References (unlimited) — As needed
Keep SKILL.md under 500 lines. Split into reference files when approaching this limit.
Skills分为三个加载层级：
  1. 元数据（约100词）— 始终处于上下文环境中
  2. SKILL.md主体（<5000词）— 触发技能时加载
  3. 参考资料（无限制）— 按需加载
保持SKILL.md在500行以内。 接近该限制时，拆分到参考文件中。

Skill Structure

技能结构

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)
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      — 可执行代码
    ├── references/   — 按需加载的文档
    └── assets/       — 输出资源（模板、图片）

SKILL.md

SKILL.md

  • Frontmatter: 
    name
    and 
    description
    . The description is the trigger mechanism.
  • Body: Instructions loaded only after triggering.
  • Frontmatter：包含
    name
    和
    description
    。描述内容是技能的触发机制。
  • 主体：仅在技能触发时加载的说明内容。

Bundled Resources

捆绑资源

TypePurposeWhen to Include
scripts/
Deterministic operationsSame code rewritten repeatedly
references/
Detailed patternsAPI docs, schemas, detailed guides
assets/
Output resourcesTemplates, images, boilerplate
Don't include: README.md, CHANGELOG.md, installation guides.
类型用途适用场景
scripts/
确定性操作需重复编写的相同代码
references/
详细模式说明API文档、架构、详细指南
assets/
输出资源模板、图片、样板代码
请勿包含：README.md、CHANGELOG.md、安装指南。

Creating Azure SDK Skills

创建Azure SDK Skills

When creating skills for Azure SDKs, follow these patterns consistently.
创建Azure SDK相关技能时，请始终遵循以下模式。

Skill Section Order

技能章节顺序

Follow this structure (based on existing Azure SDK skills):
  1. Title — 
    # SDK Name
  2. Installation — 
    pip install
    , 
    npm install
    , etc.
  3. Environment Variables — Required configuration
  4. Authentication — Always 
    DefaultAzureCredential
  5. Core Workflow — Minimal viable example
  6. Feature Tables — Clients, methods, tools
  7. Best Practices — Numbered list
  8. Reference Links — Table linking to 
    /references/*.md
遵循以下结构（基于现有Azure SDK技能）：
  1. 标题 — 
    # SDK名称
  2. 安装 — 
    pip install
    、
    npm install
    等命令
  3. 环境变量 — 必填配置
  4. 身份验证 — 始终使用
    DefaultAzureCredential
  5. 核心工作流 — 最简可行示例
  6. 功能表格 — 客户端、方法、工具
  7. 最佳实践 — 编号列表
  8. 参考链接 — 指向
    /references/*.md
    的表格

Authentication Pattern (All Languages)

身份验证模式（全语言通用）

Always use 
DefaultAzureCredential
:
python
undefined
始终使用
DefaultAzureCredential
：
python
undefined

Python

Python

from azure.identity import DefaultAzureCredential credential = DefaultAzureCredential() client = ServiceClient(endpoint, credential)

```csharp
// C#
var credential = new DefaultAzureCredential();
var client = new ServiceClient(new Uri(endpoint), credential);
java
// Java
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
ServiceClient client = new ServiceClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();
typescript
// TypeScript
import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();
const client = new ServiceClient(endpoint, credential);
Never hardcode credentials. Use environment variables.
from azure.identity import DefaultAzureCredential credential = DefaultAzureCredential() client = ServiceClient(endpoint, credential)

```csharp
// C#
var credential = new DefaultAzureCredential();
var client = new ServiceClient(new Uri(endpoint), credential);
java
// Java
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
ServiceClient client = new ServiceClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();
typescript
// TypeScript
import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();
const client = new ServiceClient(endpoint, credential);
绝对不要硬编码凭据。请使用环境变量。

Standard Verb Patterns

标准动词模式

Azure SDKs use consistent verbs across all languages:
VerbBehavior
create
Create new; fail if exists
upsert
Create or update
get
Retrieve; error if missing
list
Return collection
delete
Succeed even if missing
begin
Start long-running operation
Azure SDK在所有语言中使用一致的动词：
动词行为
create
创建新资源；已存在则失败
upsert
创建或更新资源
get
检索资源；不存在则报错
list
返回资源集合
delete
删除资源；不存在仍返回成功
begin
启动长时间运行的操作

Language-Specific Patterns

语言特定模式

See 
references/azure-sdk-patterns.md
for detailed patterns including:
  • Python: 
    ItemPaged
    , 
    LROPoller
    , context managers, Sphinx docstrings
  • .NET: 
    Response<T>
    , 
    Pageable<T>
    , 
    Operation<T>
    , mocking support
  • Java: Builder pattern, 
    PagedIterable
    /
    PagedFlux
    , Reactor types
  • TypeScript: 
    PagedAsyncIterableIterator
    , 
    AbortSignal
    , browser considerations
查看
references/azure-sdk-patterns.md
获取详细模式，包括：
  • Python：
    ItemPaged
    、
    LROPoller
    、上下文管理器、Sphinx文档字符串
  • .NET：
    Response<T>
    、
    Pageable<T>
    、
    Operation<T>
    、模拟支持
  • Java：构建器模式、
    PagedIterable
    /
    PagedFlux
    、Reactor类型
  • TypeScript：
    PagedAsyncIterableIterator
    、
    AbortSignal
    、浏览器适配考虑

Example: Azure SDK Skill Structure

示例：Azure SDK技能结构

markdown
---
name: skill-creator
description: |
  Azure AI Example SDK for Python. Use for [specific service features].
  Triggers: "example service", "create example", "list examples".
---
markdown
---
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

Azure AI Example SDK

Installation

Installation

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

Environment Variables

Environment Variables

```bash AZURE_EXAMPLE_ENDPOINT=https://<resource>.example.azure.com ```
```bash AZURE_EXAMPLE_ENDPOINT=https://<resource>.example.azure.com ```

Authentication

Authentication

```python from azure.identity import DefaultAzureCredential from azure.ai.example import ExampleClient
credential = DefaultAzureCredential() client = ExampleClient( endpoint=os.environ["AZURE_EXAMPLE_ENDPOINT"], credential=credential ) ```
```python from azure.identity import DefaultAzureCredential from azure.ai.example import ExampleClient
credential = DefaultAzureCredential() client = ExampleClient( endpoint=os.environ["AZURE_EXAMPLE_ENDPOINT"], credential=credential ) ```

Core Workflow

Core Workflow

```python
```python

Create

Create

item = client.create_item(name="example", data={...})
item = client.create_item(name="example", data={...})

List (pagination handled automatically)

List (pagination handled automatically)

for item in client.list_items(): print(item.name)
for item in client.list_items(): print(item.name)

Long-running operation

Long-running operation

poller = client.begin_process(item_id) result = poller.result()
poller = client.begin_process(item_id) result = poller.result()

Cleanup

Cleanup

client.delete_item(item_id) ```
client.delete_item(item_id) ```

Reference Files

Reference Files

FileContents
references/tools.mdTool integrations
references/streaming.mdEvent streaming patterns

---
FileContents
references/tools.mdTool integrations
references/streaming.mdEvent streaming patterns

---

Skill Creation Process

技能创建流程

  1. Gather SDK Context — User provides SDK/API reference (REQUIRED)
  2. Understand — Research SDK patterns from official docs
  3. Plan — Identify reusable resources and product area category
  4. Create — Write SKILL.md in 
    .github/skills/<skill-name>/
  5. Categorize — Create symlink in 
    skills/<language>/<category>/
  6. Test — Create acceptance criteria and test scenarios
  7. Document — Update README.md skill catalog
  8. Iterate — Refine based on real usage
  1. 收集SDK上下文 — 用户提供SDK/API参考（必填）
  2. 理解SDK — 从官方文档研究SDK模式
  3. 规划 — 确定可复用资源和产品领域分类
  4. 创建 — 在
    .github/skills/<skill-name>/
    路径下编写SKILL.md
  5. 分类 — 在
    skills/<language>/<category>/
    创建符号链接
  6. 测试 — 创建验收标准和测试场景
  7. 文档更新 — 更新README.md技能目录
  8. 迭代 — 根据实际使用情况优化

Step 1: Gather SDK Context (REQUIRED)

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

Before creating any SDK skill, the user MUST provide:
RequiredExamplePurpose
SDK Package
azure-ai-agents
, 
Azure.AI.OpenAI
Identifies the exact SDK
Documentation URL
https://learn.microsoft.com/en-us/azure/ai-services/...
Primary source of truth
Repository (optional)
Azure/azure-sdk-for-python
For code patterns
Prompt the user if not provided:
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)
Search official docs first:
bash
undefined
创建任何SDK技能前，用户必须提供：
必填项示例用途
SDK包
azure-ai-agents
, 
Azure.AI.OpenAI
明确具体的SDK
文档URL
https://learn.microsoft.com/en-us/azure/ai-services/...
主要事实来源
仓库（可选）
Azure/azure-sdk-for-python
用于参考代码模式
若未提供，提示用户：
创建此技能需要以下信息：
1. SDK包名称（例如：azure-ai-projects）
2. Microsoft Learn文档URL或GitHub仓库
3. 目标语言（py/dotnet/ts/java）
优先搜索官方文档：
bash
undefined

Use microsoft-docs MCP to get current API patterns

使用microsoft-docs MCP获取当前API模式

Query: "[SDK name] [operation] [language]"

查询语句："[SDK名称] [操作] [语言]"

Verify: Parameters match the latest SDK version

验证：参数与最新SDK版本匹配

undefined
undefined

Step 2: Understand the Skill

步骤2：理解技能需求

Gather concrete examples:
  • "What SDK operations should this skill cover?"
  • "What triggers should activate this skill?"
  • "What errors do developers commonly encounter?"
Example TaskReusable Resource
Same auth code each timeCode example in SKILL.md
Complex streaming patterns
references/streaming.md
Tool configurations
references/tools.md
Error handling patterns
references/error-handling.md
收集具体示例：
  • "此技能应覆盖哪些SDK操作？"
  • "哪些触发词应激活此技能？"
  • "开发人员通常会遇到哪些错误？"
示例任务可复用资源
重复使用相同的身份验证代码SKILL.md中的代码示例
复杂的流处理模式
references/streaming.md
工具配置
references/tools.md
错误处理模式
references/error-handling.md

Step 3: Plan Product Area Category

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

Skills are organized by language and product area in the 
skills/
directory via symlinks.
Product Area Categories:
CategoryDescriptionExamples
foundry
AI Foundry, agents, projects, inference
azure-ai-agents-py
, 
azure-ai-projects-py
data
Storage, Cosmos DB, Tables, 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, Query
azure-monitor-opentelemetry-py
identity
Authentication, DefaultAzureCredential
azure-identity-py
security
Key Vault, secrets, keys, certificates
azure-keyvault-py
integration
API Management, App Configuration
azure-appconfiguration-py
compute
Batch, ML compute
azure-compute-batch-java
container
Container Registry, ACR
azure-containerregistry-py
Determine the category based on:
  1. Azure service family (Storage → 
    data
    , Event Hubs → 
    messaging
    )
  2. Primary use case (AI agents → 
    foundry
    )
  3. Existing skills in the same service area
Skills通过符号链接按语言和产品领域组织在
skills/
目录中。
产品领域分类：
分类描述示例
foundry
AI Foundry、Agent、项目、推理
azure-ai-agents-py
, 
azure-ai-projects-py
data
存储、Cosmos DB、Tables、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服务家族（存储→
    data
    ，Event Hubs→
    messaging
    ）
  2. 主要使用场景（AI Agent→
    foundry
    ）
  3. 同一服务领域的现有技能

Step 4: Create the Skill

步骤4：创建技能

Location: 
.github/skills/<skill-name>/SKILL.md
Naming convention:
  • azure-<service>-<subservice>-<language>
  • Examples: 
    azure-ai-agents-py
    , 
    azure-cosmos-java
    , 
    azure-storage-blob-ts
For Azure SDK skills:
  1. Search 
    microsoft-docs
    MCP for current API patterns
  2. Verify against installed SDK version
  3. Follow the section order above
  4. Include cleanup code in examples
  5. Add feature comparison tables
Write bundled resources first, then SKILL.md.
Frontmatter:
yaml
---
name: skill-name-py
description: |
  Azure Service SDK for Python. Use for [specific features].
  Triggers: "service name", "create resource", "specific operation".
---
路径： 
.github/skills/<skill-name>/SKILL.md
命名规范：
  • azure-<service>-<subservice>-<language>
  • 示例：
    azure-ai-agents-py
    , 
    azure-cosmos-java
    , 
    azure-storage-blob-ts
针对Azure SDK技能：
  1. 在
    microsoft-docs
    MCP中搜索当前API模式
  2. 与已安装的SDK版本进行验证
  3. 遵循上述章节顺序
  4. 示例中包含清理代码
  5. 添加功能对比表格
先编写捆绑资源，再编写SKILL.md。
Frontmatter示例：
yaml
---
name: skill-name-py
description: |
  Azure Service SDK for Python. Use for [specific features].
  Triggers: "service name", "create resource", "specific operation".
---

Step 5: Categorize with Symlinks

步骤5：通过符号链接分类

After creating the skill in 
.github/skills/
, create a symlink in the appropriate category:
bash
undefined
在
.github/skills/
中创建技能后，在对应分类下创建符号链接：
bash
undefined

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

格式：skills/<language>/<category>/<简称> -> ../../../.github/skills/<完整技能名称>

Example for azure-ai-agents-py in python/foundry:

示例：azure-ai-agents-py在python/foundry分类下

cd skills/python/foundry ln -s ../../../.github/skills/azure-ai-agents-py agents
cd skills/python/foundry ln -s ../../../.github/skills/azure-ai-agents-py agents

Example for azure-cosmos-db-py in python/data:

示例：azure-cosmos-db-py在python/data分类下

cd skills/python/data ln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db

**Symlink naming:**
- Use short, descriptive names (e.g., `agents`, `cosmos`, `blob`)
- Remove the `azure-` prefix and language suffix
- Match existing patterns in the category

**Verify the symlink:**
```bash
ls -la skills/python/foundry/agents
cd skills/python/data ln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db

**符号链接命名规范：**
- 使用简短、描述性名称（例如：`agents`, `cosmos`, `blob`）
- 移除`azure-`前缀和语言后缀
- 与分类中的现有模式保持一致

**验证符号链接：**
```bash
ls -la skills/python/foundry/agents

Should show: agents -> ../../../.github/skills/azure-ai-agents-py

应显示：agents -> ../../../.github/skills/azure-ai-agents-py

undefined
undefined

Step 6: Create Tests

步骤6：创建测试

Every skill MUST have acceptance criteria and test scenarios.
每个技能必须包含验收标准和测试场景。

6.1 Create Acceptance Criteria

6.1 创建验收标准

Location: 
.github/skills/<skill-name>/references/acceptance-criteria.md
Source materials (in priority order):
  1. Official Microsoft Learn docs (via 
    microsoft-docs
    MCP)
  2. SDK source code from the repository
  3. Existing reference files in the skill
Format:
markdown
undefined
路径： 
.github/skills/<skill-name>/references/acceptance-criteria.md
参考资料优先级：
  1. 官方Microsoft Learn文档（通过
    microsoft-docs
    MCP）
  2. 仓库中的SDK源代码
  3. 技能中的现有参考文件
格式示例：
markdown
undefined

Acceptance Criteria: <skill-name>

验收标准：<技能名称>

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

1. Correct Import Patterns

1. 正确的导入模式

1.1 Client Imports

1.1 客户端导入

✅ CORRECT: Main Client

✅ 正确：主客户端

```python from azure.ai.mymodule import MyClient from azure.identity import DefaultAzureCredential ```
```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 ```
```python from azure.ai.mymodule.models import MyClient # Wrong - Client is not in models ```

2. Authentication Patterns

2. 身份验证模式

✅ CORRECT: DefaultAzureCredential

✅ 正确：DefaultAzureCredential

```python credential = DefaultAzureCredential() client = MyClient(endpoint, credential) ```
```python credential = DefaultAzureCredential() client = MyClient(endpoint, credential) ```

❌ INCORRECT: Hardcoded Credentials

❌ 错误：硬编码凭据

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

**Critical patterns to document:**
- Import paths (these vary significantly between Azure SDKs)
- Authentication patterns
- Client initialization
- Async variants (`.aio` modules)
- Common anti-patterns
```python client = MyClient(endpoint, api_key="hardcoded") # Security risk ```

**需记录的关键模式：**
- 导入路径（Azure SDK之间差异很大）
- 身份验证模式
- 客户端初始化
- 异步变体（`.aio`模块）
- 常见反模式

6.2 Create Test Scenarios

6.2 创建测试场景

Location: 
tests/scenarios/<skill-name>/scenarios.yaml
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"
    forbidden_patterns:
      - "api_key="
      - "hardcoded"
    tags:
      - basic
      - authentication
    mock_response: |
      import os
      from azure.identity import DefaultAzureCredential
      from azure.ai.mymodule import MyClient
      
      credential = DefaultAzureCredential()
      client = MyClient(
          endpoint=os.environ["AZURE_ENDPOINT"],
          credential=credential
      )
      # ... rest of working example
Scenario design principles:
  • Each scenario tests ONE specific pattern or feature
  • expected_patterns
    — patterns that MUST appear
  • forbidden_patterns
    — common mistakes that must NOT appear
  • mock_response
    — complete, working code that passes all checks
  • tags
    — for filtering (
    basic
    , 
    async
    , 
    streaming
    , 
    tools
    )
路径： 
tests/scenarios/<skill-name>/scenarios.yaml
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"
    forbidden_patterns:
      - "api_key="
      - "hardcoded"
    tags:
      - basic
      - authentication
    mock_response: |
      import os
      from azure.identity import DefaultAzureCredential
      from azure.ai.mymodule import MyClient
      
      credential = DefaultAzureCredential()
      client = MyClient(
          endpoint=os.environ["AZURE_ENDPOINT"],
          credential=credential
      )
      # ... rest of working example
场景设计原则：
  • 每个场景仅测试一个特定模式或功能
  • expected_patterns
    — 必须出现的模式
  • forbidden_patterns
    — 必须避免的常见错误
  • mock_response
    — 完整、可运行的通过代码
  • tags
    — 用于筛选（
    basic
    , 
    async
    , 
    streaming
    , 
    tools
    ）

6.3 Run Tests

6.3 运行测试

bash
cd tests
pnpm install
bash
cd tests
pnpm install

Check skill is discovered

检查技能是否被发现

pnpm harness --list
pnpm harness --list

Run in mock mode (fast, deterministic)

以模拟模式运行（快速、确定性）

pnpm harness <skill-name> --mock --verbose
pnpm harness <skill-name> --mock --verbose

Run with Ralph Loop (iterative improvement)

使用Ralph Loop运行（迭代优化）

pnpm harness <skill-name> --ralph --mock --max-iterations 5 --threshold 85

**Success criteria:**
- All scenarios pass (100% pass rate)
- No false positives (mock responses always pass)
- Patterns catch real mistakes
pnpm harness <skill-name> --ralph --mock --max-iterations 5 --threshold 85

**成功标准：**
- 所有场景通过（100%通过率）
- 无假阳性（模拟响应始终通过）
- 模式可捕获真实错误

Step 7: Update Documentation

步骤7：更新文档

After creating the skill:
  1. Update README.md — Add the skill to the appropriate language section in the Skill Catalog
    • Update total skill count (line ~73: 
      > N skills in...
      )
    • Update Skill Explorer link count (line ~15: 
      Browse all N skills
      )
    • Update language count table (lines ~77-83)
    • Update language section count (e.g., 
      > N skills • suffix: -py
      )
    • Update category count (e.g., 
      <summary><strong>Foundry & AI</strong> (N skills)</summary>
      )
    • Add skill row in alphabetical order within its category
    • Update test coverage summary (line ~622: 
      **N skills with N test scenarios**
      )
    • Update test coverage table — update skill count, scenario count, and top skills for the language
  2. Regenerate GitHub Pages data — Run the extraction script to update the docs site
    bash
    cd docs-site && npx tsx scripts/extract-skills.ts
    This updates 
    docs-site/src/data/skills.json
    which feeds the Astro-based docs site. Then rebuild the docs site:
    bash
    cd docs-site && npm run build
    This outputs to 
    docs/
    which is served by GitHub Pages.
  3. Verify AGENTS.md — Ensure the skill count is accurate
创建技能后：
  1. 更新README.md — 将技能添加到技能目录的对应语言章节中
    • 更新技能总数（约第73行：
      > N skills in...
      ）
    • 更新技能浏览器链接计数（约第15行：
      Browse all N skills
      ）
    • 更新语言计数表格（约第77-83行）
    • 更新语言章节计数（例如：
      > N skills • suffix: -py
      ）
    • 在对应分类中按字母顺序添加技能行
    • 更新测试覆盖率摘要（约第622行：
      **N skills with N test scenarios**
      ）
    • 更新测试覆盖率表格 — 更新对应语言的技能数量、场景数量和顶级技能
  2. 重新生成GitHub Pages数据 — 运行提取脚本更新文档站点
    bash
    cd docs-site && npx tsx scripts/extract-skills.ts
    此命令会更新
    docs-site/src/data/skills.json
    ，为基于Astro的文档站点提供数据。 然后重新构建文档站点：
    bash
    cd docs-site && npm run build
    输出到
    docs/
    目录，由GitHub Pages托管。
  3. 验证AGENTS.md — 确保技能计数准确

Progressive Disclosure Patterns

渐进式披露模式

Pattern 1: High-Level Guide with References

模式1：带参考的高级指南

markdown
undefined
markdown
undefined

SDK Name

SDK名称

Quick Start

快速开始

[Minimal example]
[最简示例]

Advanced Features

高级功能

  • Streaming: See references/streaming.md
  • Tools: See references/tools.md
undefined
  • 流处理：查看references/streaming.md
  • 工具：查看references/tools.md
undefined

Pattern 2: Language Variants

模式2：语言变体

azure-service-skill/
├── SKILL.md (overview + language selection)
└── references/
    ├── python.md
    ├── dotnet.md
    ├── java.md
    └── typescript.md
azure-service-skill/
├── SKILL.md (概述 + 语言选择)
└── references/
    ├── python.md
    ├── dotnet.md
    ├── java.md
    └── typescript.md

Pattern 3: Feature Organization

模式3：功能组织

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

Design Pattern References

设计模式参考

ReferenceContents
references/workflows.md
Sequential and conditional workflows
references/output-patterns.md
Templates and examples
references/azure-sdk-patterns.md
Language-specific Azure SDK patterns
参考文件内容
references/workflows.md
顺序和条件工作流
references/output-patterns.md
模板和示例
references/azure-sdk-patterns.md
语言特定的Azure SDK模式

Anti-Patterns

反模式

Don'tWhy
Create skill without SDK contextUsers must provide package name/docs URL
Put "when to use" in bodyBody loads AFTER triggering
Hardcode credentialsSecurity risk
Skip authentication sectionAgents will improvise poorly
Use outdated SDK patternsAPIs change; search docs first
Include README.mdAgents don't need meta-docs
Deeply nest referencesKeep one level deep
Skip acceptance criteriaSkills without tests can't be validated
Skip symlink categorizationSkills won't be discoverable by category
Use wrong import pathsAzure SDKs have specific module structures
禁止操作原因
无SDK上下文创建技能用户必须提供包名称/文档URL
将“何时使用”放在主体中主体仅在触发后加载
硬编码凭据存在安全风险
跳过身份验证章节Agent会自行编写糟糕的实现
使用过时的SDK模式API会更新；请先搜索文档
包含README.mdAgent不需要元文档
深层嵌套参考文件保持一级深度
跳过验收标准无测试的技能无法验证
跳过符号链接分类技能无法按分类被发现
使用错误的导入路径Azure SDK有特定的模块结构

Checklist

检查清单

Before completing a skill:
Prerequisites:
  • User provided SDK package name or documentation URL
  • Verified SDK patterns via 
    microsoft-docs
    MCP
Skill Creation:
  • Description includes what AND when (trigger phrases)
  • SKILL.md under 500 lines
  • Authentication uses 
    DefaultAzureCredential
  • Includes cleanup/delete in examples
  • References organized by feature
Categorization:
  • Skill created in 
    .github/skills/<skill-name>/
  • Symlink created in 
    skills/<language>/<category>/<short-name>
  • Symlink points to 
    ../../../.github/skills/<skill-name>
Testing:
  • references/acceptance-criteria.md
    created with correct/incorrect patterns
  • tests/scenarios/<skill-name>/scenarios.yaml
    created
  • All scenarios pass (
    pnpm harness <skill> --mock
    )
  • Import paths documented precisely
Documentation:
  • README.md skill catalog updated
  • Instructs to search 
    microsoft-docs
    MCP for current APIs
完成技能前，请确认：
前置条件：
  • 用户已提供SDK包名称或文档URL
  • 通过
    microsoft-docs
    MCP验证了SDK模式
技能创建：
  • 描述内容包含用途和触发短语
  • SKILL.md在500行以内
  • 身份验证使用
    DefaultAzureCredential
  • 示例中包含清理/删除代码
  • 参考资料按功能组织
分类：
  • 技能创建在
    .github/skills/<skill-name>/
    路径下
  • 在
    skills/<language>/<category>/<简称>
    创建了符号链接
  • 符号链接指向
    ../../../.github/skills/<skill-name>
测试：
  • 创建了
    references/acceptance-criteria.md
    ，包含正确/错误模式
  • 创建了
    tests/scenarios/<skill-name>/scenarios.yaml
  • 所有场景通过（
    pnpm harness <skill> --mock
    ）
  • 准确记录了导入路径
文档：
  • 更新了README.md技能目录
  • 指导Agent搜索
    microsoft-docs
    MCP获取当前API

When to Use

适用场景

This skill is applicable to execute the workflow or actions described in the overview.
本技能适用于执行概述中描述的工作流或操作。