[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69B4JCRQV5SPXAFCKXQRV0H":3,"skill-same:01M69B4JCRQV5SPXAFCKXQRV0H":107},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":42,"linkOnly":43,"markdownContent":44,"markdownBody":45,"frontMatter":46,"refName":47,"commitSha":48,"skillDirectory":49,"forksCount":50,"repositoryHtmlUrl":51,"repositoryHomepageUrl":52,"ownerHtmlUrl":53,"ownerBlogUrl":54,"ownerDescription":55,"updatedAt":56,"install":57,"resources":70},"01M69B4JCRQV5SPXAFCKXQRV0H","skill-creator",null,"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.","microsoft\u002Fskills","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69AJYYW4E1RMSYCQDJ4FJSH",3204,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,9,41],"creator","skill creator","guide","new","when","Existing","for","sdks","with","ai coding","use","coding","services","azure","ai coding agents","microsoft foundry","foundry","coding agents","2026-11-10 10:12:30",false,"---\nname: skill-creator\ndescription: 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.\n---\n\n# Skill Creator\n\nGuide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and Microsoft Foundry.\n\n> **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.\n\n## About Skills\n\nSkills are modular knowledge packages that transform general-purpose agents into specialized experts:\n\n1. **Procedural knowledge** — Multi-step workflows for specific domains\n2. **SDK expertise** — API patterns, authentication, error handling for Azure services\n3. **Domain context** — Schemas, business logic, company-specific patterns\n4. **Bundled resources** — Scripts, references, templates for complex tasks\n\n---\n\n## Core Principles\n\n### 1. Concise is Key\n\nThe context window is a shared resource. Challenge each piece: \"Does this justify its token cost?\"\n\n**For domain\u002Fprocedural skills**: Agents are already capable. Only add what they don't already know.\n\n**For SDK\u002FAPI skills**: Users MUST provide SDK package name, documentation URL, or repository reference. The skill cannot be created without this context.\n\n### 2. Fresh Documentation First\n\n**Azure SDKs change constantly.** Skills should instruct agents to verify documentation:\n\n```markdown\n## Before Implementation\n\nSearch `microsoft-docs` MCP for current API patterns:\n\n- Query: \"[SDK name] [operation] python\"\n- Verify: Parameters match your installed SDK version\n```\n\n### 3. Degrees of Freedom\n\nMatch specificity to implementation constraints. High freedom when approaches vary; low freedom when precise execution is required:\n\n| Freedom    | When                             | Example          |\n| ---------- | -------------------------------- | ---------------- |\n| **High**   | Multiple valid approaches        | Text guidelines  |\n| **Medium** | Preferred pattern with variation | Pseudocode       |\n| **Low**    | Must be exact                    | Specific scripts |\n\n### 4. Progressive Disclosure\n\nSkills load in three levels:\n\n1. **Metadata** (~100 words) — Always in context\n2. **SKILL.md body** (\u003C5k words) — When skill triggers\n3. **References** (unlimited) — As needed\n\n**Keep SKILL.md under 500 lines.** Split into reference files when approaching this limit.\n\n---\n\n## Skill Structure\n\n**Quick reference:**\n\n```\nskill-name\u002F\n├── SKILL.md (required)\n│   ├── YAML frontmatter (name, description)\n│   └── Markdown instructions\n└── Bundled Resources (optional)\n    ├── scripts\u002F      — Executable code\n    ├── references\u002F   — Documentation loaded as needed\n    └── assets\u002F       — Output resources (templates, images)\n```\n\nFor Azure SDK skills, follow the **Skill Section Order** below. For domain skills, use your judgment to organize logically.\n\n### SKILL.md Essentials\n\n- **Frontmatter**: `name` and `description` (description triggers the skill)\n- **Body**: Keep under 500 lines; split large skills into reference files\n\n### Bundled Resources (Optional)\n\n| Type          | When to Include                          | Examples                                                   |\n| ------------- | ---------------------------------------- | ---------------------------------------------------------- |\n| `scripts\u002F`    | Reused code patterns                     | Auth setup, CLI scripts                                    |\n| `references\u002F` | Feature deep-dives and overflow examples | `capabilities.md` index, `non-hero-scenarios.md`, API docs |\n| `assets\u002F`     | Output templates                         | Boilerplate code, images                                   |\n\n---\n\n## Creating Azure SDK Skills\n\nWhen creating skills for Azure SDKs, follow these patterns consistently.\n\n### Token Budget Guidelines (REQUIRED)\n\nEvery Azure SDK skill MUST stay within these token limits:\n\n| Section                       | Target           | Absolute Max     |\n| ----------------------------- | ---------------- | ---------------- |\n| Installation + Env Vars       | 100 tokens       | 150              |\n| Authentication & Lifecycle    | 200 tokens       | 300              |\n| Core Workflow (1 example)     | 300 tokens       | 400              |\n| Feature Tables                | 200 tokens       | 300              |\n| Best Practices (6-8 items)    | 200 tokens       | 250              |\n| References (reference\u002F links) | 100 tokens       | 150              |\n| **Total SKILL.md**            | **~1100 tokens** | **~1500 tokens** |\n\n**Enforcement**:\n\n- Exceeding max limit → refactor into `\u002Freferences\u002F` subdirectories\n- When approaching 500 lines → move entire sections to reference files\n- Annotate with `\u003C!-- Token Count: ~XXXX (target: 1100, max: 1500) -->` immediately below the skill's H1\n\n---\n\n### Reference Extraction Guide (REQUIRED)\n\nDecide what goes in SKILL.md vs. `\u002Freferences\u002F` using these signals:\n\n| Signal         | Move to `\u002Freferences\u002F`              | Keep in SKILL.md       |\n| -------------- | ----------------------------------- | ---------------------- |\n| Use frequency  | \u003C20% of typical use                 | ~80%+ of workflows     |\n| Cognitive load | Advanced patterns, multiple options | Single happy path      |\n| Example length | >10 lines, multiple paths           | 1-5 lines, single path |\n\n**Content extraction rules:**\n\n- **Batch operations** → `\u002Freferences\u002Fbatch-operations.md`\n- **Error handling** (beyond try-except) → `\u002Freferences\u002Ferror-handling.md`\n- **Performance tuning** → `\u002Freferences\u002Fperformance.md`\n- **Alternative workflows** → `\u002Freferences\u002Fworkflows-comparison.md`\n- **Streaming\u002Fevents** → `\u002Freferences\u002Fstreaming.md`\n- **Advanced auth** → `\u002Freferences\u002Fauth-strategies.md`\n- **Tool integration** → `\u002Freferences\u002Ftools.md`\n- **Breaking changes** → `\u002Freferences\u002Fmigration.md`\n\n**Decision:** Keep common case in SKILL.md, move edge cases to `\u002Freferences\u002F`.\n\n---\n\n### Core Workflow Discipline (REQUIRED)\n\nEvery Azure SDK skill must clarify which workflow(s) it documents.\n\n**Case 1: Single clear \"core workflow\"** (majority of services)\n\nIf one pattern handles ~80% of use cases:\n\n1. Designate it as the core workflow\n2. Show ONLY this workflow in SKILL.md (one complete, runnable example)\n3. Defer alternatives to `\u002Freferences\u002F`:\n   - Batch operations → `\u002Freferences\u002Fbatch-operations.md`\n   - Error handling → `\u002Freferences\u002Ferror-handling.md`\n   - Performance tuning → `\u002Freferences\u002Fperformance.md`\n   - Alternative workflows → `\u002Freferences\u002Fworkflows-comparison.md`\n\n**Example**: Azure Key Vault Secrets (core workflow: retrieve a secret using managed identity). Alternative authentication workflows in `\u002Freferences\u002F`: local development with `DefaultAzureCredential`, workload identity, and service-principal credentials (client secret or certificate).\n\n**Case 2: Multiple equally-valid \"core workflows\"** (e.g., authentication strategies, deployment targets)\n\nIf no single pattern dominates:\n\n1. Include every hero scenario in SKILL.md, even when that means multiple equally valid workflows\n2. Show one complete, runnable example for each hero scenario in SKILL.md\n3. Use `\u002Freferences\u002Fworkflows-comparison.md` for trade-offs, secondary variations, and deeper context that would otherwise bloat the main file\n4. Do NOT treat valid alternatives as \"advanced\" when they are core to real usage — they're equally valid, just different contexts\n\n**Example**: Azure Identity SDK has several hero scenarios. Keep the primary local-development and production-safe credential flows in SKILL.md, then use `\u002Freferences\u002Fcredential-types.md` for deeper comparisons across `AzureCliCredential`, workload identity, service principal variants, and other secondary credential choices.\n\n**Decision rule**: If you're unsure, ask: \"Would a user choosing the other approach call what I wrote wrong?\" If yes, it's another hero scenario and belongs in SKILL.md. If no, it can be summarized and linked from `\u002Freferences\u002F`.\n\n---\n\n### Skill Section Order\n\nFollow this structure (based on existing Azure SDK skills):\n\n1. **Title** — `# SDK Name`\n2. **Installation** — `pip install`, `npm install`, etc.\n3. **Environment Variables** — Required configuration, with an inline comment explaining when it's required. If using `DefaultAzureCredential` in production, include `AZURE_TOKEN_CREDENTIALS` (set to `prod` or `\u003Cspecific_credential>`)\n4. **Authentication & Lifecycle** — For Python skills, prefer `DefaultAzureCredential`: use it as-is for local development, and constrain it for production by setting `AZURE_TOKEN_CREDENTIALS` to `prod` (or a specific target credential name). A specific Microsoft Entra Token credential such as `ManagedIdentityCredential` or `WorkloadIdentityCredential` may be used directly instead. **For Python skills, this section MUST start with the standard callout block** (see [Required Authentication & Lifecycle Callout (Python)](#required-authentication--lifecycle-callout-python) below).\n5. **Core Workflow** — Minimal viable example (per core workflow discipline above)\n6. **Feature Tables** — Clients, methods, tools\n7. **Best Practices** — Numbered list\n8. **Reference Links** — Table linking to `\u002Freferences\u002F*.md` (for Azure SDK skills, include `capabilities.md` + `non-hero-scenarios.md`)\n\n### Required Authentication & Lifecycle Callout (Python)\n\n> **Scope:** Python skills (`-py` suffix) only. Other languages may follow their own idioms.\n\nEvery Python Azure SDK skill MUST open its `## Authentication & Lifecycle` section with the following callout block, **verbatim**, before any code samples. This makes the two non-negotiable rules visible to users before they read or copy any client setup code.\n\n```markdown\n## Authentication & Lifecycle\n\n> **? Two rules apply to every code sample below:**\n>\n> 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI \u002F VS Code \u002F Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account\u002FAPI keys — they bypass Entra audit and rotation.\n>    - Local dev: `DefaultAzureCredential` works as-is.\n>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>`) to constrain the credential chain to production-safe credentials.\n> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:\n>    - Sync: `with \u003CClient>(...) as client:`\n>    - Async: `async with \u003CClient>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)\n>\n> Snippets may abbreviate this setup, but production code should always follow both rules.\n```\n\n**Placement rules:**\n\n- Insert immediately under the `## Authentication & Lifecycle` heading, before the first code sample.\n- Do not paraphrase or restructure the wording — the consistency across skills is the point.\n- If the SDK does not support Entra ID at all (rare — e.g. some legacy speech REST endpoints, websocket APIs that require subscription keys), keep rule #2 (context managers) and replace rule #1 with a single sentence noting the SDK requires API-key auth and explaining why Entra is not yet available.\n- If the SDK is async-only (e.g. `azure-ai-voicelive`), keep both rules but show only the async form in the bullets.\n- Skip the callout entirely for non-Azure Python skills with no client lifecycle (e.g. `pydantic-models-py`).\n\n**Code sample enforcement.** Every client construction in the skill body must demonstrate both rules:\n\n- Show `with` \u002F `async with` on every client instantiation in usage examples (not just the auth section).\n- Show `DefaultAzureCredential` in the primary auth example. **Do not delete API-key examples for SDKs where keys are still officially supported** — many existing users (especially in regulated environments still completing their Entra rollout) need a copy-pastable working sample. Demote the keyed snippet into a clearly-labeled `### Legacy: API Key (existing keyed deployments)` subsection placed _after_ the primary `DefaultAzureCredential` block in the same `## Authentication & Lifecycle` section. Include a one-line note that new code should use `DefaultAzureCredential` and that the keyed path is for existing deployments. Also add the `\u003CSERVICE>_KEY` env var back to the Environment Variables block with a `# Only required for the legacy API-key auth path below` comment.\n- A handful of services have key-specific quirks worth calling out in the Legacy subsection (e.g. `azure-ai-translation-text` requires a `region=` parameter when using a key against the global endpoint, because token-credential auth requires a custom subdomain endpoint). Surface these in the demoted block rather than dropping the example.\n- For async examples, wrap `DefaultAzureCredential` from `azure.identity.aio` in `async with credential:` alongside the client.\n\n### Authentication Pattern (All Languages)\n\nFor local development, use `DefaultAzureCredential` which supports multiple auth methods. For production, use a specific credential type or configure `DefaultAzureCredential` with environment variable `AZURE_TOKEN_CREDENTIALS` set to `prod` or specify the target credential.\n\nIf configuring a Rust skill, use `DeveloperToolsCredential` for local development and `ManagedIdentityCredential` for production. The Rust SDK does not support `DefaultAzureCredential`, so explicitly use the appropriate credential in each environment.\n\n```python\n# Python — note: client is wrapped in `with` for deterministic cleanup\nfrom azure.identity import DefaultAzureCredential, ManagedIdentityCredential\n# Local dev: DefaultAzureCredential works as-is.\ncredential = DefaultAzureCredential()\n# Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS.\n# credential = DefaultAzureCredential(require_envvar=True)\n# Or use a specific credential directly in production:\n# See https:\u002F\u002Flearn.microsoft.com\u002Fpython\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-python#credential-classes\n# credential = ManagedIdentityCredential()\nwith ServiceClient(endpoint, credential) as client:\n    client.do_thing()\n```\n\n```csharp\n\u002F\u002F C#\nusing Azure.Identity;\n\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\nvar credential = new DefaultAzureCredential(\n    DefaultAzureCredential.DefaultEnvironmentVariableName\n);\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F See https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-dotnet#credential-classes\n\u002F\u002F var credential = new ManagedIdentityCredential();\nvar client = new ServiceClient(new Uri(endpoint), credential);\n```\n\n```java\n\u002F\u002F Java\nimport com.azure.identity.AzureIdentityEnvVars;\nimport com.azure.identity.DefaultAzureCredentialBuilder;\nimport com.azure.identity.ManagedIdentityCredential;\nimport com.azure.identity.ManagedIdentityCredentialBuilder;\n\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\nTokenCredential credential = new DefaultAzureCredentialBuilder()\n    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)\n    .build();\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F See https:\u002F\u002Flearn.microsoft.com\u002Fjava\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-java-stable#credential-classes\n\u002F\u002F TokenCredential credential = new ManagedIdentityCredentialBuilder().build();\nServiceClient client = new ServiceClientBuilder()\n    .endpoint(endpoint)\n    .credential(credential)\n    .buildClient();\n```\n\n```typescript\n\u002F\u002F TypeScript\nimport {\n  DefaultAzureCredential,\n  ManagedIdentityCredential,\n} from \"@azure\u002Fidentity\";\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\nconst credential = new DefaultAzureCredential({\n  requiredEnvVars: [\"AZURE_TOKEN_CREDENTIALS\"],\n});\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F See https:\u002F\u002Flearn.microsoft.com\u002Fjavascript\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-node-latest#credential-classes\n\u002F\u002F const credential = new ManagedIdentityCredential();\nconst client = new ServiceClient(endpoint, credential);\n```\n\n```go\n\u002F\u002F Go\nimport (\n  \"context\"\n\n  \"github.com\u002FAzure\u002Fazure-sdk-for-go\u002Fsdk\u002Fazidentity\"\n  \"github.com\u002FAzure\u002Fazure-sdk-for-go\u002Fsdk\u002Fstorage\u002Fazblob\"\n)\n\nctx := context.Background()\n\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\ncred, err := azidentity.NewDefaultAzureCredential(nil)\nif err != nil {\n  panic(err)\n}\n\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F cred, err := azidentity.NewManagedIdentityCredential(nil)\n\nclient, err := azblob.NewClient(\"https:\u002F\u002F\u003Caccount>.blob.core.windows.net\u002F\", cred, nil)\nif err != nil {\n  panic(err)\n}\n\n_ = client\n_ = ctx\n```\n\n```rust\n\u002F\u002F Rust\nuse azure_identity::DeveloperToolsCredential;\nuse azure_storage_blob::BlobServiceClient;\n\nlet credential = DeveloperToolsCredential::new(); \u002F\u002F Local dev\nlet client = BlobServiceClient::new(\n    \"https:\u002F\u002F\u003Caccount>.blob.core.windows.net\u002F\",\n    credential,\n    None,\n)?;\n```\n\n**Never hardcode credentials. Use environment variables.**\n\n### Anti-Patterns: What NOT to Do (REQUIRED Reading)\n\n**These patterns cause bloat and inefficiency. Every skill author must review this section before writing.**\n\n#### Anti-Pattern 1: \"Exhaustive API Reference\"\n\n- ❌ **Don't**: List all 50 SDK methods in a feature table with code samples for every variant\n- ✅ **Do**: Show 3-5 core methods in a table; link to official Azure API reference for exhaustive list\n- **Token cost**: Listing all methods + examples = 400-600 tokens wasted\n- **User impact**: Overwhelming cognitive load; users don't know what to use\n\n#### Anti-Pattern 2: \"Multiple Ways to Solve One Problem\"\n\n- ❌ **Don't**: \"Here's approach A, B, C, and D to paginate results\" in the main body\n- ✅ **Do**: \"Use `ItemPaged` for sync pagination\" (primary example); link alternatives to `\u002Freferences\u002F`\n- **Token cost**: Each alternate approach = 50-100 tokens; 5 approaches = skill becomes inefficient\n- **User impact**: Decision paralysis; users re-read everything\n\n#### Anti-Pattern 3: \"Beginner + Intermediate + Advanced in One Skill\"\n\n- ❌ **Don't**: Skill that goes from \"what is a client?\" to \"custom retry policies\" to \"circuit breaker patterns\"\n- ✅ **Do**: Core workflow covers 80% use case; advanced patterns in `\u002Freferences\u002F`\n- **Token cost**: Every skill level adds 200-300 tokens; three levels = 600-900 extra tokens\n- **User impact**: Experts bored, beginners overwhelmed; nobody gets what they need\n\n#### Anti-Pattern 4: \"Restating Official Documentation\"\n\n- ❌ **Don't**: \"The CosmosClient constructor takes an endpoint (string) and credential (TokenCredential). The endpoint identifies the Azure Cosmos resource...\"\n- ✅ **Do**: Show code: `client = CosmosClient(endpoint, credential)`. Link to official docs: `microsoft-docs` MCP.\n- **Token cost**: Verbose explanation = 50-100 tokens per parameter; large APIs waste 300+ tokens\n- **User impact**: Redundant; official docs are authoritative, skill should show usage not repeat them\n\n#### Anti-Pattern 5: \"Verbose Explanation When Example Suffices\"\n\n- ❌ **Don't**: \"To create a client, you first instantiate the class using the constructor, passing the endpoint and credential parameters. The endpoint is a string that identifies your resource...\"\n- ✅ **Do**: Show code immediately: `with CosmosClient(endpoint, credential) as client:`\n\n---\n\n### Efficiency Validation (REQUIRED - Phase 2)\n\n**During authoring, validate skill efficiency manually, then run the Vally eval if the skill has one under `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fvally\u002F`.**\n\n**1. Measure token count:**\n\nUse a token counter or model playground to measure each section. Compare to the Token Budget Guidelines targets above. If any section exceeds max, move content to `\u002Freferences\u002F`.\n\n**2. Run anti-pattern checklist:**\n\n- [ ] No exhaustive API reference (show 3-5 core methods, not 50)\n- [ ] No multiple solutions to one problem in SKILL.md\n- [ ] No beginner+intermediate+advanced mixed\n- [ ] No restating official docs (code first, link to microsoft-docs)\n- [ ] No verbose prose (examples first, minimal text)\n\n**3. Example count audit:**\n\n- [ ] 1 complete example per hero scenario \u002F core workflow documented in SKILL.md. For Python SDKs that support both sync and async, the paired sync + async examples for the same workflow count as one workflow, not two.\n- [ ] Feature table includes 3-5 core methods (not comprehensive API)\n- [ ] Max 1 example per best practice bullet\n\n**4. Frontmatter validation:**\n\n- [ ] `name` matches `.github\u002Fskills\u002F\u003Cname>\u002FSKILL.md`\n- [ ] `description` includes trigger keywords\n- [ ] `description` is concise (~200 chars is a good target; schema max is 1,024 chars)\n- [ ] If included, optional `benchmark_tokens_*` and `benchmark_quality_*` metadata fields are flat strings under `metadata`\n\n**4b. Authentication guidance validation** (critical for all credentials):\n\n- [ ] If skill uses Azure Identity credentials, verify guidance against the current official credential docs for that language\u002Fpackage (Microsoft Learn where available; otherwise the upstream SDK repo or package docs)\n- [ ] For Python skills, development guidance may recommend `DefaultAzureCredential` (supports multiple dev credential types)\n- [ ] For Python skills, production guidance: `DefaultAzureCredential` alone (unconstrained) is not sufficient; require either `AZURE_TOKEN_CREDENTIALS=prod` (or a specific target credential) to constrain the chain, or a specific credential (e.g., `ManagedIdentityCredential`) used directly\n- [ ] For Rust skills, development\u002Fproduction guidance reflects the actual supported credentials (`DeveloperToolsCredential` for local dev; a specific production credential such as `ManagedIdentityCredential` for production)\n- [ ] Link to `\u002Freferences\u002Fauth-strategies.md` or official docs for production credential selection\n\n**4c. Run Vally lint\u002Feval (if the skill has a spec under `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fvally\u002F`):**\n\n```bash\n# If the eval spec uses the shared Rust custom grader plugin, build it first.\n(cd tests\u002Fscenarios\u002F_shared\u002Fvally\u002Fgrader-plugins\u002Frust-cargo-build-failure && npm install && npm run build)\n\nvally lint --eval-spec tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fvally\u002Feval.yaml \\\n  --grader-plugin tests\u002Fscenarios\u002F_shared\u002Fvally\u002Fgrader-plugins\u002Frust-cargo-build-failure \\\n  --strict\n\nvally eval --eval-spec tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fvally\u002Feval.yaml \\\n  --grader-plugin tests\u002Fscenarios\u002F_shared\u002Fvally\u002Fgrader-plugins\u002Frust-cargo-build-failure\n```\n\n- [ ] `vally lint` passes with no errors\n- [ ] `vally eval` passes (no error-severity findings) when `COPILOT_TOKEN` is available; otherwise lint-only is acceptable, matching the [`Vally Evaluation`](..\u002F..\u002Fworkflows\u002Fvally-evaluation.yml) workflow behavior\n- [ ] Skills without a `vally\u002F` spec skip this step — it is optional per skill, not required for every skill\n\n**5. Spot check:**\n\n- [ ] Can a user copy the core workflow and run it immediately?\n- [ ] Do all examples follow best practices (context managers, appropriate credentials)?\n- [ ] Are all environment variables documented?\n\n**Output:** After validation, annotate the skill header with measured token count:\n\n```markdown\n# Azure Service SDK\n\n\u003C!-- Token Count: ~1180 (target: 1100, max: 1500) -->\n```\n\n---\n\n### Standard Verb Patterns\n\nAzure SDKs use consistent verbs across all languages:\n\n| Verb     | Behavior                     |\n| -------- | ---------------------------- |\n| `create` | Create new; fail if exists   |\n| `upsert` | Create or update             |\n| `get`    | Retrieve; error if missing   |\n| `list`   | Return collection            |\n| `delete` | Succeed even if missing      |\n| `begin`  | Start long-running operation |\n\n### Language-Specific Patterns\n\nSee `references\u002Fazure-sdk-patterns.md` for detailed patterns including:\n\n- **Python**: `ItemPaged`, `LROPoller`, context managers, Sphinx docstrings. When the SDK provides both sync and async clients, present both forms as first-class options; do not express a preference for either. When the SDK is sync-only or async-only, document the available mode only. Do not mix sync and async within a single code example. Always show `with` \u002F `async with` context managers.\n- **.NET**: `Response\u003CT>`, `Pageable\u003CT>`, `Operation\u003CT>`, mocking support\n- **Java**: Builder pattern, `PagedIterable`\u002F`PagedFlux`, Reactor types\n- **TypeScript**: `PagedAsyncIterableIterator`, `AbortSignal`, browser considerations\n- **Go**: `context.Context` as first arg, `runtime.Pager[T]` via `New*Pager()` + `More()\u002FNextPage(ctx)`, `runtime.Poller[T]` via `Begin*` + `PollUntilDone(ctx, nil)`, `to.Ptr(...)` helpers, and typed `*azcore.ResponseError`\n- **Rust**: Installation via `cargo add`, dependency rule for `azure_core`, `Response\u003CT>`, `Pager\u003CT>`, `RequestContent::from()`, `.into_model()`, explicit credential types, RBAC roles for Entra ID authentication\n\n### Required Best Practices in Every Skill (User-Facing)\n\n#### Python, .NET, Java, TypeScript, and Go languages\n\n**These two rules are not just authoring conventions for the skill itself — they MUST be explicitly written into every generated skill's `## Best Practices` section so end users who follow the skill apply them in their own code.**\n\nAdd both items verbatim (adapted only for language\u002FSDK specifics) as the **first two items** of the Best Practices list. Do not assume users will infer them from examples.\n\n**Standard wording (Python; adapt for other languages):**\n\n```markdown\n1. **Do not mix sync and async clients in the same call path.** Use either `azure.xxx` sync clients or `azure.xxx.aio` async clients within a single call path — do not combine both.\n2. **Always use context managers for clients and async credentials.** Wrap every client in `with Client(...) as client:` (sync) or `async with Client(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up.\n3. **Use `DefaultAzureCredential`** for code that runs locally. For code that runs in Azure, either constrain `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS=prod` (or a specific target credential) or use a specific token credential directly (e.g. `ManagedIdentityCredential`, `WorkloadIdentityCredential`).\n```\n\n**Variants to apply when the SDK shape differs:**\n\n| Skill type                                                                    | Adjust item #1 to                                                                                                                   | Adjust item #2 to                                                                                                                                                                                                              |\n| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Async-only SDK (e.g. voicelive)                                               | \"This SDK is async-only; use the `.aio` namespace throughout.\"                                                                      | keep standard                                                                                                                                                                                                                  |\n| Framework guidance that is async-oriented (for example some agent frameworks) | \"Use the framework's documented async patterns where required, but do not claim async is globally preferred for Azure Python SDKs.\" | keep standard                                                                                                                                                                                                                  |\n| Provider-pattern (OpenTelemetry exporters\u002Fdistro)                             | keep standard                                                                                                                       | \"Call `provider.shutdown()` \u002F `flush()` at process exit to flush telemetry — providers are not context managers.\"                                                                                                              |\n| REST-over-httpx skills                                                        | keep standard                                                                                                                       | \"Use `with httpx.Client(...) as client:` (sync) or `async with httpx.AsyncClient(...) as client:` (async) so connections pool and close deterministically.\"                                                                    |\n| Identity skill                                                                | keep standard                                                                                                                       | \"Use credentials as context managers (`with DefaultAzureCredential() as credential:`) when they own token caches \u002F HTTP transports you want cleaned up; for async, use `async with` on credentials from `azure.identity.aio`.\" |\n| FastAPI (non-Azure)                                                           | \"Pick `def` or `async def` per endpoint based on whether you call async I\u002FO; do not mix sync and blocking calls in one handler.\"    | \"Manage long-lived resources (DB pools, HTTP clients) in `lifespan` and inject via `Depends`; use `with`\u002F`async with` for per-request resources.\"                                                                              |\n| Pure model\u002Fschema skill (no I\u002FO, e.g. pydantic)                               | **skip both** — not applicable                                                                                                      | **skip**                                                                                                                                                                                                                       |\n\n**Enforcement in code examples.** Every code example inside the skill must itself obey both rules, so the skill demonstrates what it prescribes:\n\n- Do not interleave sync and async calls within a single example. When the SDK provides both sync and async clients, show each mode in its own complete, self-contained example — a `### Sync` subsection and an `### Async` subsection — giving both equal prominence. When the SDK is sync-only or async-only, show only the available mode.\n- Every client instantiation in every example must be wrapped in `with` \u002F `async with`. The only permitted exception is the mandatory Authentication snippet (which illustrates the credential + client construction pattern) and framework lifespan patterns where a client is owned by the app (e.g. FastAPI `lifespan`).\n- When async credentials from `azure.identity.aio` appear in an example, wrap them in `async with credential:` alongside the client.\n\n#### Rust Language\n\n**These rules MUST be explicitly written into every Rust skill's `## Best Practices` section as the first items:**\n\n1. **Use `cargo add` to manage dependencies, never edit `Cargo.toml` directly.** Always use `cargo add \u003Ccrate>` or `cargo remove \u003Ccrate>` instead of manually modifying the manifest file. Official crates are published on crates.io and should be added via cargo.\n\n2. **Add `azure_core` to `Cargo.toml` only when you import `azure_core` types directly.** If your code imports types like `azure_core::http::Url`, `azure_core::http::RequestContent`, or `azure_core::error::ErrorKind`, explicitly add `azure_core` to your dependencies. If you only use types re-exported by service crates (e.g., via `use azure_storage_blob::BlobClient`), a direct `azure_core` dependency is optional.\n\n3. **Use `DeveloperToolsCredential` for local development and `ManagedIdentityCredential` for production.** The Rust SDK does not support `DefaultAzureCredential`, so explicitly use the appropriate credential in each environment.\n\n4. **Use `RequestContent::from()` to wrap upload data.** When uploading data (e.g., blobs), wrap the content in `RequestContent::from(your_data)` to ensure proper handling by the SDK.\n\n5. **Assign appropriate RBAC roles for Entra ID auth.** For production authentication using Entra ID, ensure the identity has the necessary RBAC role assigned (e.g., \"Storage Blob Data Contributor\" for blob write access).\n\n6. **Always verify package versions using crates.io.** Before using a package, check its version on [crates.io](https:\u002F\u002Fcrates.io\u002F) to ensure you are using a stable and supported release.\n\n7. **Future-proof `#[non_exhaustive]` model structs and enums.** Azure Rust SDK request\u002Fresponse models are frequently `#[non_exhaustive]`. For **externally constructible** structs that also derive `Default`, end the initializer with `..Default::default()` (even if every currently known field is set), suppressing the lint locally with `#[allow(clippy::needless_update)]` when needed. For **truly `#[non_exhaustive]`** structs (where Rust forbids external struct literals, producing E0639), use the provided constructor or builder, or construct a default value first and then mutate the fields you need. When matching an SDK enum, include a wildcard (`_`) arm so future service-added variants do not break the match. If a skill documents model construction, its code examples MUST demonstrate this pattern. See `references\u002Fazure-sdk-patterns.md` (Model Types) for the full example.\n\n### Example Effective Skills (Benchmark Only Structure-Compliant Skills)\n\n**Only benchmark Azure SDK skills that already use the required `references\u002F` layout** (`references\u002Fcapabilities.md` plus `references\u002Fnon-hero-scenarios.md`). Older skills that predate that structure can still be useful for style ideas, but do not mirror them directly until they are brought into compliance.\n\n**A valid benchmark skill should**:\n\n1. Stay at or under the 1,500-token absolute max (see Token Budget Guidelines above)\n2. Cover the hero workflow (CRUD or primary operations), not every feature variant\n3. Show 1-2 examples per concept, not 3-5\n4. Use tables for API summary (credential types, RBAC roles, client hierarchy)\n5. Link to official docs via `microsoft-docs` MCP instead of duplicating\n6. Move advanced patterns to `\u002Freferences\u002F`\n7. Include `references\u002Fcapabilities.md` and `references\u002Fnon-hero-scenarios.md`\n\n**Before writing your skill**: Apply the checklist above directly, then mirror only the structure patterns that fit your use case.\n\n---\n\n### Handling Deprecated or Rebranded SDKs\n\nWhen an Azure SDK has been deprecated or rebranded, update skills to guide users toward the current package while maintaining backward compatibility:\n\n**1. Add a migration notice at the top of the skill:**\n\n```markdown\n> **⚠️ MIGRATION NOTICE**: The [Old Service Name] has been rebranded to **[New Service Name]**. While the package `old-package-name` remains available for compatibility, **new projects should use `new-package-name`** which provides the latest features and updates.\n>\n> **For new projects**: Use the `new-package-name` package instead.\n>\n> **This skill remains valid** for existing projects using `old-package-name`, but be aware you're using the legacy package name. The API patterns shown here are compatible with both packages.\n```\n\n**2. Show both installation options:**\n\n```markdown\n## Installation\n\n### Legacy Package (Old Name)\n\n\\`\\`\\`xml\n\u003Cdependency>\n\u003CgroupId>com.azure\u003C\u002FgroupId>\n\u003CartifactId>azure-old-package\u003C\u002FartifactId>\n\u003Cversion>4.2.0\u003C\u002Fversion>\n\u003C\u002Fdependency>\n\\`\\`\\`\n\n### Recommended Package (New Name)\n\n**For new projects, use the rebranded package:**\n\n\\`\\`\\`xml\n\u003Cdependency>\n\u003CgroupId>com.azure\u003C\u002FgroupId>\n\u003CartifactId>azure-new-package\u003C\u002FartifactId>\n\u003Cversion>1.0.0\u003C\u002Fversion>\n\u003C\u002Fdependency>\n\\`\\`\\`\n\n> **Note**: The API patterns in this skill apply to both packages. Replace package names and imports as needed when using `azure-new-package`.\n```\n\n**3. When to create a new skill vs. update existing:**\n\n- **Update existing skill** if the API is largely compatible (same or similar class\u002Fmethod names)\n- **Create new skill + migration guide** if the API changed significantly (use `references\u002Fmigration.md`)\n- **Always cross-reference** between old and new skills\n\n**Examples:**\n\n- `azure-ai-formrecognizer-java` → `azure-ai-documentintelligence` (rebranded service)\n- `azure-communication-callingserver-java` → `azure-communication-callautomation` (deprecated, with migration guide)\n\n### Example: Azure SDK Skill Structure\n\n```markdown\n---\nname: skill-creator\ndescription: |\n  Azure AI Example SDK for Python. Use for [specific service features].\n  Triggers: \"example service\", \"create example\", \"list examples\".\n---\n\n# Azure AI Example SDK\n\n## Installation\n\n\\`\\`\\`bash\npip install azure-ai-example\n\\`\\`\\`\n\n## Environment Variables\n\n\\`\\`\\`bash\nAZURE_EXAMPLE_ENDPOINT=https:\u002F\u002F\u003Cresource>.example.azure.com\nAZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production\n\\`\\`\\`\n\n## Authentication & Lifecycle\n\n> **? Two rules apply to every code sample below:**\n>\n> 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI \u002F VS Code \u002F Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account\u002FAPI keys — they bypass Entra audit and rotation.\n>    - Local dev: `DefaultAzureCredential` works as-is.\n>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>`) to constrain the credential chain to production-safe credentials.\n> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:\n>    - Sync: `with \u003CClient>(...) as client:`\n>    - Async: `async with \u003CClient>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)\n>\n> Snippets may abbreviate this setup, but production code should always follow both rules.\n\n\\`\\`\\`python\nfrom azure.identity import DefaultAzureCredential, ManagedIdentityCredential\nfrom azure.ai.example import ExampleClient\n\n# Local dev: DefaultAzureCredential works as-is.\ncredential = DefaultAzureCredential()\n\n# Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS.\n# credential = DefaultAzureCredential(require_envvar=True)\n\n# Or use a specific credential directly in production:\n\n# See https:\u002F\u002Flearn.microsoft.com\u002Fpython\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-python#credential-classes\n\n# credential = ManagedIdentityCredential()\n\nwith ExampleClient(\nendpoint=os.environ[\"AZURE_EXAMPLE_ENDPOINT\"],\ncredential=credential,\n) as client:\nitem = client.get_item(\"example\")\n\\`\\`\\`\n\n## Core Workflow\n\n\\`\\`\\`python\nwith ExampleClient(endpoint=endpoint, credential=credential) as client: # Create\nitem = client.create_item(name=\"example\", data={...})\n\n    # List (pagination handled automatically)\n    for item in client.list_items():\n        print(item.name)\n\n    # Long-running operation\n    poller = client.begin_process(item.id)\n    result = poller.result()\n\n    # Cleanup\n    client.delete_item(item.id)\n\n\\`\\`\\`\n\n## Reference Files\n\n| File                                                                 | Contents                                               |\n| -------------------------------------------------------------------- | ------------------------------------------------------ |\n| [references\u002Fcapabilities.md](references\u002Fcapabilities.md)             | Capability index (hero coverage + links to deep-dives) |\n| [references\u002Fnon-hero-scenarios.md](references\u002Fnon-hero-scenarios.md) | Concrete non-hero examples                             |\n| [references\u002Ftools.md](references\u002Ftools.md)                           | Tool integrations                                      |\n| [references\u002Fstreaming.md](references\u002Fstreaming.md)                   | Event streaming patterns                               |\n```\n\n---\n\n## Skill Creation Process\n\n1. **Gather SDK Context** — User provides SDK\u002FAPI reference (REQUIRED)\n2. **Understand** — Research SDK patterns from official docs\n3. **Plan** — Identify reusable resources and product area category\n4. **Create** — Write SKILL.md in `.github\u002Fskills\u002F\u003Cskill-name>\u002F`\n5. **Categorize** — Create symlink in `skills\u002F\u003Clanguage>\u002F\u003Ccategory>\u002F`\n6. **Test** — Create acceptance criteria and test scenarios\n7. **Document** — Update README.md skill catalog\n8. **Iterate** — Refine based on real usage\n\n### Step 1: Gather SDK Context (REQUIRED)\n\n**Before creating any SDK skill, the user MUST provide:**\n\n| Required                  | Example                                                   | Purpose                  |\n| ------------------------- | --------------------------------------------------------- | ------------------------ |\n| **SDK Package**           | `azure-ai-agents`, `Azure.AI.OpenAI`, `azblob`            | Identifies the exact SDK |\n| **Documentation URL**     | `https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Fai-services\u002F...` | Primary source of truth  |\n| **Repository** (optional) | `Azure\u002Fazure-sdk-for-python`, `Azure\u002Fazure-sdk-for-go`    | For code patterns        |\n\n**Prompt the user if not provided:**\n\n```\nTo create this skill, I need:\n1. The SDK package name (e.g., azure-ai-projects)\n2. The Microsoft Learn documentation URL or GitHub repo\n3. The target language (py\u002Fdotnet\u002Fts\u002Fjava\u002Fgo)\n```\n\n**Search official docs first:**\n\n```bash\n# Use microsoft-docs MCP to get current API patterns\n# Query: \"[SDK name] [operation] [language]\"\n# Verify: Parameters match the latest SDK version\n```\n\n### Step 2: Understand the Skill\n\nGather concrete examples:\n\n- \"What SDK operations should this skill cover?\"\n- \"What triggers should activate this skill?\"\n- \"What errors do developers commonly encounter?\"\n\n| Example Task               | Reusable Resource              |\n| -------------------------- | ------------------------------ |\n| Same auth code each time   | Code example in SKILL.md       |\n| Complex streaming patterns | `references\u002Fstreaming.md`      |\n| Tool configurations        | `references\u002Ftools.md`          |\n| Error handling patterns    | `references\u002Ferror-handling.md` |\n\n### Step 3: Plan Product Area Category\n\nSkills are organized by **language** and **product area** in the `skills\u002F` directory via symlinks.\n\n**Product Area Categories:**\n\n| Category      | Description                             | Examples                                     |\n| ------------- | --------------------------------------- | -------------------------------------------- |\n| `foundry`     | AI Foundry, agents, projects, inference | `azure-ai-agents-py`, `azure-ai-projects-py` |\n| `data`        | Storage, Cosmos DB, Tables, Data Lake   | `azure-cosmos-py`, `azure-storage-blob-py`   |\n| `messaging`   | Event Hubs, Service Bus, Event Grid     | `azure-eventhub-py`, `azure-servicebus-py`   |\n| `monitoring`  | OpenTelemetry, App Insights, Query      | `azure-monitor-opentelemetry-py`             |\n| `identity`    | Authentication, DefaultAzureCredential  | `azure-identity-py`                          |\n| `security`    | Key Vault, secrets, keys, certificates  | `azure-keyvault-py`                          |\n| `integration` | API Management, App Configuration       | `azure-appconfiguration-py`                  |\n| `compute`     | Batch, ML compute                       | `azure-compute-batch-java`                   |\n| `container`   | Container Registry, ACR                 | `azure-containerregistry-py`                 |\n\n**Determine the category** based on:\n\n1. Azure service family (Storage → `data`, Event Hubs → `messaging`)\n2. Primary use case (AI agents → `foundry`)\n3. Existing skills in the same service area\n\n### Step 4: Create the Skill\n\n**Location:** `.github\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md`\n\n**Naming convention:**\n\n- `azure-\u003Cservice>-\u003Csubservice>-\u003Clanguage>`\n- Examples: `azure-ai-agents-py`, `azure-cosmos-java`, `azure-storage-blob-ts`, `azure-storage-blob-go`\n- For Go skills in documentation prose, use the short package name (for example `azblob`).\n- Use the full module import path only in code\u002Fimport examples (for example `github.com\u002FAzure\u002Fazure-sdk-for-go\u002Fsdk\u002Fstorage\u002Fazblob`).\n\n**For Azure SDK skills:**\n\n1. Search `microsoft-docs` MCP for current API patterns\n2. Verify against installed SDK version\n3. Follow the section order above\n4. Include cleanup code in examples\n5. Add feature comparison tables\n\n**Write bundled resources first**, then SKILL.md.\n\n**Quality assurance before finalizing:**\n\n1. Measure section token counts as you write (use model playground token counter)\n2. Compare to Token Budget Guidelines targets\n3. Validate against anti-patterns checklist (see Anti-Patterns section)\n4. Extract to `\u002Freferences\u002F` if section exceeds max tokens\n5. Run Efficiency Validation checklist, including `vally lint`\u002F`vally eval` if the skill has a spec (see Efficiency Validation)\n6. Optionally add `benchmark_tokens_*` and `benchmark_quality_*` fields under the frontmatter's `metadata` mapping (flat string values)\n7. Add token count comment to skill header for future maintenance\n\n**Frontmatter (Enhanced with Benchmarking Metadata):**\n\n```yaml\n---\nname: azure-service-py\ndescription: |\n  Azure Service SDK for Python. Use for [specific features].\n  Triggers: \"service name\", \"create resource\", \"specific operation\".\nmetadata:\n  benchmark_tokens_estimated: \"1180\"\n  benchmark_tokens_target: \"1100\"\n  benchmark_tokens_max: \"1500\"\n  benchmark_quality_single_core_workflow: \"true\"\n  benchmark_quality_examples_focused: \"true\"\n  benchmark_quality_no_prose_bloat: \"true\"\n  benchmark_quality_anti_patterns_checked: \"true\"\n---\n```\n\n**Metadata fields:** (all values are strings, per the Agent Skills `metadata` spec — string keys mapped to string values)\n\n- `benchmark_tokens_estimated` — Actual measured token count\n- `benchmark_tokens_target` — Target efficiency (typically 1100)\n- `benchmark_tokens_max` — Absolute ceiling (1500; split if exceeded)\n- `benchmark_quality_*` — Individual anti-pattern checks, each a `\"true\"`\u002F`\"false\"` string (e.g., `benchmark_quality_single_core_workflow`)\n\n### Step 5: Categorize with Symlinks\n\nAfter creating the skill in `.github\u002Fskills\u002F`, create a symlink in the appropriate category:\n\n```bash\n# Pattern: skills\u002F\u003Clanguage>\u002F\u003Ccategory>\u002F\u003Cshort-name> -> ..\u002F..\u002F..\u002F.github\u002Fskills\u002F\u003Cfull-skill-name>\n\n# Example for azure-ai-agents-py in python\u002Ffoundry:\ncd skills\u002Fpython\u002Ffoundry\nln -s ..\u002F..\u002F..\u002F.github\u002Fskills\u002Fazure-ai-agents-py agents\n\n# Example for azure-cosmos-db-py in python\u002Fdata:\ncd skills\u002Fpython\u002Fdata\nln -s ..\u002F..\u002F..\u002F.github\u002Fskills\u002Fazure-cosmos-db-py cosmos-db\n\n# Example for azure-storage-blob-go in go\u002Fdata:\ncd skills\u002Fgo\u002Fdata\nln -s ..\u002F..\u002F..\u002F.github\u002Fskills\u002Fazure-storage-blob-go blob\n```\n\n**Symlink naming:**\n\n- Use short, descriptive names (e.g., `agents`, `cosmos`, `blob`)\n- Remove the `azure-` prefix and language suffix\n- Match existing patterns in the category\n\n**Verify the symlink:**\n\n```bash\nls -la skills\u002Fpython\u002Ffoundry\u002Fagents\n# Should show: agents -> ..\u002F..\u002F..\u002F.github\u002Fskills\u002Fazure-ai-agents-py\n```\n\n### Step 6: Create Tests\n\n**Every skill MUST have acceptance criteria and test scenarios.**\n\n#### 6.1 Create Acceptance Criteria\n\n**Location:** `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Facceptance-criteria.md`\n\n> Keep acceptance criteria in the `tests\u002F` tree (never beside `SKILL.md` inside the skill folder).\n\n**Source materials** (in priority order):\n\n1. Official Microsoft Learn docs (via `microsoft-docs` MCP)\n2. SDK source code from the repository\n3. Existing reference files in the skill\n\n**Format:**\n\n```markdown\n# Acceptance Criteria: \u003Cskill-name>\n\n**SDK**: `package-name`\n**Repository**: https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-\u003Clanguage>\n**Purpose**: Skill testing acceptance criteria\n\n---\n\n## 1. Correct Import Patterns\n\n### 1.1 Client Imports\n\n#### ✅ CORRECT: Main Client\n\n\\`\\`\\`python\nfrom azure.ai.mymodule import MyClient\nfrom azure.identity import DefaultAzureCredential\n\\`\\`\\`\n\n#### ❌ INCORRECT: Wrong Module Path\n\n\\`\\`\\`python\nfrom azure.ai.mymodule.models import MyClient # Wrong - Client is not in models\n\\`\\`\\`\n\n## 2. Authentication Patterns\n\n#### ✅ CORRECT: DefaultAzureCredential + context manager\n\n\\`\\`\\`python\ncredential = DefaultAzureCredential()\nwith MyClient(endpoint, credential) as client:\nclient.do_thing()\n\\`\\`\\`\n\n#### ❌ INCORRECT: Hardcoded Credentials\n\n\\`\\`\\`python\nclient = MyClient(endpoint, api_key=\"hardcoded\") # Security risk\n\\`\\`\\`\n\n#### ❌ INCORRECT: Connection string \u002F account key when Entra is supported\n\n\\`\\`\\`python\nclient = MyClient.from_connection_string(os.environ[\"CONNECTION_STRING\"]) # Bypasses Entra audit\u002Frotation\n\\`\\`\\`\n\n#### ❌ INCORRECT: Bare client without context manager\n\n\\`\\`\\`python\nclient = MyClient(endpoint, credential) # Leaks HTTP transport on exception \u002F interpreter exit\nclient.do_thing()\n\\`\\`\\`\n```\n\n**Critical patterns to document:**\n\n- Import paths (these vary significantly between Azure SDKs)\n- Authentication patterns\n- Client initialization\n- Async variants (`.aio` modules)\n- Common anti-patterns\n\n#### 6.2 Create Test Scenarios\n\n**Location:** `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fscenarios.yaml`\n\n```yaml\nconfig:\n  model: gpt-4\n  max_tokens: 2000\n  temperature: 0.3\n\nscenarios:\n  - name: basic_client_creation\n    prompt: |\n      Create a basic example using the Azure SDK.\n      Include proper authentication and client initialization.\n    expected_patterns:\n      - \"DefaultAzureCredential\"\n      - \"MyClient\"\n      - \"with MyClient\" # enforce context manager\n    forbidden_patterns:\n      - \"api_key=\"\n      - \"hardcoded\"\n      - \"from_connection_string\" # prefer Entra over connection strings\n    tags:\n      - basic\n      - authentication\n    mock_response: |\n      import os\n      from azure.identity import DefaultAzureCredential\n      from azure.ai.mymodule import MyClient\n\n      credential = DefaultAzureCredential()\n      with MyClient(\n          endpoint=os.environ[\"AZURE_ENDPOINT\"],\n          credential=credential,\n      ) as client:\n          # ... rest of working example\n          pass\n```\n\n**Scenario design principles:**\n\n- Each scenario tests ONE specific pattern or feature\n- `expected_patterns` — patterns that MUST appear\n- `forbidden_patterns` — common mistakes that must NOT appear\n- `mock_response` — complete, working code that passes all checks\n- `tags` — for filtering (`basic`, `async`, `streaming`, `tools`)\n\n#### 6.3 Run Tests\n\n```bash\ncd tests\npnpm install\n\n# Check skill is discovered\npnpm harness --list\n\n# Run in mock mode (fast, deterministic)\npnpm harness \u003Cskill-name> --mock --verbose\n\n# Run with Ralph Loop (iterative improvement)\npnpm harness \u003Cskill-name> --ralph --mock --max-iterations 5 --threshold 85\n```\n\n**Success criteria:**\n\n- All scenarios pass (100% pass rate)\n- No false positives (mock responses always pass)\n- Patterns catch real mistakes\n\n### Step 7: Update Documentation\n\nAfter creating the skill:\n\n1. **Update README.md** — Add the skill to the appropriate language section in the Skill Catalog\n   - Update total skill count (line ~73: `> N skills in...`)\n   - Update Skill Explorer link count (line ~15: `Browse all N skills`)\n   - Update language count table (lines ~77-83)\n   - Update language section count (e.g., `> N skills • suffix: -py`)\n   - Update category count (e.g., `\u003Csummary>\u003Cstrong>Foundry & AI\u003C\u002Fstrong> (N skills)\u003C\u002Fsummary>`)\n   - Add skill row in alphabetical order within its category\n   - Update test coverage summary (line ~622: `**N skills with N test scenarios**`)\n   - Update test coverage table — update skill count, scenario count, and top skills for the language\n\n2. **Regenerate GitHub Pages data** — Run the extraction script and rebuild the docs site from one scoped directory change\n\n   ```bash\n   (cd docs-site && npx tsx scripts\u002Fextract-skills.ts && npm run build)\n   ```\n\n   This updates `docs-site\u002Fsrc\u002Fdata\u002Fskills.json` which feeds the Astro-based docs site, then rebuilds the site into `docs\u002F`, which is served by GitHub Pages.\n\n3. **Verify AGENTS.md** — Ensure the skill count is accurate\n\n---\n\n### Step 8: Regenerate Existing Skills from Latest SDK Sources\n\nUse this workflow when an existing skill has stale examples, outdated API signatures,\nor changed package guidance.\n\n1. **Identify canonical source files first**\n\nFor Azure SDK language skills, use official upstream source docs and examples as the source of truth:\n\n- Go: `https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-go\u002Ftree\u002Fmain\u002Fsdk\u002F\u003Cservice>\u002F\u003Cmodule>\u002FREADME.md`\n- Go examples: `https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-go\u002Ftree\u002Fmain\u002Fsdk\u002F\u003Cservice>\u002F\u003Cmodule>\u002F`\n- Rust: `https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-rust\u002Ftree\u002Fmain\u002Fsdk\u002F\u003Cservice>\u002F\u003Ccrate>\u002FREADME.md`\n- Rust examples: `https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-rust\u002Ftree\u002Fmain\u002Fsdk\u002F\u003Cservice>\u002F\u003Ccrate>\u002Fexamples\u002F`\n- .NET\u002FJava\u002FPython\u002FTS\u002FGo: use current Microsoft Learn package docs + official SDK repos\n\n2. **Refresh skill content surgically**\n\n- Update code snippets to match current constructor\u002Fmethod signatures\n- Keep crate\u002Fpackage names aligned with official publisher guidance\n- Preserve skill structure\u002Ffrontmatter unless intentionally changing behavior\n- Update \"Best Practices\" and \"Reference Links\" when upstream recommendations change\n- For Rust, if code uses `azure_core` types\u002Fimports directly, ensure `azure_core` is present in `Cargo.toml`; if only service-crate re-exports are used, direct `azure_core` dependency is optional\n\n### API Surface Parity Gate (required for every regenerated skill)\n\nUse the language-specific authoritative source as the contract for every snippet in the regenerated skill:\n\n- **Python, .NET, Java, TypeScript, Go**: Treat the current Microsoft Learn API reference as the contract.\n- **Rust**: Treat the official SDK repository (`https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-rust`) and crates.io documentation as the contract; Rust packages do not have Learn API-reference pages.\n\nBefore finalizing any regenerated skill:\n\n1. Identify each SDK type\u002Fmethod shown in snippets (clients, operation groups, model constructors, enum members, long-running methods like `begin_*`).\n2. Verify each symbol and signature against the authoritative source for that language\u002Fpackage (see above).\n3. If the authoritative source shows a different shape (for example nested `properties=...` models, renamed methods, `begin_*` LRO methods), update the snippet to match.\n4. Re-check imports so model\u002Fclient modules match the authoritative source exactly.\n5. Do not keep compatibility shortcuts that contradict authoritative examples in primary snippets.\n\n### Scenario Coverage Gate (required for every regenerated skill, all languages)\n\nRegeneration is not complete when snippets compile — it is complete when the skill demonstrates real usage breadth.\n\nBefore finalizing any regenerated skill:\n\n1. Identify **hero scenarios** from the current authoritative docs\u002Fsamples for that SDK (Microsoft Learn where available; otherwise the upstream SDK repo and package documentation).\n2. Ensure each hero scenario is represented in the skill with copy-pastable snippets (or an explicit link to a bundled reference file when too large).\n3. Add\u002Frefresh test scenarios so hero flows are validated by harness patterns.\n4. Add at least **one important non-hero scenario** (for example: update\u002Fpatch, delete\u002Fcleanup, export\u002Fimport, advanced auth mode, paging\u002Ffiltering, retries\u002Ferror handling, or LRO monitoring) when supported by the SDK. For Python SDKs that support both sync and async clients, present both forms with equal priority; do not treat either as universally preferred.\n5. For Azure SDK skills, structure `references\u002F` as:\n   - `references\u002Fcapabilities.md` as a concise index that records each hero scenario and where it is covered (`SKILL.md` or a bundled reference), plus links to deeper non-hero references, with no historical\u002Fmigration narration.\n   - `references\u002Fnon-hero-scenarios.md` for concrete non-hero examples that are intentionally kept out of the main `SKILL.md`.\n   - Additional `references\u002F*.md` files for specialized deep-dives (operation groups, tools, evaluator matrices, etc.).\n6. If the SDK has broad operation-group coverage (common in management SDKs), include an operation-group table and explicitly call out which groups are covered in snippets vs. referenced only.\n7. Never claim \"full API surface\" unless the skill genuinely demonstrates all major operation groups; otherwise state that the skill is optimized for hero workflows plus selected secondary scenarios.\n\n### Regeneration Workflow Step 3: Validate Regenerated Skill Behavior\n\n```bash\n(cd tests && pnpm harness \u003Cskill-name> --mock --verbose)\n```\n\nIf the skill has a Vally scenario, run that eval as well (locally or in CI) before finalizing.\n\n**Rust regeneration gate (required for Rust skills):**\n\nWhen regenerating any Rust skill, verify the generated `## Best Practices` section contains these exact first two rules:\n\n1. `Use cargo add to manage dependencies, never edit Cargo.toml directly`\n2. `Add azure_core only when importing azure_core types directly`\n\nUse a content check before finalizing:\n\n```bash\nrg -n \"Use `cargo add` to manage dependencies, never edit `Cargo.toml` directly|Add `azure_core` only when importing `azure_core` types directly\" .github\u002Fplugins\u002Fazure-sdk-rust\u002Fskills\u002F**\u002FSKILL.md\n```\n\nThe regeneration is not complete unless both lines are present in each affected Rust skill.\n\n### Regeneration Workflow Step 4: Regenerate Docs Artifacts After Refresh\n\n```bash\n(cd docs-site && npx tsx scripts\u002Fextract-skills.ts && npm run build)\n```\n\n### Regeneration Workflow Step 5: Record What Changed\n\nIn the PR\u002Fcommit notes, include:\n\n- Which upstream docs\u002Fexamples were used\n- Which snippets\u002Fsignatures were corrected\n- Which tests\u002Fevals were run and their outcomes\n\n#### Python plugin batch recipe: `azure-sdk-python`\n\nUse this when the request is \"regenerate all Python skills under azure-sdk-python.\"\n\n1. **Scope the exact targets first**\n\n```bash\n# Canonical source of truth for Python plugin skills\nls .github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002F*\u002FSKILL.md\n```\n\n- Treat `.github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002F` as canonical.\n- Keep `.github\u002Fskills\u002F\u003Cname>` links in sync after edits (symlink check\u002Ffix step below).\n\n2. **For each skill, refresh from authoritative sources**\n\n- Always use `microsoft-docs` MCP first for current Microsoft Learn API guidance.\n- Verify the installed package version with `pip show \u003Cpackage>`, then inspect the installed package or official API reference to verify every symbol and signature used in snippets.\n- For Azure SDK skills, prefer package overview + official SDK repo examples.\n- For non-Azure Python skills in this plugin (for example `fastapi-router-py`, `pydantic-models-py`), keep language-specific best-practice variants and skip Azure-specific auth callouts when lifecycle\u002Fauth is not applicable.\n\n3. **Apply Python enforcement rules consistently**\n\n- Keep the standard section order for Azure SDK Python skills.\n- Ensure `## Authentication & Lifecycle` starts with the required callout block (verbatim) when applicable.\n- Ensure every client example uses `with` \u002F `async with` lifecycle patterns.\n- Ensure `## Best Practices` starts with the two required user-facing rules (or the documented variant for async-only\u002Fprovider-pattern skills).\n- Ensure each regenerated Azure SDK Python skill has `references\u002Fcapabilities.md` (index) and `references\u002Fnon-hero-scenarios.md` (concrete non-hero examples).\n- Keep existing references\u002Fassets\u002Fscripts unless stale or incorrect.\n\n4. **Validate all regenerated Python skills**\n\n```bash\n# Fast frontmatter\u002Fstructure validation for every Python skill\npython .github\u002Fskills\u002Fskill-creator\u002Fscripts\u002Fquick_validate.py .github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002F\u003Cskill-name>\n\n# Run Python skill harness in mock mode (all *-py scenarios)\n(cd tests && pwsh .\u002Frun-harness-by-language.ps1 -Language py -Mock)\n```\n\n5. **Sync skill links and docs artifacts**\n\n```bash\n# Ensure .github\u002Fskills links point at plugin canonical skills\npython .github\u002Fscripts\u002Fsync_skill_links.py --plugin azure-sdk-python --check\npython .github\u002Fscripts\u002Fsync_skill_links.py --plugin azure-sdk-python --apply\n\n# Refresh docs site data after content changes\n(cd docs-site && npx tsx scripts\u002Fextract-skills.ts && npm run build)\n```\n\n6. **Completion criteria for batch regeneration**\n\n- Every targeted `.github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002F*\u002FSKILL.md` is updated or explicitly confirmed current.\n- Harness mock run for `-py` skills passes without regressions.\n- Skill links are in sync for `azure-sdk-python`.\n- PR notes include upstream docs used, signature corrections, and validation outcomes.\n\n---\n\n## Progressive Disclosure Patterns\n\n### Pattern 1: High-Level Guide with References\n\n```markdown\n# SDK Name\n\n## Quick Start\n\n[Minimal example]\n\n## Advanced Features\n\n- **Streaming**: See [references\u002Fstreaming.md](references\u002Fstreaming.md)\n- **Tools**: See [references\u002Ftools.md](references\u002Ftools.md)\n```\n\n### Pattern 2: Language Variants\n\n```\nazure-service-skill\u002F\n├── SKILL.md (overview + language selection)\n└── references\u002F\n    ├── python.md\n    ├── dotnet.md\n    ├── go.md\n    ├── java.md\n    └── typescript.md\n```\n\n### Pattern 3: Feature Organization\n\n```\nazure-ai-agents\u002F\n├── SKILL.md (core workflow)\n└── references\u002F\n    ├── tools.md\n    ├── streaming.md\n    ├── async-patterns.md\n    └── error-handling.md\n```\n\n---\n\n## Design Pattern References\n\n| Reference                          | Contents                             |\n| ---------------------------------- | ------------------------------------ |\n| `references\u002Fworkflows.md`          | Sequential and conditional workflows |\n| `references\u002Foutput-patterns.md`    | Templates and examples               |\n| `references\u002Fazure-sdk-patterns.md` | Language-specific Azure SDK patterns |\n\n---\n\n## Anti-Patterns\n\n| Don't                                                                          | Why                                                                                 |\n| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |\n| Create skill without SDK context                                               | Users must provide package name\u002Fdocs URL                                            |\n| Put \"when to use\" in body                                                      | Body loads AFTER triggering                                                         |\n| Hardcode credentials                                                           | Security risk                                                                       |\n| Skip authentication section                                                    | Agents will improvise poorly                                                        |\n| Use outdated SDK patterns                                                      | APIs change; search docs first                                                      |\n| Include README.md                                                              | Agents don't need meta-docs                                                         |\n| Deeply nest references                                                         | Keep one level deep                                                                 |\n| Skip acceptance criteria                                                       | Skills without tests can't be validated                                             |\n| Skip symlink categorization                                                    | Skills won't be discoverable by category                                            |\n| Use wrong import paths                                                         | Azure SDKs have specific module structures                                          |\n| Omit sync\u002Fasync + context-manager bullets from Best Practices in Python skills | End users won't follow rules that aren't written down; examples alone aren't enough |\n| Mix sync and async in the same Python example                                  | Demonstrates the anti-pattern the skill is supposed to prevent                      |\n| Ship regenerated skills with zero test scenarios                               | Hero workflows and regressions cannot be validated                                  |\n| Claim full API coverage from a single happy-path sample                        | Hides operation-group and non-hero gaps users need for production                   |\n| Omit `references\u002F*.md` coverage for non-hero capabilities                      | Forces advanced capabilities out of context and leaves API breadth undocumented     |\n\n---\n\n## Checklist\n\nBefore completing a skill:\n\n**Prerequisites:**\n\n- [ ] User provided SDK package name or documentation URL\n- [ ] Verified SDK patterns via `microsoft-docs` MCP\n- [ ] Verified every snippet's API surface against the current official language-specific API reference for that SDK (Microsoft Learn where available, otherwise the upstream SDK repo — see canonical sources above)\n\n**Skill Creation:**\n\n- [ ] Description includes what AND when (trigger phrases)\n- [ ] SKILL.md under 500 lines\n- [ ] Authentication follows language rules (`DefaultAzureCredential` for Python\u002F.NET\u002FJava\u002FTS\u002FGo local dev; `DeveloperToolsCredential` local dev + `ManagedIdentityCredential` production for Rust)\n- [ ] Includes cleanup\u002Fdelete in examples\n- [ ] References organized by feature (`capabilities.md` index + dedicated deep-dive files)\n- [ ] Hero scenarios from the current authoritative docs\u002Fsamples for that SDK are explicitly covered in snippets and tests\n- [ ] At least one high-value non-hero scenario is included when the SDK supports a distinct non-hero scenario (otherwise note that no distinct non-hero scenario applies)\n- [ ] For Azure SDK skills, `references\u002Fcapabilities.md` indexes hero\u002Fnon-hero coverage and links to dedicated non-hero docs\n- [ ] For Azure SDK skills, `references\u002Fnon-hero-scenarios.md` contains concrete non-hero examples distinct from hero snippets\n- [ ] For broad SDKs (especially management SDKs), operation-group coverage is explicit (covered in snippets vs. reference-only)\n- [ ] **(Python skills only) Best Practices section contains the two user-facing rules** (sync-or-async consistency + context managers for clients and async credentials), using the variant matched to the skill type\n- [ ] For Rust skills: `## Best Practices` starts with cargo dependency rule + `azure_core` direct-import rule\n\n**Categorization:**\n\n- [ ] Skill created in `.github\u002Fskills\u002F\u003Cskill-name>\u002F`\n- [ ] Symlink created in `skills\u002F\u003Clanguage>\u002F\u003Ccategory>\u002F\u003Cshort-name>`\n- [ ] Symlink points to `..\u002F..\u002F..\u002F.github\u002Fskills\u002F\u003Cskill-name>`\n\n**Testing:**\n\n- [ ] `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Facceptance-criteria.md` created with correct\u002Fincorrect patterns\n- [ ] `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fscenarios.yaml` created\n- [ ] At least one hero scenario and one non-hero scenario are test-covered (when the SDK supports both)\n- [ ] All scenarios pass (`pnpm harness \u003Cskill> --mock`)\n- [ ] Import paths documented precisely\n\n**Documentation:**\n\n- [ ] README.md skill catalog updated\n- [ ] Instructs to search `microsoft-docs` MCP for current APIs\n","# Skill Creator\n\nGuide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and Microsoft Foundry.\n\n> **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.\n\n## About Skills\n\nSkills are modular knowledge packages that transform general-purpose agents into specialized experts:\n\n1. **Procedural knowledge** — Multi-step workflows for specific domains\n2. **SDK expertise** — API patterns, authentication, error handling for Azure services\n3. **Domain context** — Schemas, business logic, company-specific patterns\n4. **Bundled resources** — Scripts, references, templates for complex tasks\n\n---\n\n## Core Principles\n\n### 1. Concise is Key\n\nThe context window is a shared resource. Challenge each piece: \"Does this justify its token cost?\"\n\n**For domain\u002Fprocedural skills**: Agents are already capable. Only add what they don't already know.\n\n**For SDK\u002FAPI skills**: Users MUST provide SDK package name, documentation URL, or repository reference. The skill cannot be created without this context.\n\n### 2. Fresh Documentation First\n\n**Azure SDKs change constantly.** Skills should instruct agents to verify documentation:\n\n```markdown\n## Before Implementation\n\nSearch `microsoft-docs` MCP for current API patterns:\n\n- Query: \"[SDK name] [operation] python\"\n- Verify: Parameters match your installed SDK version\n```\n\n### 3. Degrees of Freedom\n\nMatch specificity to implementation constraints. High freedom when approaches vary; low freedom when precise execution is required:\n\n| Freedom    | When                             | Example          |\n| ---------- | -------------------------------- | ---------------- |\n| **High**   | Multiple valid approaches        | Text guidelines  |\n| **Medium** | Preferred pattern with variation | Pseudocode       |\n| **Low**    | Must be exact                    | Specific scripts |\n\n### 4. Progressive Disclosure\n\nSkills load in three levels:\n\n1. **Metadata** (~100 words) — Always in context\n2. **SKILL.md body** (\u003C5k words) — When skill triggers\n3. **References** (unlimited) — As needed\n\n**Keep SKILL.md under 500 lines.** Split into reference files when approaching this limit.\n\n---\n\n## Skill Structure\n\n**Quick reference:**\n\n```\nskill-name\u002F\n├── SKILL.md (required)\n│   ├── YAML frontmatter (name, description)\n│   └── Markdown instructions\n└── Bundled Resources (optional)\n    ├── scripts\u002F      — Executable code\n    ├── references\u002F   — Documentation loaded as needed\n    └── assets\u002F       — Output resources (templates, images)\n```\n\nFor Azure SDK skills, follow the **Skill Section Order** below. For domain skills, use your judgment to organize logically.\n\n### SKILL.md Essentials\n\n- **Frontmatter**: `name` and `description` (description triggers the skill)\n- **Body**: Keep under 500 lines; split large skills into reference files\n\n### Bundled Resources (Optional)\n\n| Type          | When to Include                          | Examples                                                   |\n| ------------- | ---------------------------------------- | ---------------------------------------------------------- |\n| `scripts\u002F`    | Reused code patterns                     | Auth setup, CLI scripts                                    |\n| `references\u002F` | Feature deep-dives and overflow examples | `capabilities.md` index, `non-hero-scenarios.md`, API docs |\n| `assets\u002F`     | Output templates                         | Boilerplate code, images                                   |\n\n---\n\n## Creating Azure SDK Skills\n\nWhen creating skills for Azure SDKs, follow these patterns consistently.\n\n### Token Budget Guidelines (REQUIRED)\n\nEvery Azure SDK skill MUST stay within these token limits:\n\n| Section                       | Target           | Absolute Max     |\n| ----------------------------- | ---------------- | ---------------- |\n| Installation + Env Vars       | 100 tokens       | 150              |\n| Authentication & Lifecycle    | 200 tokens       | 300              |\n| Core Workflow (1 example)     | 300 tokens       | 400              |\n| Feature Tables                | 200 tokens       | 300              |\n| Best Practices (6-8 items)    | 200 tokens       | 250              |\n| References (reference\u002F links) | 100 tokens       | 150              |\n| **Total SKILL.md**            | **~1100 tokens** | **~1500 tokens** |\n\n**Enforcement**:\n\n- Exceeding max limit → refactor into `\u002Freferences\u002F` subdirectories\n- When approaching 500 lines → move entire sections to reference files\n- Annotate with `\u003C!-- Token Count: ~XXXX (target: 1100, max: 1500) -->` immediately below the skill's H1\n\n---\n\n### Reference Extraction Guide (REQUIRED)\n\nDecide what goes in SKILL.md vs. `\u002Freferences\u002F` using these signals:\n\n| Signal         | Move to `\u002Freferences\u002F`              | Keep in SKILL.md       |\n| -------------- | ----------------------------------- | ---------------------- |\n| Use frequency  | \u003C20% of typical use                 | ~80%+ of workflows     |\n| Cognitive load | Advanced patterns, multiple options | Single happy path      |\n| Example length | >10 lines, multiple paths           | 1-5 lines, single path |\n\n**Content extraction rules:**\n\n- **Batch operations** → `\u002Freferences\u002Fbatch-operations.md`\n- **Error handling** (beyond try-except) → `\u002Freferences\u002Ferror-handling.md`\n- **Performance tuning** → `\u002Freferences\u002Fperformance.md`\n- **Alternative workflows** → `\u002Freferences\u002Fworkflows-comparison.md`\n- **Streaming\u002Fevents** → `\u002Freferences\u002Fstreaming.md`\n- **Advanced auth** → `\u002Freferences\u002Fauth-strategies.md`\n- **Tool integration** → `\u002Freferences\u002Ftools.md`\n- **Breaking changes** → `\u002Freferences\u002Fmigration.md`\n\n**Decision:** Keep common case in SKILL.md, move edge cases to `\u002Freferences\u002F`.\n\n---\n\n### Core Workflow Discipline (REQUIRED)\n\nEvery Azure SDK skill must clarify which workflow(s) it documents.\n\n**Case 1: Single clear \"core workflow\"** (majority of services)\n\nIf one pattern handles ~80% of use cases:\n\n1. Designate it as the core workflow\n2. Show ONLY this workflow in SKILL.md (one complete, runnable example)\n3. Defer alternatives to `\u002Freferences\u002F`:\n   - Batch operations → `\u002Freferences\u002Fbatch-operations.md`\n   - Error handling → `\u002Freferences\u002Ferror-handling.md`\n   - Performance tuning → `\u002Freferences\u002Fperformance.md`\n   - Alternative workflows → `\u002Freferences\u002Fworkflows-comparison.md`\n\n**Example**: Azure Key Vault Secrets (core workflow: retrieve a secret using managed identity). Alternative authentication workflows in `\u002Freferences\u002F`: local development with `DefaultAzureCredential`, workload identity, and service-principal credentials (client secret or certificate).\n\n**Case 2: Multiple equally-valid \"core workflows\"** (e.g., authentication strategies, deployment targets)\n\nIf no single pattern dominates:\n\n1. Include every hero scenario in SKILL.md, even when that means multiple equally valid workflows\n2. Show one complete, runnable example for each hero scenario in SKILL.md\n3. Use `\u002Freferences\u002Fworkflows-comparison.md` for trade-offs, secondary variations, and deeper context that would otherwise bloat the main file\n4. Do NOT treat valid alternatives as \"advanced\" when they are core to real usage — they're equally valid, just different contexts\n\n**Example**: Azure Identity SDK has several hero scenarios. Keep the primary local-development and production-safe credential flows in SKILL.md, then use `\u002Freferences\u002Fcredential-types.md` for deeper comparisons across `AzureCliCredential`, workload identity, service principal variants, and other secondary credential choices.\n\n**Decision rule**: If you're unsure, ask: \"Would a user choosing the other approach call what I wrote wrong?\" If yes, it's another hero scenario and belongs in SKILL.md. If no, it can be summarized and linked from `\u002Freferences\u002F`.\n\n---\n\n### Skill Section Order\n\nFollow this structure (based on existing Azure SDK skills):\n\n1. **Title** — `# SDK Name`\n2. **Installation** — `pip install`, `npm install`, etc.\n3. **Environment Variables** — Required configuration, with an inline comment explaining when it's required. If using `DefaultAzureCredential` in production, include `AZURE_TOKEN_CREDENTIALS` (set to `prod` or `\u003Cspecific_credential>`)\n4. **Authentication & Lifecycle** — For Python skills, prefer `DefaultAzureCredential`: use it as-is for local development, and constrain it for production by setting `AZURE_TOKEN_CREDENTIALS` to `prod` (or a specific target credential name). A specific Microsoft Entra Token credential such as `ManagedIdentityCredential` or `WorkloadIdentityCredential` may be used directly instead. **For Python skills, this section MUST start with the standard callout block** (see [Required Authentication & Lifecycle Callout (Python)](#required-authentication--lifecycle-callout-python) below).\n5. **Core Workflow** — Minimal viable example (per core workflow discipline above)\n6. **Feature Tables** — Clients, methods, tools\n7. **Best Practices** — Numbered list\n8. **Reference Links** — Table linking to `\u002Freferences\u002F*.md` (for Azure SDK skills, include `capabilities.md` + `non-hero-scenarios.md`)\n\n### Required Authentication & Lifecycle Callout (Python)\n\n> **Scope:** Python skills (`-py` suffix) only. Other languages may follow their own idioms.\n\nEvery Python Azure SDK skill MUST open its `## Authentication & Lifecycle` section with the following callout block, **verbatim**, before any code samples. This makes the two non-negotiable rules visible to users before they read or copy any client setup code.\n\n```markdown\n## Authentication & Lifecycle\n\n> **? Two rules apply to every code sample below:**\n>\n> 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI \u002F VS Code \u002F Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account\u002FAPI keys — they bypass Entra audit and rotation.\n>    - Local dev: `DefaultAzureCredential` works as-is.\n>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>`) to constrain the credential chain to production-safe credentials.\n> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:\n>    - Sync: `with \u003CClient>(...) as client:`\n>    - Async: `async with \u003CClient>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)\n>\n> Snippets may abbreviate this setup, but production code should always follow both rules.\n```\n\n**Placement rules:**\n\n- Insert immediately under the `## Authentication & Lifecycle` heading, before the first code sample.\n- Do not paraphrase or restructure the wording — the consistency across skills is the point.\n- If the SDK does not support Entra ID at all (rare — e.g. some legacy speech REST endpoints, websocket APIs that require subscription keys), keep rule #2 (context managers) and replace rule #1 with a single sentence noting the SDK requires API-key auth and explaining why Entra is not yet available.\n- If the SDK is async-only (e.g. `azure-ai-voicelive`), keep both rules but show only the async form in the bullets.\n- Skip the callout entirely for non-Azure Python skills with no client lifecycle (e.g. `pydantic-models-py`).\n\n**Code sample enforcement.** Every client construction in the skill body must demonstrate both rules:\n\n- Show `with` \u002F `async with` on every client instantiation in usage examples (not just the auth section).\n- Show `DefaultAzureCredential` in the primary auth example. **Do not delete API-key examples for SDKs where keys are still officially supported** — many existing users (especially in regulated environments still completing their Entra rollout) need a copy-pastable working sample. Demote the keyed snippet into a clearly-labeled `### Legacy: API Key (existing keyed deployments)` subsection placed _after_ the primary `DefaultAzureCredential` block in the same `## Authentication & Lifecycle` section. Include a one-line note that new code should use `DefaultAzureCredential` and that the keyed path is for existing deployments. Also add the `\u003CSERVICE>_KEY` env var back to the Environment Variables block with a `# Only required for the legacy API-key auth path below` comment.\n- A handful of services have key-specific quirks worth calling out in the Legacy subsection (e.g. `azure-ai-translation-text` requires a `region=` parameter when using a key against the global endpoint, because token-credential auth requires a custom subdomain endpoint). Surface these in the demoted block rather than dropping the example.\n- For async examples, wrap `DefaultAzureCredential` from `azure.identity.aio` in `async with credential:` alongside the client.\n\n### Authentication Pattern (All Languages)\n\nFor local development, use `DefaultAzureCredential` which supports multiple auth methods. For production, use a specific credential type or configure `DefaultAzureCredential` with environment variable `AZURE_TOKEN_CREDENTIALS` set to `prod` or specify the target credential.\n\nIf configuring a Rust skill, use `DeveloperToolsCredential` for local development and `ManagedIdentityCredential` for production. The Rust SDK does not support `DefaultAzureCredential`, so explicitly use the appropriate credential in each environment.\n\n```python\n# Python — note: client is wrapped in `with` for deterministic cleanup\nfrom azure.identity import DefaultAzureCredential, ManagedIdentityCredential\n# Local dev: DefaultAzureCredential works as-is.\ncredential = DefaultAzureCredential()\n# Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS.\n# credential = DefaultAzureCredential(require_envvar=True)\n# Or use a specific credential directly in production:\n# See https:\u002F\u002Flearn.microsoft.com\u002Fpython\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-python#credential-classes\n# credential = ManagedIdentityCredential()\nwith ServiceClient(endpoint, credential) as client:\n    client.do_thing()\n```\n\n```csharp\n\u002F\u002F C#\nusing Azure.Identity;\n\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\nvar credential = new DefaultAzureCredential(\n    DefaultAzureCredential.DefaultEnvironmentVariableName\n);\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F See https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-dotnet#credential-classes\n\u002F\u002F var credential = new ManagedIdentityCredential();\nvar client = new ServiceClient(new Uri(endpoint), credential);\n```\n\n```java\n\u002F\u002F Java\nimport com.azure.identity.AzureIdentityEnvVars;\nimport com.azure.identity.DefaultAzureCredentialBuilder;\nimport com.azure.identity.ManagedIdentityCredential;\nimport com.azure.identity.ManagedIdentityCredentialBuilder;\n\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\nTokenCredential credential = new DefaultAzureCredentialBuilder()\n    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)\n    .build();\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F See https:\u002F\u002Flearn.microsoft.com\u002Fjava\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-java-stable#credential-classes\n\u002F\u002F TokenCredential credential = new ManagedIdentityCredentialBuilder().build();\nServiceClient client = new ServiceClientBuilder()\n    .endpoint(endpoint)\n    .credential(credential)\n    .buildClient();\n```\n\n```typescript\n\u002F\u002F TypeScript\nimport {\n  DefaultAzureCredential,\n  ManagedIdentityCredential,\n} from \"@azure\u002Fidentity\";\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\nconst credential = new DefaultAzureCredential({\n  requiredEnvVars: [\"AZURE_TOKEN_CREDENTIALS\"],\n});\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F See https:\u002F\u002Flearn.microsoft.com\u002Fjavascript\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-node-latest#credential-classes\n\u002F\u002F const credential = new ManagedIdentityCredential();\nconst client = new ServiceClient(endpoint, credential);\n```\n\n```go\n\u002F\u002F Go\nimport (\n  \"context\"\n\n  \"github.com\u002FAzure\u002Fazure-sdk-for-go\u002Fsdk\u002Fazidentity\"\n  \"github.com\u002FAzure\u002Fazure-sdk-for-go\u002Fsdk\u002Fstorage\u002Fazblob\"\n)\n\nctx := context.Background()\n\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\ncred, err := azidentity.NewDefaultAzureCredential(nil)\nif err != nil {\n  panic(err)\n}\n\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F cred, err := azidentity.NewManagedIdentityCredential(nil)\n\nclient, err := azblob.NewClient(\"https:\u002F\u002F\u003Caccount>.blob.core.windows.net\u002F\", cred, nil)\nif err != nil {\n  panic(err)\n}\n\n_ = client\n_ = ctx\n```\n\n```rust\n\u002F\u002F Rust\nuse azure_identity::DeveloperToolsCredential;\nuse azure_storage_blob::BlobServiceClient;\n\nlet credential = DeveloperToolsCredential::new(); \u002F\u002F Local dev\nlet client = BlobServiceClient::new(\n    \"https:\u002F\u002F\u003Caccount>.blob.core.windows.net\u002F\",\n    credential,\n    None,\n)?;\n```\n\n**Never hardcode credentials. Use environment variables.**\n\n### Anti-Patterns: What NOT to Do (REQUIRED Reading)\n\n**These patterns cause bloat and inefficiency. Every skill author must review this section before writing.**\n\n#### Anti-Pattern 1: \"Exhaustive API Reference\"\n\n- ❌ **Don't**: List all 50 SDK methods in a feature table with code samples for every variant\n- ✅ **Do**: Show 3-5 core methods in a table; link to official Azure API reference for exhaustive list\n- **Token cost**: Listing all methods + examples = 400-600 tokens wasted\n- **User impact**: Overwhelming cognitive load; users don't know what to use\n\n#### Anti-Pattern 2: \"Multiple Ways to Solve One Problem\"\n\n- ❌ **Don't**: \"Here's approach A, B, C, and D to paginate results\" in the main body\n- ✅ **Do**: \"Use `ItemPaged` for sync pagination\" (primary example); link alternatives to `\u002Freferences\u002F`\n- **Token cost**: Each alternate approach = 50-100 tokens; 5 approaches = skill becomes inefficient\n- **User impact**: Decision paralysis; users re-read everything\n\n#### Anti-Pattern 3: \"Beginner + Intermediate + Advanced in One Skill\"\n\n- ❌ **Don't**: Skill that goes from \"what is a client?\" to \"custom retry policies\" to \"circuit breaker patterns\"\n- ✅ **Do**: Core workflow covers 80% use case; advanced patterns in `\u002Freferences\u002F`\n- **Token cost**: Every skill level adds 200-300 tokens; three levels = 600-900 extra tokens\n- **User impact**: Experts bored, beginners overwhelmed; nobody gets what they need\n\n#### Anti-Pattern 4: \"Restating Official Documentation\"\n\n- ❌ **Don't**: \"The CosmosClient constructor takes an endpoint (string) and credential (TokenCredential). The endpoint identifies the Azure Cosmos resource...\"\n- ✅ **Do**: Show code: `client = CosmosClient(endpoint, credential)`. Link to official docs: `microsoft-docs` MCP.\n- **Token cost**: Verbose explanation = 50-100 tokens per parameter; large APIs waste 300+ tokens\n- **User impact**: Redundant; official docs are authoritative, skill should show usage not repeat them\n\n#### Anti-Pattern 5: \"Verbose Explanation When Example Suffices\"\n\n- ❌ **Don't**: \"To create a client, you first instantiate the class using the constructor, passing the endpoint and credential parameters. The endpoint is a string that identifies your resource...\"\n- ✅ **Do**: Show code immediately: `with CosmosClient(endpoint, credential) as client:`\n\n---\n\n### Efficiency Validation (REQUIRED - Phase 2)\n\n**During authoring, validate skill efficiency manually, then run the Vally eval if the skill has one under `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fvally\u002F`.**\n\n**1. Measure token count:**\n\nUse a token counter or model playground to measure each section. Compare to the Token Budget Guidelines targets above. If any section exceeds max, move content to `\u002Freferences\u002F`.\n\n**2. Run anti-pattern checklist:**\n\n- [ ] No exhaustive API reference (show 3-5 core methods, not 50)\n- [ ] No multiple solutions to one problem in SKILL.md\n- [ ] No beginner+intermediate+advanced mixed\n- [ ] No restating official docs (code first, link to microsoft-docs)\n- [ ] No verbose prose (examples first, minimal text)\n\n**3. Example count audit:**\n\n- [ ] 1 complete example per hero scenario \u002F core workflow documented in SKILL.md. For Python SDKs that support both sync and async, the paired sync + async examples for the same workflow count as one workflow, not two.\n- [ ] Feature table includes 3-5 core methods (not comprehensive API)\n- [ ] Max 1 example per best practice bullet\n\n**4. Frontmatter validation:**\n\n- [ ] `name` matches `.github\u002Fskills\u002F\u003Cname>\u002FSKILL.md`\n- [ ] `description` includes trigger keywords\n- [ ] `description` is concise (~200 chars is a good target; schema max is 1,024 chars)\n- [ ] If included, optional `benchmark_tokens_*` and `benchmark_quality_*` metadata fields are flat strings under `metadata`\n\n**4b. Authentication guidance validation** (critical for all credentials):\n\n- [ ] If skill uses Azure Identity credentials, verify guidance against the current official credential docs for that language\u002Fpackage (Microsoft Learn where available; otherwise the upstream SDK repo or package docs)\n- [ ] For Python skills, development guidance may recommend `DefaultAzureCredential` (supports multiple dev credential types)\n- [ ] For Python skills, production guidance: `DefaultAzureCredential` alone (unconstrained) is not sufficient; require either `AZURE_TOKEN_CREDENTIALS=prod` (or a specific target credential) to constrain the chain, or a specific credential (e.g., `ManagedIdentityCredential`) used directly\n- [ ] For Rust skills, development\u002Fproduction guidance reflects the actual supported credentials (`DeveloperToolsCredential` for local dev; a specific production credential such as `ManagedIdentityCredential` for production)\n- [ ] Link to `\u002Freferences\u002Fauth-strategies.md` or official docs for production credential selection\n\n**4c. Run Vally lint\u002Feval (if the skill has a spec under `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fvally\u002F`):**\n\n```bash\n# If the eval spec uses the shared Rust custom grader plugin, build it first.\n(cd tests\u002Fscenarios\u002F_shared\u002Fvally\u002Fgrader-plugins\u002Frust-cargo-build-failure && npm install && npm run build)\n\nvally lint --eval-spec tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fvally\u002Feval.yaml \\\n  --grader-plugin tests\u002Fscenarios\u002F_shared\u002Fvally\u002Fgrader-plugins\u002Frust-cargo-build-failure \\\n  --strict\n\nvally eval --eval-spec tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fvally\u002Feval.yaml \\\n  --grader-plugin tests\u002Fscenarios\u002F_shared\u002Fvally\u002Fgrader-plugins\u002Frust-cargo-build-failure\n```\n\n- [ ] `vally lint` passes with no errors\n- [ ] `vally eval` passes (no error-severity findings) when `COPILOT_TOKEN` is available; otherwise lint-only is acceptable, matching the [`Vally Evaluation`](..\u002F..\u002Fworkflows\u002Fvally-evaluation.yml) workflow behavior\n- [ ] Skills without a `vally\u002F` spec skip this step — it is optional per skill, not required for every skill\n\n**5. Spot check:**\n\n- [ ] Can a user copy the core workflow and run it immediately?\n- [ ] Do all examples follow best practices (context managers, appropriate credentials)?\n- [ ] Are all environment variables documented?\n\n**Output:** After validation, annotate the skill header with measured token count:\n\n```markdown\n# Azure Service SDK\n\n\u003C!-- Token Count: ~1180 (target: 1100, max: 1500) -->\n```\n\n---\n\n### Standard Verb Patterns\n\nAzure SDKs use consistent verbs across all languages:\n\n| Verb     | Behavior                     |\n| -------- | ---------------------------- |\n| `create` | Create new; fail if exists   |\n| `upsert` | Create or update             |\n| `get`    | Retrieve; error if missing   |\n| `list`   | Return collection            |\n| `delete` | Succeed even if missing      |\n| `begin`  | Start long-running operation |\n\n### Language-Specific Patterns\n\nSee `references\u002Fazure-sdk-patterns.md` for detailed patterns including:\n\n- **Python**: `ItemPaged`, `LROPoller`, context managers, Sphinx docstrings. When the SDK provides both sync and async clients, present both forms as first-class options; do not express a preference for either. When the SDK is sync-only or async-only, document the available mode only. Do not mix sync and async within a single code example. Always show `with` \u002F `async with` context managers.\n- **.NET**: `Response\u003CT>`, `Pageable\u003CT>`, `Operation\u003CT>`, mocking support\n- **Java**: Builder pattern, `PagedIterable`\u002F`PagedFlux`, Reactor types\n- **TypeScript**: `PagedAsyncIterableIterator`, `AbortSignal`, browser considerations\n- **Go**: `context.Context` as first arg, `runtime.Pager[T]` via `New*Pager()` + `More()\u002FNextPage(ctx)`, `runtime.Poller[T]` via `Begin*` + `PollUntilDone(ctx, nil)`, `to.Ptr(...)` helpers, and typed `*azcore.ResponseError`\n- **Rust**: Installation via `cargo add`, dependency rule for `azure_core`, `Response\u003CT>`, `Pager\u003CT>`, `RequestContent::from()`, `.into_model()`, explicit credential types, RBAC roles for Entra ID authentication\n\n### Required Best Practices in Every Skill (User-Facing)\n\n#### Python, .NET, Java, TypeScript, and Go languages\n\n**These two rules are not just authoring conventions for the skill itself — they MUST be explicitly written into every generated skill's `## Best Practices` section so end users who follow the skill apply them in their own code.**\n\nAdd both items verbatim (adapted only for language\u002FSDK specifics) as the **first two items** of the Best Practices list. Do not assume users will infer them from examples.\n\n**Standard wording (Python; adapt for other languages):**\n\n```markdown\n1. **Do not mix sync and async clients in the same call path.** Use either `azure.xxx` sync clients or `azure.xxx.aio` async clients within a single call path — do not combine both.\n2. **Always use context managers for clients and async credentials.** Wrap every client in `with Client(...) as client:` (sync) or `async with Client(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up.\n3. **Use `DefaultAzureCredential`** for code that runs locally. For code that runs in Azure, either constrain `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS=prod` (or a specific target credential) or use a specific token credential directly (e.g. `ManagedIdentityCredential`, `WorkloadIdentityCredential`).\n```\n\n**Variants to apply when the SDK shape differs:**\n\n| Skill type                                                                    | Adjust item #1 to                                                                                                                   | Adjust item #2 to                                                                                                                                                                                                              |\n| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Async-only SDK (e.g. voicelive)                                               | \"This SDK is async-only; use the `.aio` namespace throughout.\"                                                                      | keep standard                                                                                                                                                                                                                  |\n| Framework guidance that is async-oriented (for example some agent frameworks) | \"Use the framework's documented async patterns where required, but do not claim async is globally preferred for Azure Python SDKs.\" | keep standard                                                                                                                                                                                                                  |\n| Provider-pattern (OpenTelemetry exporters\u002Fdistro)                             | keep standard                                                                                                                       | \"Call `provider.shutdown()` \u002F `flush()` at process exit to flush telemetry — providers are not context managers.\"                                                                                                              |\n| REST-over-httpx skills                                                        | keep standard                                                                                                                       | \"Use `with httpx.Client(...) as client:` (sync) or `async with httpx.AsyncClient(...) as client:` (async) so connections pool and close deterministically.\"                                                                    |\n| Identity skill                                                                | keep standard                                                                                                                       | \"Use credentials as context managers (`with DefaultAzureCredential() as credential:`) when they own token caches \u002F HTTP transports you want cleaned up; for async, use `async with` on credentials from `azure.identity.aio`.\" |\n| FastAPI (non-Azure)                                                           | \"Pick `def` or `async def` per endpoint based on whether you call async I\u002FO; do not mix sync and blocking calls in one handler.\"    | \"Manage long-lived resources (DB pools, HTTP clients) in `lifespan` and inject via `Depends`; use `with`\u002F`async with` for per-request resources.\"                                                                              |\n| Pure model\u002Fschema skill (no I\u002FO, e.g. pydantic)                               | **skip both** — not applicable                                                                                                      | **skip**                                                                                                                                                                                                                       |\n\n**Enforcement in code examples.** Every code example inside the skill must itself obey both rules, so the skill demonstrates what it prescribes:\n\n- Do not interleave sync and async calls within a single example. When the SDK provides both sync and async clients, show each mode in its own complete, self-contained example — a `### Sync` subsection and an `### Async` subsection — giving both equal prominence. When the SDK is sync-only or async-only, show only the available mode.\n- Every client instantiation in every example must be wrapped in `with` \u002F `async with`. The only permitted exception is the mandatory Authentication snippet (which illustrates the credential + client construction pattern) and framework lifespan patterns where a client is owned by the app (e.g. FastAPI `lifespan`).\n- When async credentials from `azure.identity.aio` appear in an example, wrap them in `async with credential:` alongside the client.\n\n#### Rust Language\n\n**These rules MUST be explicitly written into every Rust skill's `## Best Practices` section as the first items:**\n\n1. **Use `cargo add` to manage dependencies, never edit `Cargo.toml` directly.** Always use `cargo add \u003Ccrate>` or `cargo remove \u003Ccrate>` instead of manually modifying the manifest file. Official crates are published on crates.io and should be added via cargo.\n\n2. **Add `azure_core` to `Cargo.toml` only when you import `azure_core` types directly.** If your code imports types like `azure_core::http::Url`, `azure_core::http::RequestContent`, or `azure_core::error::ErrorKind`, explicitly add `azure_core` to your dependencies. If you only use types re-exported by service crates (e.g., via `use azure_storage_blob::BlobClient`), a direct `azure_core` dependency is optional.\n\n3. **Use `DeveloperToolsCredential` for local development and `ManagedIdentityCredential` for production.** The Rust SDK does not support `DefaultAzureCredential`, so explicitly use the appropriate credential in each environment.\n\n4. **Use `RequestContent::from()` to wrap upload data.** When uploading data (e.g., blobs), wrap the content in `RequestContent::from(your_data)` to ensure proper handling by the SDK.\n\n5. **Assign appropriate RBAC roles for Entra ID auth.** For production authentication using Entra ID, ensure the identity has the necessary RBAC role assigned (e.g., \"Storage Blob Data Contributor\" for blob write access).\n\n6. **Always verify package versions using crates.io.** Before using a package, check its version on [crates.io](https:\u002F\u002Fcrates.io\u002F) to ensure you are using a stable and supported release.\n\n7. **Future-proof `#[non_exhaustive]` model structs and enums.** Azure Rust SDK request\u002Fresponse models are frequently `#[non_exhaustive]`. For **externally constructible** structs that also derive `Default`, end the initializer with `..Default::default()` (even if every currently known field is set), suppressing the lint locally with `#[allow(clippy::needless_update)]` when needed. For **truly `#[non_exhaustive]`** structs (where Rust forbids external struct literals, producing E0639), use the provided constructor or builder, or construct a default value first and then mutate the fields you need. When matching an SDK enum, include a wildcard (`_`) arm so future service-added variants do not break the match. If a skill documents model construction, its code examples MUST demonstrate this pattern. See `references\u002Fazure-sdk-patterns.md` (Model Types) for the full example.\n\n### Example Effective Skills (Benchmark Only Structure-Compliant Skills)\n\n**Only benchmark Azure SDK skills that already use the required `references\u002F` layout** (`references\u002Fcapabilities.md` plus `references\u002Fnon-hero-scenarios.md`). Older skills that predate that structure can still be useful for style ideas, but do not mirror them directly until they are brought into compliance.\n\n**A valid benchmark skill should**:\n\n1. Stay at or under the 1,500-token absolute max (see Token Budget Guidelines above)\n2. Cover the hero workflow (CRUD or primary operations), not every feature variant\n3. Show 1-2 examples per concept, not 3-5\n4. Use tables for API summary (credential types, RBAC roles, client hierarchy)\n5. Link to official docs via `microsoft-docs` MCP instead of duplicating\n6. Move advanced patterns to `\u002Freferences\u002F`\n7. Include `references\u002Fcapabilities.md` and `references\u002Fnon-hero-scenarios.md`\n\n**Before writing your skill**: Apply the checklist above directly, then mirror only the structure patterns that fit your use case.\n\n---\n\n### Handling Deprecated or Rebranded SDKs\n\nWhen an Azure SDK has been deprecated or rebranded, update skills to guide users toward the current package while maintaining backward compatibility:\n\n**1. Add a migration notice at the top of the skill:**\n\n```markdown\n> **⚠️ MIGRATION NOTICE**: The [Old Service Name] has been rebranded to **[New Service Name]**. While the package `old-package-name` remains available for compatibility, **new projects should use `new-package-name`** which provides the latest features and updates.\n>\n> **For new projects**: Use the `new-package-name` package instead.\n>\n> **This skill remains valid** for existing projects using `old-package-name`, but be aware you're using the legacy package name. The API patterns shown here are compatible with both packages.\n```\n\n**2. Show both installation options:**\n\n```markdown\n## Installation\n\n### Legacy Package (Old Name)\n\n\\`\\`\\`xml\n\u003Cdependency>\n\u003CgroupId>com.azure\u003C\u002FgroupId>\n\u003CartifactId>azure-old-package\u003C\u002FartifactId>\n\u003Cversion>4.2.0\u003C\u002Fversion>\n\u003C\u002Fdependency>\n\\`\\`\\`\n\n### Recommended Package (New Name)\n\n**For new projects, use the rebranded package:**\n\n\\`\\`\\`xml\n\u003Cdependency>\n\u003CgroupId>com.azure\u003C\u002FgroupId>\n\u003CartifactId>azure-new-package\u003C\u002FartifactId>\n\u003Cversion>1.0.0\u003C\u002Fversion>\n\u003C\u002Fdependency>\n\\`\\`\\`\n\n> **Note**: The API patterns in this skill apply to both packages. Replace package names and imports as needed when using `azure-new-package`.\n```\n\n**3. When to create a new skill vs. update existing:**\n\n- **Update existing skill** if the API is largely compatible (same or similar class\u002Fmethod names)\n- **Create new skill + migration guide** if the API changed significantly (use `references\u002Fmigration.md`)\n- **Always cross-reference** between old and new skills\n\n**Examples:**\n\n- `azure-ai-formrecognizer-java` → `azure-ai-documentintelligence` (rebranded service)\n- `azure-communication-callingserver-java` → `azure-communication-callautomation` (deprecated, with migration guide)\n\n### Example: Azure SDK Skill Structure\n\n```markdown\n---\nname: skill-creator\ndescription: |\n  Azure AI Example SDK for Python. Use for [specific service features].\n  Triggers: \"example service\", \"create example\", \"list examples\".\n---\n\n# Azure AI Example SDK\n\n## Installation\n\n\\`\\`\\`bash\npip install azure-ai-example\n\\`\\`\\`\n\n## Environment Variables\n\n\\`\\`\\`bash\nAZURE_EXAMPLE_ENDPOINT=https:\u002F\u002F\u003Cresource>.example.azure.com\nAZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production\n\\`\\`\\`\n\n## Authentication & Lifecycle\n\n> **? Two rules apply to every code sample below:**\n>\n> 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI \u002F VS Code \u002F Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account\u002FAPI keys — they bypass Entra audit and rotation.\n>    - Local dev: `DefaultAzureCredential` works as-is.\n>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>`) to constrain the credential chain to production-safe credentials.\n> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:\n>    - Sync: `with \u003CClient>(...) as client:`\n>    - Async: `async with \u003CClient>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)\n>\n> Snippets may abbreviate this setup, but production code should always follow both rules.\n\n\\`\\`\\`python\nfrom azure.identity import DefaultAzureCredential, ManagedIdentityCredential\nfrom azure.ai.example import ExampleClient\n\n# Local dev: DefaultAzureCredential works as-is.\ncredential = DefaultAzureCredential()\n\n# Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS.\n# credential = DefaultAzureCredential(require_envvar=True)\n\n# Or use a specific credential directly in production:\n\n# See https:\u002F\u002Flearn.microsoft.com\u002Fpython\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-python#credential-classes\n\n# credential = ManagedIdentityCredential()\n\nwith ExampleClient(\nendpoint=os.environ[\"AZURE_EXAMPLE_ENDPOINT\"],\ncredential=credential,\n) as client:\nitem = client.get_item(\"example\")\n\\`\\`\\`\n\n## Core Workflow\n\n\\`\\`\\`python\nwith ExampleClient(endpoint=endpoint, credential=credential) as client: # Create\nitem = client.create_item(name=\"example\", data={...})\n\n    # List (pagination handled automatically)\n    for item in client.list_items():\n        print(item.name)\n\n    # Long-running operation\n    poller = client.begin_process(item.id)\n    result = poller.result()\n\n    # Cleanup\n    client.delete_item(item.id)\n\n\\`\\`\\`\n\n## Reference Files\n\n| File                                                                 | Contents                                               |\n| -------------------------------------------------------------------- | ------------------------------------------------------ |\n| [references\u002Fcapabilities.md](references\u002Fcapabilities.md)             | Capability index (hero coverage + links to deep-dives) |\n| [references\u002Fnon-hero-scenarios.md](references\u002Fnon-hero-scenarios.md) | Concrete non-hero examples                             |\n| [references\u002Ftools.md](references\u002Ftools.md)                           | Tool integrations                                      |\n| [references\u002Fstreaming.md](references\u002Fstreaming.md)                   | Event streaming patterns                               |\n```\n\n---\n\n## Skill Creation Process\n\n1. **Gather SDK Context** — User provides SDK\u002FAPI reference (REQUIRED)\n2. **Understand** — Research SDK patterns from official docs\n3. **Plan** — Identify reusable resources and product area category\n4. **Create** — Write SKILL.md in `.github\u002Fskills\u002F\u003Cskill-name>\u002F`\n5. **Categorize** — Create symlink in `skills\u002F\u003Clanguage>\u002F\u003Ccategory>\u002F`\n6. **Test** — Create acceptance criteria and test scenarios\n7. **Document** — Update README.md skill catalog\n8. **Iterate** — Refine based on real usage\n\n### Step 1: Gather SDK Context (REQUIRED)\n\n**Before creating any SDK skill, the user MUST provide:**\n\n| Required                  | Example                                                   | Purpose                  |\n| ------------------------- | --------------------------------------------------------- | ------------------------ |\n| **SDK Package**           | `azure-ai-agents`, `Azure.AI.OpenAI`, `azblob`            | Identifies the exact SDK |\n| **Documentation URL**     | `https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Fai-services\u002F...` | Primary source of truth  |\n| **Repository** (optional) | `Azure\u002Fazure-sdk-for-python`, `Azure\u002Fazure-sdk-for-go`    | For code patterns        |\n\n**Prompt the user if not provided:**\n\n```\nTo create this skill, I need:\n1. The SDK package name (e.g., azure-ai-projects)\n2. The Microsoft Learn documentation URL or GitHub repo\n3. The target language (py\u002Fdotnet\u002Fts\u002Fjava\u002Fgo)\n```\n\n**Search official docs first:**\n\n```bash\n# Use microsoft-docs MCP to get current API patterns\n# Query: \"[SDK name] [operation] [language]\"\n# Verify: Parameters match the latest SDK version\n```\n\n### Step 2: Understand the Skill\n\nGather concrete examples:\n\n- \"What SDK operations should this skill cover?\"\n- \"What triggers should activate this skill?\"\n- \"What errors do developers commonly encounter?\"\n\n| Example Task               | Reusable Resource              |\n| -------------------------- | ------------------------------ |\n| Same auth code each time   | Code example in SKILL.md       |\n| Complex streaming patterns | `references\u002Fstreaming.md`      |\n| Tool configurations        | `references\u002Ftools.md`          |\n| Error handling patterns    | `references\u002Ferror-handling.md` |\n\n### Step 3: Plan Product Area Category\n\nSkills are organized by **language** and **product area** in the `skills\u002F` directory via symlinks.\n\n**Product Area Categories:**\n\n| Category      | Description                             | Examples                                     |\n| ------------- | --------------------------------------- | -------------------------------------------- |\n| `foundry`     | AI Foundry, agents, projects, inference | `azure-ai-agents-py`, `azure-ai-projects-py` |\n| `data`        | Storage, Cosmos DB, Tables, Data Lake   | `azure-cosmos-py`, `azure-storage-blob-py`   |\n| `messaging`   | Event Hubs, Service Bus, Event Grid     | `azure-eventhub-py`, `azure-servicebus-py`   |\n| `monitoring`  | OpenTelemetry, App Insights, Query      | `azure-monitor-opentelemetry-py`             |\n| `identity`    | Authentication, DefaultAzureCredential  | `azure-identity-py`                          |\n| `security`    | Key Vault, secrets, keys, certificates  | `azure-keyvault-py`                          |\n| `integration` | API Management, App Configuration       | `azure-appconfiguration-py`                  |\n| `compute`     | Batch, ML compute                       | `azure-compute-batch-java`                   |\n| `container`   | Container Registry, ACR                 | `azure-containerregistry-py`                 |\n\n**Determine the category** based on:\n\n1. Azure service family (Storage → `data`, Event Hubs → `messaging`)\n2. Primary use case (AI agents → `foundry`)\n3. Existing skills in the same service area\n\n### Step 4: Create the Skill\n\n**Location:** `.github\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md`\n\n**Naming convention:**\n\n- `azure-\u003Cservice>-\u003Csubservice>-\u003Clanguage>`\n- Examples: `azure-ai-agents-py`, `azure-cosmos-java`, `azure-storage-blob-ts`, `azure-storage-blob-go`\n- For Go skills in documentation prose, use the short package name (for example `azblob`).\n- Use the full module import path only in code\u002Fimport examples (for example `github.com\u002FAzure\u002Fazure-sdk-for-go\u002Fsdk\u002Fstorage\u002Fazblob`).\n\n**For Azure SDK skills:**\n\n1. Search `microsoft-docs` MCP for current API patterns\n2. Verify against installed SDK version\n3. Follow the section order above\n4. Include cleanup code in examples\n5. Add feature comparison tables\n\n**Write bundled resources first**, then SKILL.md.\n\n**Quality assurance before finalizing:**\n\n1. Measure section token counts as you write (use model playground token counter)\n2. Compare to Token Budget Guidelines targets\n3. Validate against anti-patterns checklist (see Anti-Patterns section)\n4. Extract to `\u002Freferences\u002F` if section exceeds max tokens\n5. Run Efficiency Validation checklist, including `vally lint`\u002F`vally eval` if the skill has a spec (see Efficiency Validation)\n6. Optionally add `benchmark_tokens_*` and `benchmark_quality_*` fields under the frontmatter's `metadata` mapping (flat string values)\n7. Add token count comment to skill header for future maintenance\n\n**Frontmatter (Enhanced with Benchmarking Metadata):**\n\n```yaml\n---\nname: azure-service-py\ndescription: |\n  Azure Service SDK for Python. Use for [specific features].\n  Triggers: \"service name\", \"create resource\", \"specific operation\".\nmetadata:\n  benchmark_tokens_estimated: \"1180\"\n  benchmark_tokens_target: \"1100\"\n  benchmark_tokens_max: \"1500\"\n  benchmark_quality_single_core_workflow: \"true\"\n  benchmark_quality_examples_focused: \"true\"\n  benchmark_quality_no_prose_bloat: \"true\"\n  benchmark_quality_anti_patterns_checked: \"true\"\n---\n```\n\n**Metadata fields:** (all values are strings, per the Agent Skills `metadata` spec — string keys mapped to string values)\n\n- `benchmark_tokens_estimated` — Actual measured token count\n- `benchmark_tokens_target` — Target efficiency (typically 1100)\n- `benchmark_tokens_max` — Absolute ceiling (1500; split if exceeded)\n- `benchmark_quality_*` — Individual anti-pattern checks, each a `\"true\"`\u002F`\"false\"` string (e.g., `benchmark_quality_single_core_workflow`)\n\n### Step 5: Categorize with Symlinks\n\nAfter creating the skill in `.github\u002Fskills\u002F`, create a symlink in the appropriate category:\n\n```bash\n# Pattern: skills\u002F\u003Clanguage>\u002F\u003Ccategory>\u002F\u003Cshort-name> -> ..\u002F..\u002F..\u002F.github\u002Fskills\u002F\u003Cfull-skill-name>\n\n# Example for azure-ai-agents-py in python\u002Ffoundry:\ncd skills\u002Fpython\u002Ffoundry\nln -s ..\u002F..\u002F..\u002F.github\u002Fskills\u002Fazure-ai-agents-py agents\n\n# Example for azure-cosmos-db-py in python\u002Fdata:\ncd skills\u002Fpython\u002Fdata\nln -s ..\u002F..\u002F..\u002F.github\u002Fskills\u002Fazure-cosmos-db-py cosmos-db\n\n# Example for azure-storage-blob-go in go\u002Fdata:\ncd skills\u002Fgo\u002Fdata\nln -s ..\u002F..\u002F..\u002F.github\u002Fskills\u002Fazure-storage-blob-go blob\n```\n\n**Symlink naming:**\n\n- Use short, descriptive names (e.g., `agents`, `cosmos`, `blob`)\n- Remove the `azure-` prefix and language suffix\n- Match existing patterns in the category\n\n**Verify the symlink:**\n\n```bash\nls -la skills\u002Fpython\u002Ffoundry\u002Fagents\n# Should show: agents -> ..\u002F..\u002F..\u002F.github\u002Fskills\u002Fazure-ai-agents-py\n```\n\n### Step 6: Create Tests\n\n**Every skill MUST have acceptance criteria and test scenarios.**\n\n#### 6.1 Create Acceptance Criteria\n\n**Location:** `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Facceptance-criteria.md`\n\n> Keep acceptance criteria in the `tests\u002F` tree (never beside `SKILL.md` inside the skill folder).\n\n**Source materials** (in priority order):\n\n1. Official Microsoft Learn docs (via `microsoft-docs` MCP)\n2. SDK source code from the repository\n3. Existing reference files in the skill\n\n**Format:**\n\n```markdown\n# Acceptance Criteria: \u003Cskill-name>\n\n**SDK**: `package-name`\n**Repository**: https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-\u003Clanguage>\n**Purpose**: Skill testing acceptance criteria\n\n---\n\n## 1. Correct Import Patterns\n\n### 1.1 Client Imports\n\n#### ✅ CORRECT: Main Client\n\n\\`\\`\\`python\nfrom azure.ai.mymodule import MyClient\nfrom azure.identity import DefaultAzureCredential\n\\`\\`\\`\n\n#### ❌ INCORRECT: Wrong Module Path\n\n\\`\\`\\`python\nfrom azure.ai.mymodule.models import MyClient # Wrong - Client is not in models\n\\`\\`\\`\n\n## 2. Authentication Patterns\n\n#### ✅ CORRECT: DefaultAzureCredential + context manager\n\n\\`\\`\\`python\ncredential = DefaultAzureCredential()\nwith MyClient(endpoint, credential) as client:\nclient.do_thing()\n\\`\\`\\`\n\n#### ❌ INCORRECT: Hardcoded Credentials\n\n\\`\\`\\`python\nclient = MyClient(endpoint, api_key=\"hardcoded\") # Security risk\n\\`\\`\\`\n\n#### ❌ INCORRECT: Connection string \u002F account key when Entra is supported\n\n\\`\\`\\`python\nclient = MyClient.from_connection_string(os.environ[\"CONNECTION_STRING\"]) # Bypasses Entra audit\u002Frotation\n\\`\\`\\`\n\n#### ❌ INCORRECT: Bare client without context manager\n\n\\`\\`\\`python\nclient = MyClient(endpoint, credential) # Leaks HTTP transport on exception \u002F interpreter exit\nclient.do_thing()\n\\`\\`\\`\n```\n\n**Critical patterns to document:**\n\n- Import paths (these vary significantly between Azure SDKs)\n- Authentication patterns\n- Client initialization\n- Async variants (`.aio` modules)\n- Common anti-patterns\n\n#### 6.2 Create Test Scenarios\n\n**Location:** `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fscenarios.yaml`\n\n```yaml\nconfig:\n  model: gpt-4\n  max_tokens: 2000\n  temperature: 0.3\n\nscenarios:\n  - name: basic_client_creation\n    prompt: |\n      Create a basic example using the Azure SDK.\n      Include proper authentication and client initialization.\n    expected_patterns:\n      - \"DefaultAzureCredential\"\n      - \"MyClient\"\n      - \"with MyClient\" # enforce context manager\n    forbidden_patterns:\n      - \"api_key=\"\n      - \"hardcoded\"\n      - \"from_connection_string\" # prefer Entra over connection strings\n    tags:\n      - basic\n      - authentication\n    mock_response: |\n      import os\n      from azure.identity import DefaultAzureCredential\n      from azure.ai.mymodule import MyClient\n\n      credential = DefaultAzureCredential()\n      with MyClient(\n          endpoint=os.environ[\"AZURE_ENDPOINT\"],\n          credential=credential,\n      ) as client:\n          # ... rest of working example\n          pass\n```\n\n**Scenario design principles:**\n\n- Each scenario tests ONE specific pattern or feature\n- `expected_patterns` — patterns that MUST appear\n- `forbidden_patterns` — common mistakes that must NOT appear\n- `mock_response` — complete, working code that passes all checks\n- `tags` — for filtering (`basic`, `async`, `streaming`, `tools`)\n\n#### 6.3 Run Tests\n\n```bash\ncd tests\npnpm install\n\n# Check skill is discovered\npnpm harness --list\n\n# Run in mock mode (fast, deterministic)\npnpm harness \u003Cskill-name> --mock --verbose\n\n# Run with Ralph Loop (iterative improvement)\npnpm harness \u003Cskill-name> --ralph --mock --max-iterations 5 --threshold 85\n```\n\n**Success criteria:**\n\n- All scenarios pass (100% pass rate)\n- No false positives (mock responses always pass)\n- Patterns catch real mistakes\n\n### Step 7: Update Documentation\n\nAfter creating the skill:\n\n1. **Update README.md** — Add the skill to the appropriate language section in the Skill Catalog\n   - Update total skill count (line ~73: `> N skills in...`)\n   - Update Skill Explorer link count (line ~15: `Browse all N skills`)\n   - Update language count table (lines ~77-83)\n   - Update language section count (e.g., `> N skills • suffix: -py`)\n   - Update category count (e.g., `\u003Csummary>\u003Cstrong>Foundry & AI\u003C\u002Fstrong> (N skills)\u003C\u002Fsummary>`)\n   - Add skill row in alphabetical order within its category\n   - Update test coverage summary (line ~622: `**N skills with N test scenarios**`)\n   - Update test coverage table — update skill count, scenario count, and top skills for the language\n\n2. **Regenerate GitHub Pages data** — Run the extraction script and rebuild the docs site from one scoped directory change\n\n   ```bash\n   (cd docs-site && npx tsx scripts\u002Fextract-skills.ts && npm run build)\n   ```\n\n   This updates `docs-site\u002Fsrc\u002Fdata\u002Fskills.json` which feeds the Astro-based docs site, then rebuilds the site into `docs\u002F`, which is served by GitHub Pages.\n\n3. **Verify AGENTS.md** — Ensure the skill count is accurate\n\n---\n\n### Step 8: Regenerate Existing Skills from Latest SDK Sources\n\nUse this workflow when an existing skill has stale examples, outdated API signatures,\nor changed package guidance.\n\n1. **Identify canonical source files first**\n\nFor Azure SDK language skills, use official upstream source docs and examples as the source of truth:\n\n- Go: `https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-go\u002Ftree\u002Fmain\u002Fsdk\u002F\u003Cservice>\u002F\u003Cmodule>\u002FREADME.md`\n- Go examples: `https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-go\u002Ftree\u002Fmain\u002Fsdk\u002F\u003Cservice>\u002F\u003Cmodule>\u002F`\n- Rust: `https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-rust\u002Ftree\u002Fmain\u002Fsdk\u002F\u003Cservice>\u002F\u003Ccrate>\u002FREADME.md`\n- Rust examples: `https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-rust\u002Ftree\u002Fmain\u002Fsdk\u002F\u003Cservice>\u002F\u003Ccrate>\u002Fexamples\u002F`\n- .NET\u002FJava\u002FPython\u002FTS\u002FGo: use current Microsoft Learn package docs + official SDK repos\n\n2. **Refresh skill content surgically**\n\n- Update code snippets to match current constructor\u002Fmethod signatures\n- Keep crate\u002Fpackage names aligned with official publisher guidance\n- Preserve skill structure\u002Ffrontmatter unless intentionally changing behavior\n- Update \"Best Practices\" and \"Reference Links\" when upstream recommendations change\n- For Rust, if code uses `azure_core` types\u002Fimports directly, ensure `azure_core` is present in `Cargo.toml`; if only service-crate re-exports are used, direct `azure_core` dependency is optional\n\n### API Surface Parity Gate (required for every regenerated skill)\n\nUse the language-specific authoritative source as the contract for every snippet in the regenerated skill:\n\n- **Python, .NET, Java, TypeScript, Go**: Treat the current Microsoft Learn API reference as the contract.\n- **Rust**: Treat the official SDK repository (`https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-rust`) and crates.io documentation as the contract; Rust packages do not have Learn API-reference pages.\n\nBefore finalizing any regenerated skill:\n\n1. Identify each SDK type\u002Fmethod shown in snippets (clients, operation groups, model constructors, enum members, long-running methods like `begin_*`).\n2. Verify each symbol and signature against the authoritative source for that language\u002Fpackage (see above).\n3. If the authoritative source shows a different shape (for example nested `properties=...` models, renamed methods, `begin_*` LRO methods), update the snippet to match.\n4. Re-check imports so model\u002Fclient modules match the authoritative source exactly.\n5. Do not keep compatibility shortcuts that contradict authoritative examples in primary snippets.\n\n### Scenario Coverage Gate (required for every regenerated skill, all languages)\n\nRegeneration is not complete when snippets compile — it is complete when the skill demonstrates real usage breadth.\n\nBefore finalizing any regenerated skill:\n\n1. Identify **hero scenarios** from the current authoritative docs\u002Fsamples for that SDK (Microsoft Learn where available; otherwise the upstream SDK repo and package documentation).\n2. Ensure each hero scenario is represented in the skill with copy-pastable snippets (or an explicit link to a bundled reference file when too large).\n3. Add\u002Frefresh test scenarios so hero flows are validated by harness patterns.\n4. Add at least **one important non-hero scenario** (for example: update\u002Fpatch, delete\u002Fcleanup, export\u002Fimport, advanced auth mode, paging\u002Ffiltering, retries\u002Ferror handling, or LRO monitoring) when supported by the SDK. For Python SDKs that support both sync and async clients, present both forms with equal priority; do not treat either as universally preferred.\n5. For Azure SDK skills, structure `references\u002F` as:\n   - `references\u002Fcapabilities.md` as a concise index that records each hero scenario and where it is covered (`SKILL.md` or a bundled reference), plus links to deeper non-hero references, with no historical\u002Fmigration narration.\n   - `references\u002Fnon-hero-scenarios.md` for concrete non-hero examples that are intentionally kept out of the main `SKILL.md`.\n   - Additional `references\u002F*.md` files for specialized deep-dives (operation groups, tools, evaluator matrices, etc.).\n6. If the SDK has broad operation-group coverage (common in management SDKs), include an operation-group table and explicitly call out which groups are covered in snippets vs. referenced only.\n7. Never claim \"full API surface\" unless the skill genuinely demonstrates all major operation groups; otherwise state that the skill is optimized for hero workflows plus selected secondary scenarios.\n\n### Regeneration Workflow Step 3: Validate Regenerated Skill Behavior\n\n```bash\n(cd tests && pnpm harness \u003Cskill-name> --mock --verbose)\n```\n\nIf the skill has a Vally scenario, run that eval as well (locally or in CI) before finalizing.\n\n**Rust regeneration gate (required for Rust skills):**\n\nWhen regenerating any Rust skill, verify the generated `## Best Practices` section contains these exact first two rules:\n\n1. `Use cargo add to manage dependencies, never edit Cargo.toml directly`\n2. `Add azure_core only when importing azure_core types directly`\n\nUse a content check before finalizing:\n\n```bash\nrg -n \"Use `cargo add` to manage dependencies, never edit `Cargo.toml` directly|Add `azure_core` only when importing `azure_core` types directly\" .github\u002Fplugins\u002Fazure-sdk-rust\u002Fskills\u002F**\u002FSKILL.md\n```\n\nThe regeneration is not complete unless both lines are present in each affected Rust skill.\n\n### Regeneration Workflow Step 4: Regenerate Docs Artifacts After Refresh\n\n```bash\n(cd docs-site && npx tsx scripts\u002Fextract-skills.ts && npm run build)\n```\n\n### Regeneration Workflow Step 5: Record What Changed\n\nIn the PR\u002Fcommit notes, include:\n\n- Which upstream docs\u002Fexamples were used\n- Which snippets\u002Fsignatures were corrected\n- Which tests\u002Fevals were run and their outcomes\n\n#### Python plugin batch recipe: `azure-sdk-python`\n\nUse this when the request is \"regenerate all Python skills under azure-sdk-python.\"\n\n1. **Scope the exact targets first**\n\n```bash\n# Canonical source of truth for Python plugin skills\nls .github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002F*\u002FSKILL.md\n```\n\n- Treat `.github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002F` as canonical.\n- Keep `.github\u002Fskills\u002F\u003Cname>` links in sync after edits (symlink check\u002Ffix step below).\n\n2. **For each skill, refresh from authoritative sources**\n\n- Always use `microsoft-docs` MCP first for current Microsoft Learn API guidance.\n- Verify the installed package version with `pip show \u003Cpackage>`, then inspect the installed package or official API reference to verify every symbol and signature used in snippets.\n- For Azure SDK skills, prefer package overview + official SDK repo examples.\n- For non-Azure Python skills in this plugin (for example `fastapi-router-py`, `pydantic-models-py`), keep language-specific best-practice variants and skip Azure-specific auth callouts when lifecycle\u002Fauth is not applicable.\n\n3. **Apply Python enforcement rules consistently**\n\n- Keep the standard section order for Azure SDK Python skills.\n- Ensure `## Authentication & Lifecycle` starts with the required callout block (verbatim) when applicable.\n- Ensure every client example uses `with` \u002F `async with` lifecycle patterns.\n- Ensure `## Best Practices` starts with the two required user-facing rules (or the documented variant for async-only\u002Fprovider-pattern skills).\n- Ensure each regenerated Azure SDK Python skill has `references\u002Fcapabilities.md` (index) and `references\u002Fnon-hero-scenarios.md` (concrete non-hero examples).\n- Keep existing references\u002Fassets\u002Fscripts unless stale or incorrect.\n\n4. **Validate all regenerated Python skills**\n\n```bash\n# Fast frontmatter\u002Fstructure validation for every Python skill\npython .github\u002Fskills\u002Fskill-creator\u002Fscripts\u002Fquick_validate.py .github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002F\u003Cskill-name>\n\n# Run Python skill harness in mock mode (all *-py scenarios)\n(cd tests && pwsh .\u002Frun-harness-by-language.ps1 -Language py -Mock)\n```\n\n5. **Sync skill links and docs artifacts**\n\n```bash\n# Ensure .github\u002Fskills links point at plugin canonical skills\npython .github\u002Fscripts\u002Fsync_skill_links.py --plugin azure-sdk-python --check\npython .github\u002Fscripts\u002Fsync_skill_links.py --plugin azure-sdk-python --apply\n\n# Refresh docs site data after content changes\n(cd docs-site && npx tsx scripts\u002Fextract-skills.ts && npm run build)\n```\n\n6. **Completion criteria for batch regeneration**\n\n- Every targeted `.github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002F*\u002FSKILL.md` is updated or explicitly confirmed current.\n- Harness mock run for `-py` skills passes without regressions.\n- Skill links are in sync for `azure-sdk-python`.\n- PR notes include upstream docs used, signature corrections, and validation outcomes.\n\n---\n\n## Progressive Disclosure Patterns\n\n### Pattern 1: High-Level Guide with References\n\n```markdown\n# SDK Name\n\n## Quick Start\n\n[Minimal example]\n\n## Advanced Features\n\n- **Streaming**: See [references\u002Fstreaming.md](references\u002Fstreaming.md)\n- **Tools**: See [references\u002Ftools.md](references\u002Ftools.md)\n```\n\n### Pattern 2: Language Variants\n\n```\nazure-service-skill\u002F\n├── SKILL.md (overview + language selection)\n└── references\u002F\n    ├── python.md\n    ├── dotnet.md\n    ├── go.md\n    ├── java.md\n    └── typescript.md\n```\n\n### Pattern 3: Feature Organization\n\n```\nazure-ai-agents\u002F\n├── SKILL.md (core workflow)\n└── references\u002F\n    ├── tools.md\n    ├── streaming.md\n    ├── async-patterns.md\n    └── error-handling.md\n```\n\n---\n\n## Design Pattern References\n\n| Reference                          | Contents                             |\n| ---------------------------------- | ------------------------------------ |\n| `references\u002Fworkflows.md`          | Sequential and conditional workflows |\n| `references\u002Foutput-patterns.md`    | Templates and examples               |\n| `references\u002Fazure-sdk-patterns.md` | Language-specific Azure SDK patterns |\n\n---\n\n## Anti-Patterns\n\n| Don't                                                                          | Why                                                                                 |\n| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |\n| Create skill without SDK context                                               | Users must provide package name\u002Fdocs URL                                            |\n| Put \"when to use\" in body                                                      | Body loads AFTER triggering                                                         |\n| Hardcode credentials                                                           | Security risk                                                                       |\n| Skip authentication section                                                    | Agents will improvise poorly                                                        |\n| Use outdated SDK patterns                                                      | APIs change; search docs first                                                      |\n| Include README.md                                                              | Agents don't need meta-docs                                                         |\n| Deeply nest references                                                         | Keep one level deep                                                                 |\n| Skip acceptance criteria                                                       | Skills without tests can't be validated                                             |\n| Skip symlink categorization                                                    | Skills won't be discoverable by category                                            |\n| Use wrong import paths                                                         | Azure SDKs have specific module structures                                          |\n| Omit sync\u002Fasync + context-manager bullets from Best Practices in Python skills | End users won't follow rules that aren't written down; examples alone aren't enough |\n| Mix sync and async in the same Python example                                  | Demonstrates the anti-pattern the skill is supposed to prevent                      |\n| Ship regenerated skills with zero test scenarios                               | Hero workflows and regressions cannot be validated                                  |\n| Claim full API coverage from a single happy-path sample                        | Hides operation-group and non-hero gaps users need for production                   |\n| Omit `references\u002F*.md` coverage for non-hero capabilities                      | Forces advanced capabilities out of context and leaves API breadth undocumented     |\n\n---\n\n## Checklist\n\nBefore completing a skill:\n\n**Prerequisites:**\n\n- [ ] User provided SDK package name or documentation URL\n- [ ] Verified SDK patterns via `microsoft-docs` MCP\n- [ ] Verified every snippet's API surface against the current official language-specific API reference for that SDK (Microsoft Learn where available, otherwise the upstream SDK repo — see canonical sources above)\n\n**Skill Creation:**\n\n- [ ] Description includes what AND when (trigger phrases)\n- [ ] SKILL.md under 500 lines\n- [ ] Authentication follows language rules (`DefaultAzureCredential` for Python\u002F.NET\u002FJava\u002FTS\u002FGo local dev; `DeveloperToolsCredential` local dev + `ManagedIdentityCredential` production for Rust)\n- [ ] Includes cleanup\u002Fdelete in examples\n- [ ] References organized by feature (`capabilities.md` index + dedicated deep-dive files)\n- [ ] Hero scenarios from the current authoritative docs\u002Fsamples for that SDK are explicitly covered in snippets and tests\n- [ ] At least one high-value non-hero scenario is included when the SDK supports a distinct non-hero scenario (otherwise note that no distinct non-hero scenario applies)\n- [ ] For Azure SDK skills, `references\u002Fcapabilities.md` indexes hero\u002Fnon-hero coverage and links to dedicated non-hero docs\n- [ ] For Azure SDK skills, `references\u002Fnon-hero-scenarios.md` contains concrete non-hero examples distinct from hero snippets\n- [ ] For broad SDKs (especially management SDKs), operation-group coverage is explicit (covered in snippets vs. reference-only)\n- [ ] **(Python skills only) Best Practices section contains the two user-facing rules** (sync-or-async consistency + context managers for clients and async credentials), using the variant matched to the skill type\n- [ ] For Rust skills: `## Best Practices` starts with cargo dependency rule + `azure_core` direct-import rule\n\n**Categorization:**\n\n- [ ] Skill created in `.github\u002Fskills\u002F\u003Cskill-name>\u002F`\n- [ ] Symlink created in `skills\u002F\u003Clanguage>\u002F\u003Ccategory>\u002F\u003Cshort-name>`\n- [ ] Symlink points to `..\u002F..\u002F..\u002F.github\u002Fskills\u002F\u003Cskill-name>`\n\n**Testing:**\n\n- [ ] `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Facceptance-criteria.md` created with correct\u002Fincorrect patterns\n- [ ] `tests\u002Fscenarios\u002F\u003Cskill-name>\u002Fscenarios.yaml` created\n- [ ] At least one hero scenario and one non-hero scenario are test-covered (when the SDK supports both)\n- [ ] All scenarios pass (`pnpm harness \u003Cskill> --mock`)\n- [ ] Import paths documented precisely\n\n**Documentation:**\n\n- [ ] README.md skill catalog updated\n- [ ] Instructs to search `microsoft-docs` MCP for current APIs\n",{"name":5,"description":7},"main","3f5b461b2314e01c400564051e92469114c5b68f",".github\u002Fskills\u002Fskill-creator",368,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills","https:\u002F\u002Fmicrosoft.github.io\u002Fskills\u002F","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-14 06:48:25",{"source":8,"skillName":5,"commands":58,"prompt":68,"zipAvailable":69},[59,62,65],{"tool":60,"command":61},"npx","npx skills add microsoft\u002Fskills --skill skill-creator",{"tool":63,"command":64},"bunx","bunx skills add microsoft\u002Fskills --skill skill-creator",{"tool":66,"command":67},"pnpm","pnpm dlx skills add microsoft\u002Fskills --skill skill-creator","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002FSKILL.md",true,[71,77,81,85,89,93,99,103],{"path":72,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":75,"sourceHtmlUrl":76},"references\u002Fazure-sdk-patterns.md","REFERENCE","参考文档",32551,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002Freferences\u002Fazure-sdk-patterns.md",{"path":78,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":79,"sourceHtmlUrl":80},"references\u002Foutput-patterns.md",4176,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002Freferences\u002Foutput-patterns.md",{"path":82,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":83,"sourceHtmlUrl":84},"references\u002Fphoto-guide.md",720,"https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Fhiggsfield-ai_skills\u002Fhiggsfield-soul-id\u002Freferences\u002Fphoto-guide.md",{"path":86,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":87,"sourceHtmlUrl":88},"references\u002Ftroubleshooting.md",538,"https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Fhiggsfield-ai_skills\u002Fhiggsfield-soul-id\u002Freferences\u002Ftroubleshooting.md",{"path":90,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":91,"sourceHtmlUrl":92},"references\u002Fworkflows.md",3196,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002Freferences\u002Fworkflows.md",{"path":94,"resourceType":95,"resourceTypeDesc":96,"sizeBytes":97,"sourceHtmlUrl":98},"scripts\u002Finit_skill.py","SCRIPT","脚本",10863,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002Fscripts\u002Finit_skill.py",{"path":100,"resourceType":95,"resourceTypeDesc":96,"sizeBytes":101,"sourceHtmlUrl":102},"scripts\u002Fpackage_skill.py",3288,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002Fscripts\u002Fpackage_skill.py",{"path":104,"resourceType":95,"resourceTypeDesc":96,"sizeBytes":105,"sourceHtmlUrl":106},"scripts\u002Fquick_validate.py",3523,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002Fscripts\u002Fquick_validate.py",[108,116,154,181,202,240],{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":115},"01M741JBE1VH8A2Y3FXX2P7386","azure-advisor-cost-optimization","Analyze Azure Advisor Cost\u002FIdleResources findings and prevalidate deletion safety, including Service Groups. WHEN: \"find unused Azure resources\", \"what resources am I paying for but no longer using\", \"idle-resource savings\", \"historical idle-resource savings\", \"are these idle resources safe to delete\". Generic Cost, other subcategories, and cross-category requests use azure-advisor.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fplugins\u002Fazure-advisor\u002Fskills\u002Fazure-advisor-cost-optimization\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":117,"name":118,"nameZh":6,"description":119,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":120,"categories":121,"keywords":132,"publishedAt":42},"01M69B4FD57V1MYKRWAJJECTZ7","podcast-generation","Generate AI-powered podcast-style audio narratives using Azure OpenAI's GPT Realtime Mini model via WebSocket. Use when building text-to-speech features, audio narrative generation, podcast creation from content, or integrating with Azure OpenAI Realtime API for real audio output. Covers full-stack implementation from React frontend to Python FastAPI backend with WebSocket streaming.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fpodcast-generation\u002FSKILL.md",[122,125,128,131],{"categoryNo":123,"categoryName":124,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":126,"categoryName":127,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":129,"categoryName":130,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[133,134,135,136,37,137,138,139,140,141,142,143,144,145,146,28,147,148,149,150,151,152,153],"podcast generation","generation","podcast","frontend","azure openai","realtime","react","python","Audio","creation","model","fastapi backend","python fastapi","fastapi","api","streaming","text","narrative","stack","generate","features",{"skillNo":155,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":158,"categories":159,"keywords":161,"publishedAt":42},"01M69B4CYPM5SESY5ZWEFDXEQZ","microsoft-docs","Understand Microsoft technologies by querying official documentation. Use whenever the user asks how something works, wants tutorials, needs configuration options, limits, quotas, or best practices for any Microsoft technology (Azure, .NET, M365, Windows, Power Platform, etc.)—even if they don't mention \"docs.\" If the question is about understanding a concept rather than writing code, this is the right skill.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fmicrosoft-docs\u002FSKILL.md",[160],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[162,9,163,164,165,166,167,37,168,169,170,171,172,173,174,175,30,176,60,177,34,178,179,180],"microsoft docs","docs","documentation","windows","official","cli","MCP","writing","power platform","mcp server","back","concept","power","platform","technology","question","learn mcp","learn","best practices",{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":185,"categories":186,"keywords":188,"publishedAt":42},"01M69B49C3YPD1ZJ3NC0HPCY58","mcp-builder","Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP), Node\u002FTypeScript (MCP SDK), or C#\u002F.NET (Microsoft MCP SDK).","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fmcp-builder\u002FSKILL.md",[187],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[189,168,190,191,192,9,140,193,194,143,195,28,196,197,198,26,199,200,30,201,34,32],"mcp builder","builder","llms","sdk","typescript","model context protocol","building mcp servers","node","integrate","Tools","context","fastmcp","mcp sdk",{"skillNo":203,"name":204,"nameZh":6,"description":205,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":206,"categories":207,"keywords":220,"publishedAt":42},"01M69B467A7CDMFQ0T6Q0ZA12Q","kql","KQL language expertise for writing correct, efficient Kusto Query Language queries. Covers syntax gotchas, join patterns, dynamic types, datetime pitfalls, regex patterns, serialization, memory management, result-size discipline, and advanced functions (geo, vector, graph). USE THIS SKILL whenever writing, debugging, or reviewing KQL queries — even simple ones — because the gotchas section prevents the most common errors that waste tool calls and cause expensive retry cascades. Trigger on: KQL, Kusto, ADX, Azure Data Explorer, Fabric Real-Time Intelligence, EventHouse, Log Analytics, log analysis, data exploration, time series, anomaly detection, summarize, where clause, join, extend, project, let statement, parse operator, extract function, any mention of pipe-forward query syntax.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fkql\u002FSKILL.md",[208,211,212,217],{"categoryNo":209,"categoryName":210,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":213,"categoryName":214,"taxonomyType":215,"taxonomyTypeDesc":216},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",{"categoryNo":218,"categoryName":219,"taxonomyType":215,"taxonomyTypeDesc":216},"01JBSEEDCAT000000000000036","内容创作者",[204,37,169,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,30,237,238,239],"analytics","memory","summarize","exploration","parse","project","time","vector","join","log","pipe","datetime","discipline","time series","regex","anomaly","section","tool","geo",{"skillNo":241,"name":242,"nameZh":6,"description":243,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":244,"categories":245,"keywords":246,"publishedAt":42},"01M69B44HJQ7897EZ7NE7DWQX3","github-issue-creator","Convert raw notes, error logs, voice dictation, or screenshots into crisp GitHub-flavored markdown issue reports. Use when the user pastes bug info, error messages, or informal descriptions and wants a structured GitHub issue. Supports images\u002FGIFs for visual evidence.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fgithub-issue-creator\u002FSKILL.md",[],[247,248,249,250,251,24,252,253,254,255,256,257,30,258,34,28,259,260,261,262,263],"github","github issue creator","issue creator","github issue","issue","notes","screenshots","images","error","evidence","error messages","messages","visual","convert","logs","reports","info"]