[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DHKRSTYYC13H4KXSE6Y0FD":3,"skill-same:01M7DHKRSTYYC13H4KXSE6Y0FD":72},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":27,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7DHKRSTYYC13H4KXSE6Y0FD","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.","ak2dev\u002Fagentguard","ak2dev","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F233005497?v=4","01M7DGWK3E3XCC276C6YRFSN05","01M7DGWK4J2A9WQ44CS5CRP4R6",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Fbench\u002Fcorpus\u002Fbenign\u002Freal-ms-skill-creator\u002FSKILL.md",[],[],"2026-11-15 14:19:17",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","634c25395a24b98cd6125453ad4abb65517bcabb","bench\u002Fcorpus\u002Fbenign\u002Freal-ms-skill-creator","https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard","https:\u002F\u002Fsite-bionic8.vercel.app","https:\u002F\u002Fgithub.com\u002Fak2dev","2026-11-11 02:37:06",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add ak2dev\u002Fagentguard --skill skill-creator",{"tool":36,"command":37},"bunx","bunx skills add ak2dev\u002Fagentguard --skill skill-creator",{"tool":39,"command":40},"pnpm","pnpm dlx skills add ak2dev\u002Fagentguard --skill skill-creator","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Fbench\u002Fcorpus\u002Fbenign\u002Freal-ms-skill-creator\u002FSKILL.md",true,[44,50,54,58,64,68],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"references\u002Fazure-sdk-patterns.md","REFERENCE","参考文档",32551,"https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Fbench\u002Fcorpus\u002Fbenign\u002Freal-ms-skill-creator\u002Freferences\u002Fazure-sdk-patterns.md",{"path":51,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Foutput-patterns.md",4176,"https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Fbench\u002Fcorpus\u002Fbenign\u002Freal-ms-skill-creator\u002Freferences\u002Foutput-patterns.md",{"path":55,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fworkflows.md",3196,"https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Fbench\u002Fcorpus\u002Fbenign\u002Freal-ms-skill-creator\u002Freferences\u002Fworkflows.md",{"path":59,"resourceType":60,"resourceTypeDesc":61,"sizeBytes":62,"sourceHtmlUrl":63},"scripts\u002Finit_skill.py","SCRIPT","脚本",10863,"https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Fbench\u002Fcorpus\u002Fbenign\u002Freal-ms-skill-creator\u002Fscripts\u002Finit_skill.py",{"path":65,"resourceType":60,"resourceTypeDesc":61,"sizeBytes":66,"sourceHtmlUrl":67},"scripts\u002Fpackage_skill.py",3288,"https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Fbench\u002Fcorpus\u002Fbenign\u002Freal-ms-skill-creator\u002Fscripts\u002Fpackage_skill.py",{"path":69,"resourceType":60,"resourceTypeDesc":61,"sizeBytes":70,"sourceHtmlUrl":71},"scripts\u002Fquick_validate.py",3523,"https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Fbench\u002Fcorpus\u002Fbenign\u002Freal-ms-skill-creator\u002Fscripts\u002Fquick_validate.py",[73,80,85,90,95,101],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M7DJ7GBSJBJ32GXNQXVAMNYK","csv-tool","Summarize CSV files and report column statistics.","https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Ffixtures\u002Frules\u002FAG-SYS-002\u002Fpositive\u002Ffault\u002Fcsv-tool\u002FSKILL.md",[],[],{"skillNo":81,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":18},"01M7DJ7F00PA7EHFM39RVCC8R5","https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Ffixtures\u002Frules\u002FAG-SYS-002\u002Fnegative\u002Fnormal\u002Fcsv-tool\u002FSKILL.md",[],[],{"skillNo":86,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":18},"01M7DJ7DP7KDW7MYY5Q0R0JFEN","https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Ffixtures\u002Frules\u002FAG-SYS-001\u002Fpositive\u002Ftoo-large\u002Fcsv-tool\u002FSKILL.md",[],[],{"skillNo":91,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":18},"01M7DJ7C3VA0KQ8Q9ESNX6AJHE","https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Ffixtures\u002Frules\u002FAG-SYS-001\u002Fnegative\u002Fsmall\u002Fcsv-tool\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":18},"01M7DJ7AQZTGY5YADQX73TRB7K","pdf","https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Ffixtures\u002Frules\u002FAG-SKL-TYP-002\u002Fpositive\u002Fother-publisher\u002Fpdf\u002FSKILL.md",[],[],{"skillNo":102,"name":97,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":18},"01M7DJ7831XDVWS4W9SAAKBJHX","https:\u002F\u002Fgithub.com\u002Fak2dev\u002Fagentguard\u002Fblob\u002Fmain\u002Ffixtures\u002Frules\u002FAG-SKL-TYP-002\u002Fnegative\u002Fsame-publisher\u002Fpdf\u002FSKILL.md",[],[]]