skill-creator

name	skill-creator
description	Create effective skills for AI agents — Azure SDK patterns, progressive disclosure, acceptance criteria, test scenarios
tier	standard
applyTo	**/*skill*,**/*SKILL*,**/skills/**

Skill Creator

Guide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and external APIs

Related: See skill-building for Alex-specific skill creation workflow and promotion to Master Alex.

---

Core Principles

1. Concise is Key

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.

2. Fresh Documentation First

Azure SDKs change constantly. Skills should instruct agents to verify documentation:

## Before Implementation

Search `microsoft-docs` MCP for current API patterns:
- Query: "[SDK name] [operation] python"
- Verify: Parameters match your installed SDK version

3. Degrees of Freedom

Match specificity to task fragility:

Freedom	When	Example
High	Multiple valid approaches	Text guidelines
Medium	Preferred pattern with variation	Pseudocode
Low	Must be exact	Specific scripts

4. Progressive Disclosure

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.

---

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)

Bundled Resources

Type	Purpose	When to Include
scripts/	Deterministic operations	Same code rewritten repeatedly
references/	Detailed patterns	API docs, schemas, detailed guides
assets/	Output resources	Templates, images, boilerplate

Don't include: README.md, CHANGELOG.md, installation guides.

---

Creating Azure SDK Skills

Section Order

Follow this structure for 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

Authentication Pattern (All Languages)

Always use 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);

Never hardcode credentials. Use environment variables.

Standard Verb Patterns

Azure SDKs use consistent verbs across all languages:

Verb	Behavior
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

Language-Specific Patterns

Language	Pagination	Long-Running Ops	Async
Python	ItemPaged	LROPoller	aio submodule
.NET	Pageable<T>	Operation<T>	Async suffix
Java	PagedIterable	SyncPoller	PagedFlux (reactive)
TypeScript	PagedAsyncIterableIterator	poller.pollUntilDone()	Native async/await

---

Example: Azure SDK Skill

---
name: azure-ai-example-py
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
\`\`\`

## 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
)
\`\`\`

## Core Workflow

\`\`\`python
# 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/tools.md](references/tools.md) | Tool integrations |
| [references/streaming.md](references/streaming.md) | Event streaming patterns |

---

Creating Test Scenarios

Acceptance Criteria

Location: references/acceptance-criteria.md

# 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
\`\`\`python
credential = DefaultAzureCredential()
client = MyClient(endpoint, credential)
\`\`\`

#### ❌ INCORRECT: Hardcoded Credentials
\`\`\`python
client = MyClient(endpoint, api_key="hardcoded")  # Security risk
\`\`\`

Test Scenarios

Location: 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"
    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)

---

Progressive Disclosure Patterns

Pattern 1: High-Level Guide with References

# SDK Name

## Quick Start
[Minimal example]

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

Pattern 2: Language Variants

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

Pattern 3: Feature Organization

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

---

Anti-Patterns

Don't	Why
Create skill without SDK context	Users must provide package name/docs URL
Put "when to use" in body	Body loads AFTER triggering
Hardcode credentials	Security risk
Skip authentication section	Agents will improvise poorly
Use outdated SDK patterns	APIs change; search docs first
Include README.md	Agents don't need meta-docs
Deeply nest references	Keep one level deep
Skip acceptance criteria	Skills without tests can't be validated
Use wrong import paths	Azure SDKs have specific module structures

---

Checklist

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

Testing

• references/acceptance-criteria.md created with correct/incorrect patterns
• All scenarios pass
• Import paths documented precisely

Documentation

• Instructs to search microsoft-docs MCP for current APIs

---

Synapse Connection

This skill complements:

• skill-building — Alex-specific skill creation and promotion workflow
• azure-architecture-patterns — When creating Azure-focused skills
• testing-strategies — For comprehensive skill testing

---

References

• Microsoft Skills Repository
• Azure SDK Design Guidelines
• Azure Identity Library