Skill Creator

1---
2name: skill-creator
3description: 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---
5 
6# Skill Creator
7 
8Guide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and Microsoft Foundry.
9 
10> **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.
11 
12## About Skills
13 
14Skills are modular knowledge packages that transform general-purpose agents into specialized experts:
15 
161. **Procedural knowledge** — Multi-step workflows for specific domains
172. **SDK expertise** — API patterns, authentication, error handling for Azure services
183. **Domain context** — Schemas, business logic, company-specific patterns
194. **Bundled resources** — Scripts, references, templates for complex tasks
20 
21---
22 
23## Core Principles
24 
25### 1. Concise is Key
26 
27The context window is a shared resource. Challenge each piece: "Does this justify its token cost?"
28 
29**Default assumption: Agents are already capable.** Only add what they don't already know.
30 
31### 2. Fresh Documentation First
32 
33**Azure SDKs change constantly.** Skills should instruct agents to verify documentation:
34 
35```markdown
36## Before Implementation
37 
38Search `microsoft-docs` MCP for current API patterns:
39- Query: "[SDK name] [operation] python"
40- Verify: Parameters match your installed SDK version
41```
42 
43### 3. Degrees of Freedom
44 
45Match specificity to task fragility:
46 
47| 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 |
52 
53### 4. Progressive Disclosure
54 
55Skills load in three levels:
56 
571. **Metadata** (~100 words) — Always in context
582. **SKILL.md body** (<5k words) — When skill triggers
593. **References** (unlimited) — As needed
60 
61**Keep SKILL.md under 500 lines.** Split into reference files when approaching this limit.
62 
63---
64 
65## Skill Structure
66 
67```
68skill-name/
69├── SKILL.md (required)
70│   ├── YAML frontmatter (name, description)
71│   └── Markdown instructions
72└── Bundled Resources (optional)
73    ├── scripts/      — Executable code
74    ├── references/   — Documentation loaded as needed
75    └── assets/       — Output resources (templates, images)
76```
77 
78### SKILL.md
79 
80- **Frontmatter**: `name` and `description`. The description is the trigger mechanism.
81- **Body**: Instructions loaded only after triggering.
82 
83### Bundled Resources
84 
85| 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 |
90 
91**Don't include**: README.md, CHANGELOG.md, installation guides.
92 
93---
94 
95## Creating Azure SDK Skills
96 
97When creating skills for Azure SDKs, follow these patterns consistently.
98 
99### Skill Section Order
100 
101Follow this structure (based on existing Azure SDK skills):
102 
1031. **Title** — `# SDK Name`
1042. **Installation** — `pip install`, `npm install`, etc.
1053. **Environment Variables** — Required configuration
1064. **Authentication** — Always `DefaultAzureCredential`
1075. **Core Workflow** — Minimal viable example
1086. **Feature Tables** — Clients, methods, tools
1097. **Best Practices** — Numbered list
1108. **Reference Links** — Table linking to `/references/*.md`
111 
112### Authentication Pattern (All Languages)
113 
114Always use `DefaultAzureCredential`:
115 
116```python
117# Python
118from azure.identity import DefaultAzureCredential
119credential = DefaultAzureCredential()
120client = ServiceClient(endpoint, credential)
121```
122 
123```csharp
124// C#
125var credential = new DefaultAzureCredential();
126var client = new ServiceClient(new Uri(endpoint), credential);
127```
128 
129```java
130// Java
131TokenCredential credential = new DefaultAzureCredentialBuilder().build();
132ServiceClient client = new ServiceClientBuilder()
133    .endpoint(endpoint)
134    .credential(credential)
135    .buildClient();
136```
137 
138```typescript
139// TypeScript
140import { DefaultAzureCredential } from "@azure/identity";
141const credential = new DefaultAzureCredential();
142const client = new ServiceClient(endpoint, credential);
143```
144 
145**Never hardcode credentials. Use environment variables.**
146 
147### Standard Verb Patterns
148 
149Azure SDKs use consistent verbs across all languages:
150 
151| 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 |
159 
160### Language-Specific Patterns
161 
162See `references/azure-sdk-patterns.md` for detailed patterns including:
163 
164- **Python**: `ItemPaged`, `LROPoller`, context managers, Sphinx docstrings
165- **.NET**: `Response<T>`, `Pageable<T>`, `Operation<T>`, mocking support
166- **Java**: Builder pattern, `PagedIterable`/`PagedFlux`, Reactor types
167- **TypeScript**: `PagedAsyncIterableIterator`, `AbortSignal`, browser considerations
168 
169### Example: Azure SDK Skill Structure
170 
171```markdown
172---
173name: skill-creator
174description: |
175  Azure AI Example SDK for Python. Use for [specific service features].
176  Triggers: "example service", "create example", "list examples".
177---
178 
179# Azure AI Example SDK
180 
181## Installation
182 
183\`\`\`bash
184pip install azure-ai-example
185\`\`\`
186 
187## Environment Variables
188 
189\`\`\`bash
190AZURE_EXAMPLE_ENDPOINT=https://<resource>.example.azure.com
191\`\`\`
192 
193## Authentication
194 
195\`\`\`python
196from azure.identity import DefaultAzureCredential
197from azure.ai.example import ExampleClient
198 
199credential = DefaultAzureCredential()
200client = ExampleClient(
201    endpoint=os.environ["AZURE_EXAMPLE_ENDPOINT"],
202    credential=credential
203)
204\`\`\`
205 
206## Core Workflow
207 
208\`\`\`python
209# Create
210item = client.create_item(name="example", data={...})
211 
212# List (pagination handled automatically)
213for item in client.list_items():
214    print(item.name)
215 
216# Long-running operation
217poller = client.begin_process(item_id)
218result = poller.result()
219 
220# Cleanup
221client.delete_item(item_id)
222\`\`\`
223 
224## Reference Files
225 
226| File | Contents |
227|------|----------|
228| [references/tools.md](references/tools.md) | Tool integrations |
229| [references/streaming.md](references/streaming.md) | Event streaming patterns |
230```
231 
232---
233 
234## Skill Creation Process
235 
2361. **Gather SDK Context** — User provides SDK/API reference (REQUIRED)
2372. **Understand** — Research SDK patterns from official docs
2383. **Plan** — Identify reusable resources and product area category
2394. **Create** — Write SKILL.md in `.github/skills/<skill-name>/`
2405. **Categorize** — Create symlink in `skills/<language>/<category>/`
2416. **Test** — Create acceptance criteria and test scenarios
2427. **Document** — Update README.md skill catalog
2438. **Iterate** — Refine based on real usage
244 
245### Step 1: Gather SDK Context (REQUIRED)
246 
247**Before creating any SDK skill, the user MUST provide:**
248 
249| 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 |
254 
255**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 repo
2603. The target language (py/dotnet/ts/java)
261```
262 
263**Search official docs first:**
264```bash
265# Use microsoft-docs MCP to get current API patterns
266# Query: "[SDK name] [operation] [language]"
267# Verify: Parameters match the latest SDK version
268```
269 
270### Step 2: Understand the Skill
271 
272Gather concrete examples:
273 
274- "What SDK operations should this skill cover?"
275- "What triggers should activate this skill?"
276- "What errors do developers commonly encounter?"
277 
278| 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` |
284 
285### Step 3: Plan Product Area Category
286 
287Skills are organized by **language** and **product area** in the `skills/` directory via symlinks.
288 
289**Product Area Categories:**
290 
291| 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` |
302 
303**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 area
307 
308### Step 4: Create the Skill
309 
310**Location:** `.github/skills/<skill-name>/SKILL.md`
311 
312**Naming convention:**
313- `azure-<service>-<subservice>-<language>`
314- Examples: `azure-ai-agents-py`, `azure-cosmos-java`, `azure-storage-blob-ts`
315 
316**For Azure SDK skills:**
317 
3181. Search `microsoft-docs` MCP for current API patterns
3192. Verify against installed SDK version
3203. Follow the section order above
3214. Include cleanup code in examples
3225. Add feature comparison tables
323 
324**Write bundled resources first**, then SKILL.md.
325 
326**Frontmatter:**
327 
328```yaml
329---
330name: skill-name-py
331description: |
332  Azure Service SDK for Python. Use for [specific features].
333  Triggers: "service name", "create resource", "specific operation".
334---
335```
336 
337### Step 5: Categorize with Symlinks
338 
339After creating the skill in `.github/skills/`, create a symlink in the appropriate category:
340 
341```bash
342# Pattern: skills/<language>/<category>/<short-name> -> ../../../.github/skills/<full-skill-name>
343 
344# Example for azure-ai-agents-py in python/foundry:
345cd skills/python/foundry
346ln -s ../../../.github/skills/azure-ai-agents-py agents
347 
348# Example for azure-cosmos-db-py in python/data:
349cd skills/python/data
350ln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db
351```
352 
353**Symlink naming:**
354- Use short, descriptive names (e.g., `agents`, `cosmos`, `blob`)
355- Remove the `azure-` prefix and language suffix
356- Match existing patterns in the category
357 
358**Verify the symlink:**
359```bash
360ls -la skills/python/foundry/agents
361# Should show: agents -> ../../../.github/skills/azure-ai-agents-py
362```
363 
364### Step 6: Create Tests
365 
366**Every skill MUST have acceptance criteria and test scenarios.**
367 
368#### 6.1 Create Acceptance Criteria
369 
370**Location:** `.github/skills/<skill-name>/references/acceptance-criteria.md`
371 
372**Source materials** (in priority order):
3731. Official Microsoft Learn docs (via `microsoft-docs` MCP)
3742. SDK source code from the repository
3753. Existing reference files in the skill
376 
377**Format:**
378```markdown
379# Acceptance Criteria: <skill-name>
380 
381**SDK**: `package-name`
382**Repository**: https://github.com/Azure/azure-sdk-for-<language>
383**Purpose**: Skill testing acceptance criteria
384 
385---
386 
387## 1. Correct Import Patterns
388 
389### 1.1 Client Imports
390 
391#### ✅ CORRECT: Main Client
392\`\`\`python
393from azure.ai.mymodule import MyClient
394from azure.identity import DefaultAzureCredential
395\`\`\`
396 
397#### ❌ INCORRECT: Wrong Module Path
398\`\`\`python
399from azure.ai.mymodule.models import MyClient  # Wrong - Client is not in models
400\`\`\`
401 
402## 2. Authentication Patterns
403 
404#### ✅ CORRECT: DefaultAzureCredential
405\`\`\`python
406credential = DefaultAzureCredential()
407client = MyClient(endpoint, credential)
408\`\`\`
409 
410#### ❌ INCORRECT: Hardcoded Credentials
411\`\`\`python
412client = MyClient(endpoint, api_key="hardcoded")  # Security risk
413\`\`\`
414```
415 
416**Critical patterns to document:**
417- Import paths (these vary significantly between Azure SDKs)
418- Authentication patterns
419- Client initialization
420- Async variants (`.aio` modules)
421- Common anti-patterns
422 
423#### 6.2 Create Test Scenarios
424 
425**Location:** `tests/scenarios/<skill-name>/scenarios.yaml`
426 
427```yaml
428config:
429  model: gpt-4
430  max_tokens: 2000
431  temperature: 0.3
432 
433scenarios:
434  - name: basic_client_creation
435    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      - basic
446      - authentication
447    mock_response: |
448      import os
449      from azure.identity import DefaultAzureCredential
450      from azure.ai.mymodule import MyClient
451      
452      credential = DefaultAzureCredential()
453      client = MyClient(
454          endpoint=os.environ["AZURE_ENDPOINT"],
455          credential=credential
456      )
457      # ... rest of working example
458```
459 
460**Scenario design principles:**
461- Each scenario tests ONE specific pattern or feature
462- `expected_patterns` — patterns that MUST appear
463- `forbidden_patterns` — common mistakes that must NOT appear
464- `mock_response` — complete, working code that passes all checks
465- `tags` — for filtering (`basic`, `async`, `streaming`, `tools`)
466 
467#### 6.3 Run Tests
468 
469```bash
470cd tests
471pnpm install
472 
473# Check skill is discovered
474pnpm harness --list
475 
476# Run in mock mode (fast, deterministic)
477pnpm harness <skill-name> --mock --verbose
478 
479# Run with Ralph Loop (iterative improvement)
480pnpm harness <skill-name> --ralph --mock --max-iterations 5 --threshold 85
481```
482 
483**Success criteria:**
484- All scenarios pass (100% pass rate)
485- No false positives (mock responses always pass)
486- Patterns catch real mistakes
487 
488### Step 7: Update Documentation
489 
490After creating the skill:
491 
4921. **Update README.md** — Add the skill to the appropriate language section in the Skill Catalog
493   - 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 category
499   - 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 language
501 
5022. **Regenerate GitHub Pages data** — Run the extraction script to update the docs site
503   ```bash
504   cd docs-site && npx tsx scripts/extract-skills.ts
505   ```
506   This updates `docs-site/src/data/skills.json` which feeds the Astro-based docs site.
507   Then rebuild the docs site:
508   ```bash
509   cd docs-site && npm run build
510   ```
511   This outputs to `docs/` which is served by GitHub Pages.
512 
5133. **Verify AGENTS.md** — Ensure the skill count is accurate
514 
515---
516 
517## Progressive Disclosure Patterns
518 
519### Pattern 1: High-Level Guide with References
520 
521```markdown
522# SDK Name
523 
524## Quick Start
525[Minimal example]
526 
527## Advanced Features
528- **Streaming**: See [references/streaming.md](references/streaming.md)
529- **Tools**: See [references/tools.md](references/tools.md)
530```
531 
532### Pattern 2: Language Variants
533 
534```
535azure-service-skill/
536├── SKILL.md (overview + language selection)
537└── references/
538    ├── python.md
539    ├── dotnet.md
540    ├── java.md
541    └── typescript.md
542```
543 
544### Pattern 3: Feature Organization
545 
546```
547azure-ai-agents/
548├── SKILL.md (core workflow)
549└── references/
550    ├── tools.md
551    ├── streaming.md
552    ├── async-patterns.md
553    └── error-handling.md
554```
555 
556---
557 
558## Design Pattern References
559 
560| 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 |
565 
566---
567 
568## Anti-Patterns
569 
570| 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 |
582 
583---
584 
585## Checklist
586 
587Before completing a skill:
588 
589**Prerequisites:**
590- [ ] User provided SDK package name or documentation URL
591- [ ] Verified SDK patterns via `microsoft-docs` MCP
592 
593**Skill Creation:**
594- [ ] Description includes what AND when (trigger phrases)
595- [ ] SKILL.md under 500 lines
596- [ ] Authentication uses `DefaultAzureCredential`
597- [ ] Includes cleanup/delete in examples
598- [ ] References organized by feature
599 
600**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>`
604 
605**Testing:**
606- [ ] `references/acceptance-criteria.md` created with correct/incorrect patterns
607- [ ] `tests/scenarios/<skill-name>/scenarios.yaml` created
608- [ ] All scenarios pass (`pnpm harness <skill> --mock`)
609- [ ] Import paths documented precisely
610 
611**Documentation:**
612- [ ] README.md skill catalog updated
613- [ ] Instructs to search `microsoft-docs` MCP for current APIs
614