Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.
Add this skill
npx mdskills install sickn33/skill-creator-msComprehensive meta-skill for creating Azure SDK skills with strong patterns and structure
1---2name: skill-creator3description: Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.4---56# Skill Creator78Guide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and Microsoft Foundry.910> **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.1112## About Skills1314Skills are modular knowledge packages that transform general-purpose agents into specialized experts:15161. **Procedural knowledge** — Multi-step workflows for specific domains172. **SDK expertise** — API patterns, authentication, error handling for Azure services183. **Domain context** — Schemas, business logic, company-specific patterns194. **Bundled resources** — Scripts, references, templates for complex tasks2021---2223## Core Principles2425### 1. Concise is Key2627The context window is a shared resource. Challenge each piece: "Does this justify its token cost?"2829**Default assumption: Agents are already capable.** Only add what they don't already know.3031### 2. Fresh Documentation First3233**Azure SDKs change constantly.** Skills should instruct agents to verify documentation:3435```markdown36## Before Implementation3738Search `microsoft-docs` MCP for current API patterns:39- Query: "[SDK name] [operation] python"40- Verify: Parameters match your installed SDK version41```4243### 3. Degrees of Freedom4445Match specificity to task fragility:4647| Freedom | When | Example |48|---------|------|---------|49| **High** | Multiple valid approaches | Text guidelines |50| **Medium** | Preferred pattern with variation | Pseudocode |51| **Low** | Must be exact | Specific scripts |5253### 4. Progressive Disclosure5455Skills load in three levels:56571. **Metadata** (~100 words) — Always in context582. **SKILL.md body** (<5k words) — When skill triggers593. **References** (unlimited) — As needed6061**Keep SKILL.md under 500 lines.** Split into reference files when approaching this limit.6263---6465## Skill Structure6667```68skill-name/69├── SKILL.md (required)70│ ├── YAML frontmatter (name, description)71│ └── Markdown instructions72└── Bundled Resources (optional)73 ├── scripts/ — Executable code74 ├── references/ — Documentation loaded as needed75 └── assets/ — Output resources (templates, images)76```7778### SKILL.md7980- **Frontmatter**: `name` and `description`. The description is the trigger mechanism.81- **Body**: Instructions loaded only after triggering.8283### Bundled Resources8485| Type | Purpose | When to Include |86|------|---------|-----------------|87| `scripts/` | Deterministic operations | Same code rewritten repeatedly |88| `references/` | Detailed patterns | API docs, schemas, detailed guides |89| `assets/` | Output resources | Templates, images, boilerplate |9091**Don't include**: README.md, CHANGELOG.md, installation guides.9293---9495## Creating Azure SDK Skills9697When creating skills for Azure SDKs, follow these patterns consistently.9899### Skill Section Order100101Follow this structure (based on existing Azure SDK skills):1021031. **Title** — `# SDK Name`1042. **Installation** — `pip install`, `npm install`, etc.1053. **Environment Variables** — Required configuration1064. **Authentication** — Always `DefaultAzureCredential`1075. **Core Workflow** — Minimal viable example1086. **Feature Tables** — Clients, methods, tools1097. **Best Practices** — Numbered list1108. **Reference Links** — Table linking to `/references/*.md`111112### Authentication Pattern (All Languages)113114Always use `DefaultAzureCredential`:115116```python117# Python118from azure.identity import DefaultAzureCredential119credential = DefaultAzureCredential()120client = ServiceClient(endpoint, credential)121```122123```csharp124// C#125var credential = new DefaultAzureCredential();126var client = new ServiceClient(new Uri(endpoint), credential);127```128129```java130// Java131TokenCredential credential = new DefaultAzureCredentialBuilder().build();132ServiceClient client = new ServiceClientBuilder()133 .endpoint(endpoint)134 .credential(credential)135 .buildClient();136```137138```typescript139// TypeScript140import { DefaultAzureCredential } from "@azure/identity";141const credential = new DefaultAzureCredential();142const client = new ServiceClient(endpoint, credential);143```144145**Never hardcode credentials. Use environment variables.**146147### Standard Verb Patterns148149Azure SDKs use consistent verbs across all languages:150151| Verb | Behavior |152|------|----------|153| `create` | Create new; fail if exists |154| `upsert` | Create or update |155| `get` | Retrieve; error if missing |156| `list` | Return collection |157| `delete` | Succeed even if missing |158| `begin` | Start long-running operation |159160### Language-Specific Patterns161162See `references/azure-sdk-patterns.md` for detailed patterns including:163164- **Python**: `ItemPaged`, `LROPoller`, context managers, Sphinx docstrings165- **.NET**: `Response<T>`, `Pageable<T>`, `Operation<T>`, mocking support166- **Java**: Builder pattern, `PagedIterable`/`PagedFlux`, Reactor types167- **TypeScript**: `PagedAsyncIterableIterator`, `AbortSignal`, browser considerations168169### Example: Azure SDK Skill Structure170171```markdown172---173name: skill-creator174description: |175 Azure AI Example SDK for Python. Use for [specific service features].176 Triggers: "example service", "create example", "list examples".177---178179# Azure AI Example SDK180181## Installation182183\`\`\`bash184pip install azure-ai-example185\`\`\`186187## Environment Variables188189\`\`\`bash190AZURE_EXAMPLE_ENDPOINT=https://<resource>.example.azure.com191\`\`\`192193## Authentication194195\`\`\`python196from azure.identity import DefaultAzureCredential197from azure.ai.example import ExampleClient198199credential = DefaultAzureCredential()200client = ExampleClient(201 endpoint=os.environ["AZURE_EXAMPLE_ENDPOINT"],202 credential=credential203)204\`\`\`205206## Core Workflow207208\`\`\`python209# Create210item = client.create_item(name="example", data={...})211212# List (pagination handled automatically)213for item in client.list_items():214 print(item.name)215216# Long-running operation217poller = client.begin_process(item_id)218result = poller.result()219220# Cleanup221client.delete_item(item_id)222\`\`\`223224## Reference Files225226| File | Contents |227|------|----------|228| [references/tools.md](references/tools.md) | Tool integrations |229| [references/streaming.md](references/streaming.md) | Event streaming patterns |230```231232---233234## Skill Creation Process2352361. **Gather SDK Context** — User provides SDK/API reference (REQUIRED)2372. **Understand** — Research SDK patterns from official docs2383. **Plan** — Identify reusable resources and product area category2394. **Create** — Write SKILL.md in `.github/skills/<skill-name>/`2405. **Categorize** — Create symlink in `skills/<language>/<category>/`2416. **Test** — Create acceptance criteria and test scenarios2427. **Document** — Update README.md skill catalog2438. **Iterate** — Refine based on real usage244245### Step 1: Gather SDK Context (REQUIRED)246247**Before creating any SDK skill, the user MUST provide:**248249| Required | Example | Purpose |250|----------|---------|---------|251| **SDK Package** | `azure-ai-agents`, `Azure.AI.OpenAI` | Identifies the exact SDK |252| **Documentation URL** | `https://learn.microsoft.com/en-us/azure/ai-services/...` | Primary source of truth |253| **Repository** (optional) | `Azure/azure-sdk-for-python` | For code patterns |254255**Prompt the user if not provided:**256```257To create this skill, I need:2581. The SDK package name (e.g., azure-ai-projects)2592. The Microsoft Learn documentation URL or GitHub repo2603. The target language (py/dotnet/ts/java)261```262263**Search official docs first:**264```bash265# Use microsoft-docs MCP to get current API patterns266# Query: "[SDK name] [operation] [language]"267# Verify: Parameters match the latest SDK version268```269270### Step 2: Understand the Skill271272Gather concrete examples:273274- "What SDK operations should this skill cover?"275- "What triggers should activate this skill?"276- "What errors do developers commonly encounter?"277278| Example Task | Reusable Resource |279|--------------|-------------------|280| Same auth code each time | Code example in SKILL.md |281| Complex streaming patterns | `references/streaming.md` |282| Tool configurations | `references/tools.md` |283| Error handling patterns | `references/error-handling.md` |284285### Step 3: Plan Product Area Category286287Skills are organized by **language** and **product area** in the `skills/` directory via symlinks.288289**Product Area Categories:**290291| Category | Description | Examples |292|----------|-------------|----------|293| `foundry` | AI Foundry, agents, projects, inference | `azure-ai-agents-py`, `azure-ai-projects-py` |294| `data` | Storage, Cosmos DB, Tables, Data Lake | `azure-cosmos-py`, `azure-storage-blob-py` |295| `messaging` | Event Hubs, Service Bus, Event Grid | `azure-eventhub-py`, `azure-servicebus-py` |296| `monitoring` | OpenTelemetry, App Insights, Query | `azure-monitor-opentelemetry-py` |297| `identity` | Authentication, DefaultAzureCredential | `azure-identity-py` |298| `security` | Key Vault, secrets, keys, certificates | `azure-keyvault-py` |299| `integration` | API Management, App Configuration | `azure-appconfiguration-py` |300| `compute` | Batch, ML compute | `azure-compute-batch-java` |301| `container` | Container Registry, ACR | `azure-containerregistry-py` |302303**Determine the category** based on:3041. Azure service family (Storage → `data`, Event Hubs → `messaging`)3052. Primary use case (AI agents → `foundry`)3063. Existing skills in the same service area307308### Step 4: Create the Skill309310**Location:** `.github/skills/<skill-name>/SKILL.md`311312**Naming convention:**313- `azure-<service>-<subservice>-<language>`314- Examples: `azure-ai-agents-py`, `azure-cosmos-java`, `azure-storage-blob-ts`315316**For Azure SDK skills:**3173181. Search `microsoft-docs` MCP for current API patterns3192. Verify against installed SDK version3203. Follow the section order above3214. Include cleanup code in examples3225. Add feature comparison tables323324**Write bundled resources first**, then SKILL.md.325326**Frontmatter:**327328```yaml329---330name: skill-name-py331description: |332 Azure Service SDK for Python. Use for [specific features].333 Triggers: "service name", "create resource", "specific operation".334---335```336337### Step 5: Categorize with Symlinks338339After creating the skill in `.github/skills/`, create a symlink in the appropriate category:340341```bash342# Pattern: skills/<language>/<category>/<short-name> -> ../../../.github/skills/<full-skill-name>343344# Example for azure-ai-agents-py in python/foundry:345cd skills/python/foundry346ln -s ../../../.github/skills/azure-ai-agents-py agents347348# Example for azure-cosmos-db-py in python/data:349cd skills/python/data350ln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db351```352353**Symlink naming:**354- Use short, descriptive names (e.g., `agents`, `cosmos`, `blob`)355- Remove the `azure-` prefix and language suffix356- Match existing patterns in the category357358**Verify the symlink:**359```bash360ls -la skills/python/foundry/agents361# Should show: agents -> ../../../.github/skills/azure-ai-agents-py362```363364### Step 6: Create Tests365366**Every skill MUST have acceptance criteria and test scenarios.**367368#### 6.1 Create Acceptance Criteria369370**Location:** `.github/skills/<skill-name>/references/acceptance-criteria.md`371372**Source materials** (in priority order):3731. Official Microsoft Learn docs (via `microsoft-docs` MCP)3742. SDK source code from the repository3753. Existing reference files in the skill376377**Format:**378```markdown379# Acceptance Criteria: <skill-name>380381**SDK**: `package-name`382**Repository**: https://github.com/Azure/azure-sdk-for-<language>383**Purpose**: Skill testing acceptance criteria384385---386387## 1. Correct Import Patterns388389### 1.1 Client Imports390391#### ✅ CORRECT: Main Client392\`\`\`python393from azure.ai.mymodule import MyClient394from azure.identity import DefaultAzureCredential395\`\`\`396397#### ❌ INCORRECT: Wrong Module Path398\`\`\`python399from azure.ai.mymodule.models import MyClient # Wrong - Client is not in models400\`\`\`401402## 2. Authentication Patterns403404#### ✅ CORRECT: DefaultAzureCredential405\`\`\`python406credential = DefaultAzureCredential()407client = MyClient(endpoint, credential)408\`\`\`409410#### ❌ INCORRECT: Hardcoded Credentials411\`\`\`python412client = MyClient(endpoint, api_key="hardcoded") # Security risk413\`\`\`414```415416**Critical patterns to document:**417- Import paths (these vary significantly between Azure SDKs)418- Authentication patterns419- Client initialization420- Async variants (`.aio` modules)421- Common anti-patterns422423#### 6.2 Create Test Scenarios424425**Location:** `tests/scenarios/<skill-name>/scenarios.yaml`426427```yaml428config:429 model: gpt-4430 max_tokens: 2000431 temperature: 0.3432433scenarios:434 - name: basic_client_creation435 prompt: |436 Create a basic example using the Azure SDK.437 Include proper authentication and client initialization.438 expected_patterns:439 - "DefaultAzureCredential"440 - "MyClient"441 forbidden_patterns:442 - "api_key="443 - "hardcoded"444 tags:445 - basic446 - authentication447 mock_response: |448 import os449 from azure.identity import DefaultAzureCredential450 from azure.ai.mymodule import MyClient451452 credential = DefaultAzureCredential()453 client = MyClient(454 endpoint=os.environ["AZURE_ENDPOINT"],455 credential=credential456 )457 # ... rest of working example458```459460**Scenario design principles:**461- Each scenario tests ONE specific pattern or feature462- `expected_patterns` — patterns that MUST appear463- `forbidden_patterns` — common mistakes that must NOT appear464- `mock_response` — complete, working code that passes all checks465- `tags` — for filtering (`basic`, `async`, `streaming`, `tools`)466467#### 6.3 Run Tests468469```bash470cd tests471pnpm install472473# Check skill is discovered474pnpm harness --list475476# Run in mock mode (fast, deterministic)477pnpm harness <skill-name> --mock --verbose478479# Run with Ralph Loop (iterative improvement)480pnpm harness <skill-name> --ralph --mock --max-iterations 5 --threshold 85481```482483**Success criteria:**484- All scenarios pass (100% pass rate)485- No false positives (mock responses always pass)486- Patterns catch real mistakes487488### Step 7: Update Documentation489490After creating the skill:4914921. **Update README.md** — Add the skill to the appropriate language section in the Skill Catalog493 - Update total skill count (line ~73: `> N skills in...`)494 - Update Skill Explorer link count (line ~15: `Browse all N skills`)495 - Update language count table (lines ~77-83)496 - Update language section count (e.g., `> N skills • suffix: -py`)497 - Update category count (e.g., `<summary><strong>Foundry & AI</strong> (N skills)</summary>`)498 - Add skill row in alphabetical order within its category499 - Update test coverage summary (line ~622: `**N skills with N test scenarios**`)500 - Update test coverage table — update skill count, scenario count, and top skills for the language5015022. **Regenerate GitHub Pages data** — Run the extraction script to update the docs site503 ```bash504 cd docs-site && npx tsx scripts/extract-skills.ts505 ```506 This updates `docs-site/src/data/skills.json` which feeds the Astro-based docs site.507 Then rebuild the docs site:508 ```bash509 cd docs-site && npm run build510 ```511 This outputs to `docs/` which is served by GitHub Pages.5125133. **Verify AGENTS.md** — Ensure the skill count is accurate514515---516517## Progressive Disclosure Patterns518519### Pattern 1: High-Level Guide with References520521```markdown522# SDK Name523524## Quick Start525[Minimal example]526527## Advanced Features528- **Streaming**: See [references/streaming.md](references/streaming.md)529- **Tools**: See [references/tools.md](references/tools.md)530```531532### Pattern 2: Language Variants533534```535azure-service-skill/536├── SKILL.md (overview + language selection)537└── references/538 ├── python.md539 ├── dotnet.md540 ├── java.md541 └── typescript.md542```543544### Pattern 3: Feature Organization545546```547azure-ai-agents/548├── SKILL.md (core workflow)549└── references/550 ├── tools.md551 ├── streaming.md552 ├── async-patterns.md553 └── error-handling.md554```555556---557558## Design Pattern References559560| Reference | Contents |561|-----------|----------|562| `references/workflows.md` | Sequential and conditional workflows |563| `references/output-patterns.md` | Templates and examples |564| `references/azure-sdk-patterns.md` | Language-specific Azure SDK patterns |565566---567568## Anti-Patterns569570| Don't | Why |571|-------|-----|572| Create skill without SDK context | Users must provide package name/docs URL |573| Put "when to use" in body | Body loads AFTER triggering |574| Hardcode credentials | Security risk |575| Skip authentication section | Agents will improvise poorly |576| Use outdated SDK patterns | APIs change; search docs first |577| Include README.md | Agents don't need meta-docs |578| Deeply nest references | Keep one level deep |579| Skip acceptance criteria | Skills without tests can't be validated |580| Skip symlink categorization | Skills won't be discoverable by category |581| Use wrong import paths | Azure SDKs have specific module structures |582583---584585## Checklist586587Before completing a skill:588589**Prerequisites:**590- [ ] User provided SDK package name or documentation URL591- [ ] Verified SDK patterns via `microsoft-docs` MCP592593**Skill Creation:**594- [ ] Description includes what AND when (trigger phrases)595- [ ] SKILL.md under 500 lines596- [ ] Authentication uses `DefaultAzureCredential`597- [ ] Includes cleanup/delete in examples598- [ ] References organized by feature599600**Categorization:**601- [ ] Skill created in `.github/skills/<skill-name>/`602- [ ] Symlink created in `skills/<language>/<category>/<short-name>`603- [ ] Symlink points to `../../../.github/skills/<skill-name>`604605**Testing:**606- [ ] `references/acceptance-criteria.md` created with correct/incorrect patterns607- [ ] `tests/scenarios/<skill-name>/scenarios.yaml` created608- [ ] All scenarios pass (`pnpm harness <skill> --mock`)609- [ ] Import paths documented precisely610611**Documentation:**612- [ ] README.md skill catalog updated613- [ ] Instructs to search `microsoft-docs` MCP for current APIs614
Full transparency — inspect the skill content before installing.