skill-creator-ms

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.

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

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)

SKILL.md

• Frontmatter: name and description. The description is the trigger mechanism.
• Body: Instructions loaded only after triggering.

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

When creating skills for Azure SDKs, follow these patterns consistently.

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

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

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

Example: Azure SDK Skill Structure

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

## 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 | Tool integrations |
| references/streaming.md | Event 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

Step 1: Gather SDK Context (REQUIRED)

Before creating any SDK skill, the user MUST provide:

| Required | Example | Purpose | |----------|---------|---------| | 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:

# Use microsoft-docs MCP to get current API patterns
# Query: "[SDK name] [operation] [language]"
# Verify: Parameters match the latest SDK version

Step 2: Understand the Skill

Gather concrete examples:

• "What SDK operations should this skill cover?"
• "What triggers should activate this skill?"
• "What errors do developers commonly encounter?"

| Example Task | Reusable Resource | |--------------|-------------------| | Same auth code each time | Code example in SKILL.md | | Complex streaming patterns | references/streaming.md | | Tool configurations | references/tools.md | | Error handling patterns | `r