Back to Details

skill-creator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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 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
技能是模块化的知识包，可将通用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.
上下文窗口是共享资源。对每一部分都要提出质疑：“它是否值得占用令牌成本？”
默认假设：Agent已具备基础能力。 仅添加它们不知道的内容。

2. Fresh Documentation First

2. 优先使用最新文档

Azure SDKs change constantly. Skills should instruct agents to verify documentation:
markdown
undefined
Azure SDK会持续更新。 技能应指导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.
技能分为三个层级加载：
  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 (必填)
│   ├── YAML前置元数据 (name, description)
│   └── Markdown说明
└── 捆绑资源 (可选)
    ├── scripts/      — 可执行代码
    ├── references/   — 按需加载的文档
    └── assets/       — 输出资源（模板、图片）

SKILL.md

SKILL.md

  • Frontmatter: 
    name
    and 
    description
    . The description is the trigger mechanism.
  • Body: Instructions loaded only after triggering.
  • 前置元数据：
    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技能

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

安装

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

Environment Variables

环境变量

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

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

核心工作流

```python
```python

Create

创建

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

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

长时间运行的操作

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

Cleanup

清理

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

Reference Files

参考文件

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

---
文件内容
references/tools.md工具集成
references/streaming.md事件流模式

---

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模式
  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/
目录中按语言和产品领域组织。
产品领域分类：
分类描述示例
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、Query
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。
前置元数据：
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>/<short-name> -> ../../../.github/skills/<full-skill-name>

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>

验收标准: <skill-name>

SDK: 
package-name
Repository: https://github.com/Azure/azure-sdk-for-<language> Purpose: Skill testing acceptance criteria
SDK: 
package-name
仓库: https://github.com/Azure/azure-sdk-for-<language> 用途: 技能测试验收标准

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 # 错误 - 客户端不在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") # 安全风险 ```

**需要记录的关键模式：**
- 导入路径（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 ~75: 
      > N skills in...
      )
    • 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 table (line ~590: 
      **N skills with N test scenarios**
      )
  2. Update docs/index.html — Add the skill to the GitHub Pages site
    • Update badge count: 
      <span class="badge-count">N</span> Skills
      (line ~717)
    • Update tab count: 
      All <span class="tab-count">N</span>
      (line ~806)
    • Add skill entry in the JavaScript 
      skills
      array (around line ~1060-1300)
    Skill entry format:
    javascript
    {
    name: "skill-name-py",
    lang: "py",
    desc: "Short description — key features",
},
    Placement: Add in the appropriate language/category section (skills are grouped by language, then roughly by category in the array).
  3. Verify AGENTS.md — Ensure the skill count is accurate
创建技能后：
  1. 更新README.md — 在技能目录的相应语言部分添加该技能
    • 更新技能总数（约第75行：
      > N skills in...
      ）
    • 更新语言数量表格（约第77-83行）
    • 更新语言部分数量（例如：
      > N skills • suffix: -py
      ）
    • 更新分类数量（例如：
      <summary><strong>Foundry & AI</strong> (N skills)</summary>
      ）
    • 在分类中按字母顺序添加技能行
    • 更新测试覆盖率表格（约第590行：
      **N skills with N test scenarios**
      ）
  2. 更新docs/index.html — 将技能添加到GitHub Pages站点
    • 更新徽章数量：
      <span class="badge-count">N</span> Skills
      （约第717行）
    • 更新标签页数量：
      All <span class="tab-count">N</span>
      （约第806行）
    • 在JavaScript的
      skills
      数组中添加技能条目（约第1060-1300行）
    技能条目格式：
    javascript
    {
    name: "skill-name-py",
    lang: "py",
    desc: "Short description — key features",
},
    位置： 添加到相应的语言/分类部分（数组中技能按语言分组，然后大致按分类排序）。
  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>/<short-name>
    中创建了符号链接
  • 符号链接指向
    ../../../.github/skills/<skill-name>
测试：
  • 创建了
    references/acceptance-criteria.md
    ，包含正确/错误模式
  • 创建了
    tests/scenarios/<skill-name>/scenarios.yaml
  • 所有场景通过（
    pnpm harness <skill> --mock
    ）
  • 精确记录了导入路径
文档：
  • 更新了README.md技能目录
  • 指导使用
    microsoft-docs
    MCP搜索当前API