# Skill Creator > 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. - Skill: `thedixitjain/skill-creator-7` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds add thedixitjain/skill-creator-7` - Raw SKILL.md: https://api.skillmd.com/api/skills/thedixitjain/skill-creator-7/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: thedixitjain (https://skillmd.com/u/thedixitjain) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/thedixitjain/skill-creator-7 --- # Skill Creator Guide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and Microsoft Foundry. > **Required Context:** When creating SDK or API skills, users MUST provide the SDK package name, documentation URL, or repository reference for the skill to be based on. ## About Skills Skills are modular knowledge packages that transform general-purpose agents into specialized experts: 1. **Procedural knowledge** — Multi-step workflows for specific domains 2. **SDK expertise** — API patterns, authentication, error handling for Azure services 3. **Domain context** — Schemas, business logic, company-specific patterns 4. **Bundled resources** — Scripts, references, templates for complex tasks --- ## Core Principles ### 1. Concise is Key The context window is a shared resource. Challenge each piece: "Does this justify its token cost?" **For domain/procedural skills**: Agents are already capable. Only add what they don't already know. **For SDK/API skills**: Users MUST provide SDK package name, documentation URL, or repository reference. The skill cannot be created without this context. ### 2. Fresh Documentation First **Azure SDKs change constantly.** Skills should instruct agents to verify documentation: ```markdown ## Before Implementation Search `microsoft-docs` MCP for current API patterns: - Query: "[SDK name] [operation] python" - Verify: Parameters match your installed SDK version ``` ### 3. Degrees of Freedom Match specificity to implementation constraints. High freedom when approaches vary; low freedom when precise execution is required: | Freedom | When | Example | | ---------- | -------------------------------- | ---------------- | | **High** | Multiple valid approaches | Text guidelines | | **Medium** | Preferred pattern with variation | Pseudocode | | **Low** | Must be exact | Specific scripts | ### 4. Progressive Disclosure Skills load in three levels: 1. **Metadata** (~100 words) — Always in context 2. **SKILL.md body** (<5k words) — When skill triggers 3. **References** (unlimited) — As needed **Keep SKILL.md under 500 lines.** Split into reference files when approaching this limit. --- ## Skill Structure **Quick reference:** ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name, description) │ └── Markdown instructions └── Bundled Resources (optional) ├── scripts/ — Executable code ├── references/ — Documentation loaded as needed └── assets/ — Output resources (templates, images) ``` For Azure SDK skills, follow the **Skill Section Order** below. For domain skills, use your judgment to organize logically. ### SKILL.md Essentials - **Frontmatter**: `name` and `description` (description triggers the skill) - **Body**: Keep under 500 lines; split large skills into reference files ### Bundled Resources (Optional) | Type | When to Include | Examples | | ------------- | ---------------------------------------- | ---------------------------------------------------------- | | `scripts/` | Reused code patterns | Auth setup, CLI scripts | | `references/` | Feature deep-dives and overflow examples | `capabilities.md` index, `non-hero-scenarios.md`, API docs | | `assets/` | Output templates | Boilerplate code, images | --- ## Creating Azure SDK Skills When creating skills for Azure SDKs, follow these patterns consistently. ### Token Budget Guidelines (REQUIRED) Every Azure SDK skill MUST stay within these token limits: | Section | Target | Absolute Max | | ----------------------------- | ---------------- | ---------------- | | Installation + Env Vars | 100 tokens | 150 | | Authentication & Lifecycle | 200 tokens | 300 | | Core Workflow (1 example) | 300 tokens | 400 | | Feature Tables | 200 tokens | 300 | | Best Practices (6-8 items) | 200 tokens | 250 | | References (reference/ links) | 100 tokens | 150 | | **Total SKILL.md** | **~1100 tokens** | **~1500 tokens** | **Enforcement**: - Exceeding max limit → refactor into `/references/` subdirectories - When approaching 500 lines → move entire sections to reference files - Annotate with `` immediately below the skill's H1 --- ### Reference Extraction Guide (REQUIRED) Decide what goes in SKILL.md vs. `/references/` using these signals: | Signal | Move to `/references/` | Keep in SKILL.md | | -------------- | ----------------------------------- | ---------------------- | | Use frequency | <20% of typical use | ~80%+ of workflows | | Cognitive load | Advanced patterns, multiple options | Single happy path | | Example length | >10 lines, multiple paths | 1-5 lines, single path | **Content extraction rules:** - **Batch operations** → `/references/batch-operations.md` - **Error handling** (beyond try-except) → `/references/error-handling.md` - **Performance tuning** → `/references/performance.md` - **Alternative workflows** → `/references/workflows-comparison.md` - **Streaming/events** → `/references/streaming.md` - **Advanced auth** → `/references/auth-strategies.md` - **Tool integration** → `/references/tools.md` - **Breaking changes** → `/references/migration.md` **Decision:** Keep common case in SKILL.md, move edge cases to `/references/`. --- ### Core Workflow Discipline (REQUIRED) Every Azure SDK skill must clarify which workflow(s) it documents. **Case 1: Single clear "core workflow"** (majority of services) If one pattern handles ~80% of use cases: 1. Designate it as the core workflow 2. Show ONLY this workflow in SKILL.md (one complete, runnable example) 3. Defer alternatives to `/references/`: - Batch operations → `/references/batch-operations.md` - Error handling → `/references/error-handling.md` - Performance tuning → `/references/performance.md` - Alternative workflows → `/references/workflows-comparison.md` **Example**: Azure Key Vault Secrets (core workflow: retrieve a secret using managed identity). Alternative authentication workflows in `/references/`: local development with `DefaultAzureCredential`, workload identity, and service-principal credentials (client secret or certificate). **Case 2: Multiple equally-valid "core workflows"** (e.g., authentication strategies, deployment targets) If no single pattern dominates: 1. Include every hero scenario in SKILL.md, even when that means multiple equally valid workflows 2. Show one complete, runnable example for each hero scenario in SKILL.md 3. Use `/references/workflows-comparison.md` for trade-offs, secondary variations, and deeper context that would otherwise bloat the main file 4. Do NOT treat valid alternatives as "advanced" when they are core to real usage — they're equally valid, just different contexts **Example**: Azure Identity SDK has several hero scenarios. Keep the primary local-development and production-safe credential flows in SKILL.md, then use `/references/credential-types.md` for deeper comparisons across `AzureCliCredential`, workload identity, service principal variants, and other secondary credential choices. **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 `/references/`. --- ### Skill Section Order Follow this structure (based on existing Azure SDK skills): 1. **Title** — `# SDK Name` 2. **Installation** — `pip install`, `npm install`, etc. 3. **Environment Variables** — Required configuration, with an inline comment explaining when it's required. If using `DefaultAzureCredential` in production, include `AZURE_TOKEN_CREDENTIALS` (set to `prod` or ``) 4. **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). 5. **Core Workflow** — Minimal viable example (per core workflow discipline above) 6. **Feature Tables** — Clients, methods, tools 7. **Best Practices** — Numbered list 8. **Reference Links** — Table linking to `/references/*.md` (for Azure SDK skills, include `capabilities.md` + `non-hero-scenarios.md`) ### Required Authentication & Lifecycle Callout (Python) > **Scope:** Python skills (`-py` suffix) only. Other languages may follow their own idioms. Every 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. ```markdown ## Authentication & Lifecycle > **🔑 Two rules apply to every code sample below:** > > 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI / VS Code / Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account/API keys — they bypass Entra audit and rotation. > - Local dev: `DefaultAzureCredential` works as-is. > - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=`) to constrain the credential chain to production-safe credentials. > 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically: > - Sync: `with (...) as client:` > - Async: `async with (...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`) > > Snippets may abbreviate this setup, but production code should always follow both rules. ``` **Placement rules:** - Insert immediately under the `## Authentication & Lifecycle` heading, before the first code sample. - Do not paraphrase or restructure the wording — the consistency across skills is the point. - 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. - If the SDK is async-only (e.g. `azure-ai-voicelive`), keep both rules but show only the async form in the bullets. - Skip the callout entirely for non-Azure Python skills with no client lifecycle (e.g. `pydantic-models-py`). **Code sample enforcement.** Every client construction in the skill body must demonstrate both rules: - Show `with` / `async with` on every client instantiation in usage examples (not just the auth section). - 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 `_KEY` env var back to the Environment Variables block with a `# Only required for the legacy API-key auth path below` comment. - 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. - For async examples, wrap `DefaultAzureCredential` from `azure.identity.aio` in `async with credential:` alongside the client. ### Authentication Pattern (All Languages) For 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. If 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. ```python # Python — note: client is wrapped in `with` for deterministic cleanup from azure.identity import DefaultAzureCredential, ManagedIdentityCredential # Local dev: DefaultAzureCredential works as-is. credential = DefaultAzureCredential() # Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS. # credential = DefaultAzureCredential(require_envvar=True) # Or use a specific credential directly in production: # See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes # credential = ManagedIdentityCredential() with ServiceClient(endpoint, credential) as client: client.do_thing() ``` ```csharp // C# using Azure.Identity; // Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS= var credential = new DefaultAzureCredential( DefaultAzureCredential.DefaultEnvironmentVariableName ); // Or use a specific credential directly in production: // See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes // var credential = new ManagedIdentityCredential(); var client = new ServiceClient(new Uri(endpoint), credential); ``` ```java // Java import com.azure.identity.AzureIdentityEnvVars; import com.azure.identity.DefaultAzureCredentialBuilder; import com.azure.identity.ManagedIdentityCredential; import com.azure.identity.ManagedIdentityCredentialBuilder; // Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS= TokenCredential credential = new DefaultAzureCredentialBuilder() .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS) .build(); // Or use a specific credential directly in production: // See https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#credential-classes // TokenCredential credential = new ManagedIdentityCredentialBuilder().build(); ServiceClient client = new ServiceClientBuilder() .endpoint(endpoint) .credential(credential) .buildClient(); ``` ```typescript // TypeScript import { DefaultAzureCredential, ManagedIdentityCredential, } from "@azure/identity"; // Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS= const credential = new DefaultAzureCredential({ requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"], }); // Or use a specific credential directly in production: // See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes // const credential = new ManagedIdentityCredential(); const client = new ServiceClient(endpoint, credential); ``` ```go // Go import ( "context" "github.com/Azure/azure-sdk-for-go/sdk/azidentity" "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob" ) ctx := context.Background() // Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS= cred, err := azidentity.NewDefaultAzureCredential(nil) if err != nil { panic(err) } // Or use a specific credential directly in production: // cred, err := azidentity.NewManagedIdentityCredential(nil) client, err := azblob.NewClient("https://.blob.core.windows.net/", cred, nil) if err != nil { panic(err) } _ = client _ = ctx ``` ```rust // Rust use azure_identity::DeveloperToolsCredential; use azure_storage_blob::BlobServiceClient; let credential = DeveloperToolsCredential::new(); // Local dev let client = BlobServiceClient::new( "https://.blob.core.windows.net/", credential, None, )?; ``` **Never hardcode credentials. Use environment variables.** ### Anti-Patterns: What NOT to Do (REQUIRED Reading) **These patterns cause bloat and inefficiency. Every skill author must review this section before writing.** #### Anti-Pattern 1: "Exhaustive API Reference" - ❌ **Don't**: List all 50 SDK methods in a feature table with code samples for every variant - ✅ **Do**: Show 3-5 core methods in a table; link to official Azure API reference for exhaustive list - **Token cost**: Listing all methods + examples = 400-600 tokens wasted - **User impact**: Overwhelming cognitive load; users don't know what to use #### Anti-Pattern 2: "Multiple Ways to Solve One Problem" - ❌ **Don't**: "Here's approach A, B, C, and D to paginate results" in the main body - ✅ **Do**: "Use `ItemPaged` for sync pagination" (primary example); link alternatives to `/references/` - **Token cost**: Each alternate approach = 50-100 tokens; 5 approaches = skill becomes inefficient - **User impact**: Decision paralysis; users re-read everything #### Anti-Pattern 3: "Beginner + Intermediate + Advanced in One Skill" - ❌ **Don't**: Skill that goes from "what is a client?" to "custom retry policies" to "circuit breaker patterns" - ✅ **Do**: Core workflow covers 80% use case; advanced patterns in `/references/` - **Token cost**: Every skill level adds 200-300 tokens; three levels = 600-900 extra tokens - **User impact**: Experts bored, beginners overwhelmed; nobody gets what they need #### Anti-Pattern 4: "Restating Official Documentation" - ❌ **Don't**: "The CosmosClient constructor takes an endpoint (string) and credential (TokenCredential). The endpoint identifies the Azure Cosmos resource..." - ✅ **Do**: Show code: `client = CosmosClient(endpoint, credential)`. Link to official docs: `microsoft-docs` MCP. - **Token cost**: Verbose explanation = 50-100 tokens per parameter; large APIs waste 300+ tokens - **User impact**: Redundant; official docs are authoritative, skill should show usage not repeat them #### Anti-Pattern 5: "Verbose Explanation When Example Suffices" - ❌ **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..." - ✅ **Do**: Show code immediately: `with CosmosClient(endpoint, credential) as client:` --- ### Efficiency Validation (REQUIRED - Phase 2) **During authoring, validate skill efficiency manually, then run the Vally eval if the skill has one under `tests/scenarios//vally/`.** **1. Measure token count:** Use 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 `/references/`. **2. Run anti-pattern checklist:** - [ ] No exhaustive API reference (show 3-5 core methods, not 50) - [ ] No multiple solutions to one problem in SKILL.md - [ ] No beginner+intermediate+advanced mixed - [ ] No restating official docs (code first, link to microsoft-docs) - [ ] No verbose prose (examples first, minimal text) **3. Example count audit:** - [ ] 1 complete example per hero scenario / 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. - [ ] Feature table includes 3-5 core methods (not comprehensive API) - [ ] Max 1 example per best practice bullet **4. Frontmatter validation:** - [ ] `name` matches `.github/skills//SKILL.md` - [ ] `description` includes trigger keywords - [ ] `description` is concise (~200 chars is a good target; schema max is 1,024 chars) - [ ] If included, optional `benchmark_tokens_*` and `benchmark_quality_*` metadata fields are flat strings under `metadata` **4b. Authentication guidance validation** (critical for all credentials): - [ ] If skill uses Azure Identity credentials, verify guidance against the current official credential docs for that language/package (Microsoft Learn where available; otherwise the upstream SDK repo or package docs) - [ ] For Python skills, development guidance may recommend `DefaultAzureCredential` (supports multiple dev credential types) - [ ] 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 - [ ] For Rust skills, development/production guidance reflects the actual supported credentials (`DeveloperToolsCredential` for local dev; a specific production credential such as `ManagedIdentityCredential` for production) - [ ] Link to `/references/auth-strategies.md` or official docs for production credential selection **4c. Run Vally lint/eval (if the skill has a spec under `tests/scenarios//vally/`):** ```bash # If the eval spec uses the shared Rust custom grader plugin, build it first. (cd tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure && npm install && npm run build) vally lint --eval-spec tests/scenarios//vally/eval.yaml \ --grader-plugin tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure \ --strict vally eval --eval-spec tests/scenarios//vally/eval.yaml \ --grader-plugin tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure ``` - [ ] `vally lint` passes with no errors - [ ] `vally eval` passes (no error-severity findings) when `COPILOT_TOKEN` is available; otherwise lint-only is acceptable, matching the [`Vally Evaluation`](../../workflows/vally-evaluation.yml) workflow behavior - [ ] Skills without a `vally/` spec skip this step — it is optional per skill, not required for every skill **5. Spot check:** - [ ] Can a user copy the core workflow and run it immediately? - [ ] Do all examples follow best practices (context managers, appropriate credentials)? - [ ] Are all environment variables documented? **Output:** After validation, annotate the skill header with measured token count: ```markdown # Azure Service SDK ``` --- ### Standard Verb Patterns Azure SDKs use consistent verbs across all languages: | Verb | Behavior | | -------- | ---------------------------- | | `create` | Create new; fail if exists | | `upsert` | Create or update | | `get` | Retrieve; error if missing | | `list` | Return collection | | `delete` | Succeed even if missing | | `begin` | Start long-running operation | ### Language-Specific Patterns See `references/azure-sdk-patterns.md` for detailed patterns including: - **Python**: `ItemPaged`, `LROPoller`, context managers, Sphinx docstrings. 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` / `async with` context managers. - **.NET**: `Response`, `Pageable`, `Operation`, mocking support - **Java**: Builder pattern, `PagedIterable`/`PagedFlux`, Reactor types - **TypeScript**: `PagedAsyncIterableIterator`, `AbortSignal`, browser considerations - **Go**: `context.Context` as first arg, `runtime.Pager[T]` via `New*Pager()` + `More()/NextPage(ctx)`, `runtime.Poller[T]` via `Begin*` + `PollUntilDone(ctx, nil)`, `to.Ptr(...)` helpers, and typed `*azcore.ResponseError` - **Rust**: Installation via `cargo add`, dependency rule for `azure_core`, `Response`, `Pager`, `RequestContent::from()`, `.into_model()`, explicit credential types, RBAC roles for Entra ID authentication ### Required Best Practices in Every Skill (User-Facing) #### Python, .NET, Java, TypeScript, and Go languages **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.** Add both items verbatim (adapted only for language/SDK specifics) as the **first two items** of the Best Practices list. Do not assume users will infer them from examples. **Standard wording (Python; adapt for other languages):** ```markdown 1. **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. 2. **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. 3. **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`). ``` **Variants to apply when the SDK shape differs:** | Skill type | Adjust item #1 to | Adjust item #2 to | | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Async-only SDK (e.g. voicelive) | "This SDK is async-only; use the `.aio` namespace throughout." | keep standard | | 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 | | Provider-pattern (OpenTelemetry exporters/distro) | keep standard | "Call `provider.shutdown()` / `flush()` at process exit to flush telemetry — providers are not context managers." | | 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." | | Identity skill | keep standard | "Use credentials as context managers (`with DefaultAzureCredential() as credential:`) when they own token caches / HTTP transports you want cleaned up; for async, use `async with` on credentials from `azure.identity.aio`." | | FastAPI (non-Azure) | "Pick `def` or `async def` per endpoint based on whether you call async I/O; 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`/`async with` for per-request resources." | | Pure model/schema skill (no I/O, e.g. pydantic) | **skip both** — not applicable | **skip** | **Enforcement in code examples.** Every code example inside the skill must itself obey both rules, so the skill demonstrates what it prescribes: - 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. - Every client instantiation in every example must be wrapped in `with` / `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`). - When async credentials from `azure.identity.aio` appear in an example, wrap them in `async with credential:` alongside the client. #### Rust Language **These rules MUST be explicitly written into every Rust skill's `## Best Practices` section as the first items:** 1. **Use `cargo add` to manage dependencies, never edit `Cargo.toml` directly.** Always use `cargo add ` or `cargo remove ` instead of manually modifying the manifest file. Official crates are published on crates.io and should be added via cargo. 2. **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. 3. **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. 4. **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. 5. **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). 6. **Always verify package versions using crates.io.** Before using a package, check its version on [crates.io](https://crates.io/) to ensure you are using a stable and supported release. ### Example Effective Skills (Benchmark Only Structure-Compliant Skills) **Only benchmark Azure SDK skills that already use the required `references/` layout** (`references/capabilities.md` plus `references/non-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. **A valid benchmark skill should**: 1. Stay at or under the 1,500-token absolute max (see Token Budget Guidelines above) 2. Cover the hero workflow (CRUD or primary operations), not every feature variant 3. Show 1-2 examples per concept, not 3-5 4. Use tables for API summary (credential types, RBAC roles, client hierarchy) 5. Link to official docs via `microsoft-docs` MCP instead of duplicating 6. Move advanced patterns to `/references/` 7. Include `references/capabilities.md` and `references/non-hero-scenarios.md` **Before writing your skill**: Apply the checklist above directly, then mirror only the structure patterns that fit your use case. --- ### Handling Deprecated or Rebranded SDKs When an Azure SDK has been deprecated or rebranded, update skills to guide users toward the current package while maintaining backward compatibility: **1. Add a migration notice at the top of the skill:** ```markdown > **⚠️ 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. > > **For new projects**: Use the `new-package-name` package instead. > > **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. ``` **2. Show both installation options:** ```markdown ## Installation ### Legacy Package (Old Name) \`\`\`xml com.azure azure-old-package 4.2.0 \`\`\` ### Recommended Package (New Name) **For new projects, use the rebranded package:** \`\`\`xml com.azure azure-new-package 1.0.0 \`\`\` > **Note**: The API patterns in this skill apply to both packages. Replace package names and imports as needed when using `azure-new-package`. ``` **3. When to create a new skill vs. update existing:** - **Update existing skill** if the API is largely compatible (same or similar class/method names) - **Create new skill + migration guide** if the API changed significantly (use `references/migration.md`) - **Always cross-reference** between old and new skills **Examples:** - `azure-ai-formrecognizer-java` → `azure-ai-documentintelligence` (rebranded service) - `azure-communication-callingserver-java` → `azure-communication-callautomation` (deprecated, with migration guide) ### Example: Azure SDK Skill Structure ```markdown --- name: skill-creator description: | Azure AI Example SDK for Python. Use for [specific service features]. Triggers: "example service", "create example", "list examples". --- # Azure AI Example SDK ## Installation \`\`\`bash pip install azure-ai-example \`\`\` ## Environment Variables \`\`\`bash AZURE_EXAMPLE_ENDPOINT=https://.example.azure.com AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production \`\`\` ## Authentication & Lifecycle > **🔑 Two rules apply to every code sample below:** > > 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI / VS Code / Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account/API keys — they bypass Entra audit and rotation. > - Local dev: `DefaultAzureCredential` works as-is. > - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=`) to constrain the credential chain to production-safe credentials. > 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically: > - Sync: `with (...) as client:` > - Async: `async with (...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`) > > Snippets may abbreviate this setup, but production code should always follow both rules. \`\`\`python from azure.identity import DefaultAzureCredential, ManagedIdentityCredential from azure.ai.example import ExampleClient # Local dev: DefaultAzureCredential works as-is. credential = DefaultAzureCredential() # Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS. # credential = DefaultAzureCredential(require_envvar=True) # Or use a specific credential directly in production: # See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes # credential = ManagedIdentityCredential() with ExampleClient( endpoint=os.environ["AZURE_EXAMPLE_ENDPOINT"], credential=credential, ) as client: item = client.get_item("example") \`\`\` ## Core Workflow \`\`\`python with ExampleClient(endpoint=endpoint, credential=credential) as client: # Create item = client.create_item(name="example", data={...}) # List (pagination handled automatically) for item in client.list_items(): print(item.name) # Long-running operation poller = client.begin_process(item.id) result = poller.result() # Cleanup client.delete_item(item.id) \`\`\` ## Reference Files | File | Contents | | -------------------------------------------------------------------- | ------------------------------------------------------ | | [references/capabilities.md](references/capabilities.md) | Capability index (hero coverage + links to deep-dives) | | [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Concrete non-hero examples | | [references/tools.md](references/tools.md) | Tool integrations | | [references/streaming.md](references/streaming.md) | Event streaming patterns | ``` --- ## Skill Creation Process 1. **Gather SDK Context** — User provides SDK/API reference (REQUIRED) 2. **Understand** — Research SDK patterns from official docs 3. **Plan** — Identify reusable resources and product area category 4. **Create** — Write SKILL.md in `.github/skills//` 5. **Categorize** — Create symlink in `skills///` 6. **Test** — Create acceptance criteria and test scenarios 7. **Document** — Update README.md skill catalog …(truncated)