{"slug":"skill-creator","title":"skill-creator","summary":"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.","platform":"GitHub Copilot","tags":[],"authorName":"Ciza","authorSlug":"ciza","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-12T21:05:26.531573Z","repo":{"url":"https://github.com/microsoft/skills","stars":3052,"forks":351,"license":"MIT","updatedAt":"2026-09-24T16:38:17Z"},"bodyHtml":"
\n

name: 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

Skill Creator

\n

Guide 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

Skills are modular knowledge packages that transform general-purpose agents into specialized experts:

\n
    \n
  1. Procedural knowledge — Multi-step workflows for specific domains
    2. \n
  2. SDK expertise — API patterns, authentication, error handling for Azure services
    3. \n
  3. Domain context — Schemas, business logic, company-specific patterns
    4. \n
  4. Bundled resources — Scripts, references, templates for complex tasks
    5. \n
\n
\n

Core Principles

\n

1. Concise is Key

\n

The context window is a shared resource. Challenge each piece: \"Does this justify its token cost?\"

\n

For domain/procedural skills: Agents are already capable. Only add what they don't already know.

\n

For SDK/API skills: Users MUST provide SDK package name, documentation URL, or repository reference. The skill cannot be created without this context.

\n

2. Fresh Documentation First

\n

Azure SDKs change constantly. Skills should instruct agents to verify documentation:

\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

3. Degrees of Freedom

\n

Match specificity to implementation constraints. High freedom when approaches vary; low freedom when precise execution is required:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FreedomWhenExample
HighMultiple valid approachesText guidelines
MediumPreferred pattern with variationPseudocode
LowMust be exactSpecific scripts
\n

4. Progressive Disclosure

\n

Skills load in three levels:

\n
    \n
  1. Metadata (~100 words) — Always in context
    2. \n
  2. SKILL.md body (<5k words) — When skill triggers
    3. \n
  3. References (unlimited) — As needed
    4. \n
\n

Keep SKILL.md under 500 lines. Split into reference files when approaching this limit.

\n
\n

Skill Structure

\n

Quick reference:

\n
skill-name/\n├── SKILL.md (required)\n│   ├── YAML frontmatter (name, description)\n│   └── Markdown instructions\n└── Bundled Resources (optional)\n    ├── scripts/      — Executable code\n    ├── references/   — Documentation loaded as needed\n    └── assets/       — Output resources (templates, images)\n
\n

For Azure SDK skills, follow the Skill Section Order below. For domain skills, use your judgment to organize logically.

\n

SKILL.md Essentials

\n\n

Bundled Resources (Optional)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TypeWhen to IncludeExamples
scripts/Reused code patternsAuth setup, CLI scripts
references/Feature deep-dives and overflow examplescapabilities.md index, non-hero-scenarios.md, API docs
assets/Output templatesBoilerplate code, images
\n
\n

Creating Azure SDK Skills

\n

When creating skills for Azure SDKs, follow these patterns consistently.

\n

Token Budget Guidelines (REQUIRED)

\n

Every Azure SDK skill MUST stay within these token limits:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SectionTargetAbsolute Max
Installation + Env Vars100 tokens150
Authentication & Lifecycle200 tokens300
Core Workflow (1 example)300 tokens400
Feature Tables200 tokens300
Best Practices (6-8 items)200 tokens250
References (reference/ links)100 tokens150
Total SKILL.md~1100 tokens~1500 tokens
\n

Enforcement:

\n\n
\n

Reference Extraction Guide (REQUIRED)

\n

Decide what goes in SKILL.md vs. /references/ using these signals:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SignalMove to /references/Keep in SKILL.md
Use frequency<20% of typical use~80%+ of workflows
Cognitive loadAdvanced patterns, multiple optionsSingle happy path
Example length>10 lines, multiple paths1-5 lines, single path
\n

Content extraction rules:

\n\n

Decision: Keep common case in SKILL.md, move edge cases to /references/.

\n
\n

Core Workflow Discipline (REQUIRED)

\n

Every Azure SDK skill must clarify which workflow(s) it documents.

\n

Case 1: Single clear \"core workflow\" (majority of services)

\n

If one pattern handles ~80% of use cases:

\n
    \n
  1. Designate it as the core workflow
    2. \n
  2. Show ONLY this workflow in SKILL.md (one complete, runnable example)
    3. \n
  3. Defer alternatives to /references/:\n\n
    4. \n
\n

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).

\n

Case 2: Multiple equally-valid \"core workflows\" (e.g., authentication strategies, deployment targets)

\n

If no single pattern dominates:

\n
    \n
  1. Include every hero scenario in SKILL.md, even when that means multiple equally valid workflows
    2. \n
  2. Show one complete, runnable example for each hero scenario in SKILL.md
    3. \n
  3. Use /references/workflows-comparison.md for trade-offs, secondary variations, and deeper context that would otherwise bloat the main file
    4. \n
  4. Do NOT treat valid alternatives as \"advanced\" when they are core to real usage — they're equally valid, just different contexts
    5. \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 /references/credential-types.md for deeper comparisons across AzureCliCredential, workload identity, service principal variants, and other secondary credential choices.

\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 /references/.

\n
\n

Skill Section Order

\n

Follow this structure (based on existing Azure SDK skills):

\n
    \n
  1. Title — # SDK Name
    2. \n
  2. Installation — pip install, npm install, etc.
    3. \n
  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 <specific_credential>)
    4. \n
  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) below).
    5. \n
  5. Core Workflow — Minimal viable example (per core workflow discipline above)
    6. \n
  6. Feature Tables — Clients, methods, tools
    7. \n
  7. Best Practices — Numbered list
    8. \n
  8. Reference Links — Table linking to /references/*.md (for Azure SDK skills, include capabilities.md + non-hero-scenarios.md)
    9. \n
\n

Required Authentication & Lifecycle Callout (Python)

\n
\n

Scope: Python skills (-py suffix) only. Other languages may follow their own idioms.

\n
\n

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.

\n
## Authentication & Lifecycle\n\n> **\uD83D\uDD11 Two rules apply to every code sample below:**\n>\n> 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.\n>    - Local dev: `DefaultAzureCredential` works as-is.\n>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_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 <Client>(...) as client:`\n>    - Async: `async with <Client>(...) 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

Placement rules:

\n\n

Code sample enforcement. Every client construction in the skill body must demonstrate both rules:

\n\n

Authentication Pattern (All Languages)

\n

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.

\n

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.

\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://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes\n# credential = ManagedIdentityCredential()\nwith ServiceClient(endpoint, credential) as client:\n    client.do_thing()\n
\n
// C#\nusing Azure.Identity;\n\n// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>\nvar credential = new DefaultAzureCredential(\n    DefaultAzureCredential.DefaultEnvironmentVariableName\n);\n// Or use a specific credential directly in production:\n// See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes\n// var credential = new ManagedIdentityCredential();\nvar client = new ServiceClient(new Uri(endpoint), credential);\n
\n
// Java\nimport com.azure.identity.AzureIdentityEnvVars;\nimport com.azure.identity.DefaultAzureCredentialBuilder;\nimport com.azure.identity.ManagedIdentityCredential;\nimport com.azure.identity.ManagedIdentityCredentialBuilder;\n\n// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>\nTokenCredential credential = new DefaultAzureCredentialBuilder()\n    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)\n    .build();\n// Or use a specific credential directly in production:\n// See https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#credential-classes\n// TokenCredential credential = new ManagedIdentityCredentialBuilder().build();\nServiceClient client = new ServiceClientBuilder()\n    .endpoint(endpoint)\n    .credential(credential)\n    .buildClient();\n
\n
// TypeScript\nimport {\n  DefaultAzureCredential,\n  ManagedIdentityCredential,\n} from \"@azure/identity\";\n// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>\nconst credential = new DefaultAzureCredential({\n  requiredEnvVars: [\"AZURE_TOKEN_CREDENTIALS\"],\n});\n// Or use a specific credential directly in production:\n// See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes\n// const credential = new ManagedIdentityCredential();\nconst client = new ServiceClient(endpoint, credential);\n
\n
// Go\nimport (\n  \"context\"\n\n  \"github.com/Azure/azure-sdk-for-go/sdk/azidentity\"\n  \"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob\"\n)\n\nctx := context.Background()\n\n// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>\ncred, err := azidentity.NewDefaultAzureCredential(nil)\nif err != nil {\n  panic(err)\n}\n\n// Or use a specific credential directly in production:\n// cred, err := azidentity.NewManagedIdentityCredential(nil)\n\nclient, err := azblob.NewClient(\"https://<account>.blob.core.windows.net/\", cred, nil)\nif err != nil {\n  panic(err)\n}\n\n_ = client\n_ = ctx\n
\n
// Rust\nuse azure_identity::DeveloperToolsCredential;\nuse azure_storage_blob::BlobServiceClient;\n\nlet credential = DeveloperToolsCredential::new(); // Local dev\nlet client = BlobServiceClient::new(\n    \"https://<account>.blob.core.windows.net/\",\n    credential,\n    None,\n)?;\n
\n

Never hardcode credentials. Use environment variables.

\n

Anti-Patterns: What NOT to Do (REQUIRED Reading)

\n

These patterns cause bloat and inefficiency. Every skill author must review this section before writing.

\n

Anti-Pattern 1: \"Exhaustive API Reference\"

\n\n

Anti-Pattern 2: \"Multiple Ways to Solve One Problem\"

\n\n

Anti-Pattern 3: \"Beginner + Intermediate + Advanced in One Skill\"

\n\n

Anti-Pattern 4: \"Restating Official Documentation\"

\n\n

Anti-Pattern 5: \"Verbose Explanation When Example Suffices\"

\n\n
\n

Efficiency Validation (REQUIRED - Phase 2)

\n

During authoring, validate skill efficiency manually, then run the Vally eval if the skill has one under tests/scenarios/<skill-name>/vally/.

\n

1. Measure token count:

\n

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/.

\n

2. Run anti-pattern checklist:

\n\n

3. Example count audit:

\n\n

4. Frontmatter validation:

\n\n

4b. Authentication guidance validation (critical for all credentials):

\n\n

4c. Run Vally lint/eval (if the skill has a spec under tests/scenarios/<skill-name>/vally/):

\n
# If the eval spec uses the shared Rust custom grader plugin, build it first.\n(cd tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure && npm install && npm run build)\n\nvally lint --eval-spec tests/scenarios/<skill-name>/vally/eval.yaml \\\n  --grader-plugin tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure \\\n  --strict\n\nvally eval --eval-spec tests/scenarios/<skill-name>/vally/eval.yaml \\\n  --grader-plugin tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure\n
\n\n

5. Spot check:

\n\n

Output: After validation, annotate the skill header with measured token count:

\n
# Azure Service SDK\n\n<!-- Token Count: ~1180 (target: 1100, max: 1500) -->\n
\n
\n

Standard Verb Patterns

\n

Azure SDKs use consistent verbs across all languages:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
VerbBehavior
createCreate new; fail if exists
upsertCreate or update
getRetrieve; error if missing
listReturn collection
deleteSucceed even if missing
beginStart long-running operation
\n

Language-Specific Patterns

\n

See references/azure-sdk-patterns.md for detailed patterns including:

\n\n

Required Best Practices in Every Skill (User-Facing)

\n

Python, .NET, Java, TypeScript, and Go languages

\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

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.

\n

Standard wording (Python; adapt for other languages):

\n
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.\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

Variants to apply when the SDK shape differs:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Skill typeAdjust item #1 toAdjust 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 skillskeep standard\"Use with httpx.Client(...) as client: (sync) or async with httpx.AsyncClient(...) as client: (async) so connections pool and close deterministically.\"
Identity skillkeep 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 applicableskip
\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

Rust Language

\n

These rules MUST be explicitly written into every Rust skill's ## Best Practices section as the first items:

\n
    \n

  1. Use cargo add to manage dependencies, never edit Cargo.toml directly. Always use cargo add <crate> or cargo remove <crate> instead of manually modifying the manifest file. Official crates are published on crates.io and should be added via cargo.

    \n
    2. \n

  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.

    \n
    3. \n

  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.

    \n
    4. \n

  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.

    \n
    5. \n

  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).

    \n
    6. \n

  6. Always verify package versions using crates.io. Before using a package, check its version on crates.io to ensure you are using a stable and supported release.

    \n
    7. \n

  7. Future-proof #[non_exhaustive] model structs and enums. Azure Rust SDK request/response 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/azure-sdk-patterns.md (Model Types) for the full example.

    \n
    8. \n
\n

Example Effective Skills (Benchmark Only Structure-Compliant Skills)

\n

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.

\n

A valid benchmark skill should:

\n
    \n
  1. Stay at or under the 1,500-token absolute max (see Token Budget Guidelines above)
    2. \n
  2. Cover the hero workflow (CRUD or primary operations), not every feature variant
    3. \n
  3. Show 1-2 examples per concept, not 3-5
    4. \n
  4. Use tables for API summary (credential types, RBAC roles, client hierarchy)
    5. \n
  5. Link to official docs via microsoft-docs MCP instead of duplicating
    6. \n
  6. Move advanced patterns to /references/
    7. \n
  7. Include references/capabilities.md and references/non-hero-scenarios.md
    8. \n
\n

Before writing your skill: Apply the checklist above directly, then mirror only the structure patterns that fit your use case.

\n
\n

Handling Deprecated or Rebranded SDKs

\n

When an Azure SDK has been deprecated or rebranded, update skills to guide users toward the current package while maintaining backward compatibility:

\n

1. Add a migration notice at the top of the skill:

\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

2. Show both installation options:

\n
## Installation\n\n### Legacy Package (Old Name)\n\n\\`\\`\\`xml\n<dependency>\n<groupId>com.azure</groupId>\n<artifactId>azure-old-package</artifactId>\n<version>4.2.0</version>\n</dependency>\n\\`\\`\\`\n\n### Recommended Package (New Name)\n\n**For new projects, use the rebranded package:**\n\n\\`\\`\\`xml\n<dependency>\n<groupId>com.azure</groupId>\n<artifactId>azure-new-package</artifactId>\n<version>1.0.0</version>\n</dependency>\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

3. When to create a new skill vs. update existing:

\n\n

Examples:

\n\n

Example: Azure SDK Skill Structure

\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://<resource>.example.azure.com\nAZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production\n\\`\\`\\`\n\n## Authentication & Lifecycle\n\n> **\uD83D\uDD11 Two rules apply to every code sample below:**\n>\n> 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.\n>    - Local dev: `DefaultAzureCredential` works as-is.\n>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_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 <Client>(...) as client:`\n>    - Async: `async with <Client>(...) 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://learn.microsoft.com/python/api/overview/azure/identity-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/capabilities.md](references/capabilities.md)             | Capability index (hero coverage + links to deep-dives) |\n| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Concrete non-hero examples                             |\n| [references/tools.md](references/tools.md)                           | Tool integrations                                      |\n| [references/streaming.md](references/streaming.md)                   | Event streaming patterns                               |\n
\n
\n

Skill Creation Process

\n
    \n
  1. Gather SDK Context — User provides SDK/API reference (REQUIRED)
    2. \n
  2. Understand — Research SDK patterns from official docs
    3. \n
  3. Plan — Identify reusable resources and product area category
    4. \n
  4. Create — Write SKILL.md in .github/skills/<skill-name>/
    5. \n
  5. Categorize — Create symlink in skills/<language>/<category>/
    6. \n
  6. Test — Create acceptance criteria and test scenarios
    7. \n
  7. Document — Update README.md skill catalog
    8. \n
  8. Iterate — Refine based on real usage
    9. \n
\n

Step 1: Gather SDK Context (REQUIRED)

\n

Before creating any SDK skill, the user MUST provide:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
RequiredExamplePurpose
SDK Packageazure-ai-agents, Azure.AI.OpenAI, azblobIdentifies the exact SDK
Documentation URLhttps://learn.microsoft.com/en-us/azure/ai-services/...Primary source of truth
Repository (optional)Azure/azure-sdk-for-python, Azure/azure-sdk-for-goFor code patterns
\n

Prompt the user if not provided:

\n
To 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/dotnet/ts/java/go)\n
\n

Search official docs first:

\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

Step 2: Understand the Skill

\n

Gather concrete examples:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Example TaskReusable Resource
Same auth code each timeCode example in SKILL.md
Complex streaming patternsreferences/streaming.md
Tool configurationsreferences/tools.md
Error handling patternsreferences/error-handling.md
\n

Step 3: Plan Product Area Category

\n

Skills are organized by language and product area in the skills/ directory via symlinks.

\n

Product Area Categories:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CategoryDescriptionExamples
foundryAI Foundry, agents, projects, inferenceazure-ai-agents-py, azure-ai-projects-py
dataStorage, Cosmos DB, Tables, Data Lakeazure-cosmos-py, azure-storage-blob-py
messagingEvent Hubs, Service Bus, Event Gridazure-eventhub-py, azure-servicebus-py
monitoringOpenTelemetry, App Insights, Queryazure-monitor-opentelemetry-py
identityAuthentication, DefaultAzureCredentialazure-identity-py
securityKey Vault, secrets, keys, certificatesazure-keyvault-py
integrationAPI Management, App Configurationazure-appconfiguration-py
computeBatch, ML computeazure-compute-batch-java
containerContainer Registry, ACRazure-containerregistry-py
\n

Determine the category based on:

\n
    \n
  1. Azure service family (Storage → data, Event Hubs → messaging)
    2. \n
  2. Primary use case (AI agents → foundry)
    3. \n
  3. Existing skills in the same service area
    4. \n
\n

Step 4: Create the Skill

\n

Location: .github/skills/<skill-name>/SKILL.md

\n

Naming convention:

\n\n

For Azure SDK skills:

\n
    \n
  1. Search microsoft-docs MCP for current API patterns
    2. \n
  2. Verify against installed SDK version
    3. \n
  3. Follow the section order above
    4. \n
  4. Include cleanup code in examples
    5. \n
  5. Add feature comparison tables
    6. \n
\n

Write bundled resources first, then SKILL.md.

\n

Quality assurance before finalizing:

\n
    \n
  1. Measure section token counts as you write (use model playground token counter)
    2. \n
  2. Compare to Token Budget Guidelines targets
    3. \n
  3. Validate against anti-patterns checklist (see Anti-Patterns section)
    4. \n
  4. Extract to /references/ if section exceeds max tokens
    5. \n
  5. Run Efficiency Validation checklist, including vally lint/vally eval if the skill has a spec (see Efficiency Validation)
    6. \n
  6. Optionally add benchmark_tokens_* and benchmark_quality_* fields under the frontmatter's metadata mapping (flat string values)
    7. \n
  7. Add token count comment to skill header for future maintenance
    8. \n
\n

Frontmatter (Enhanced with Benchmarking Metadata):

\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

Metadata fields: (all values are strings, per the Agent Skills metadata spec — string keys mapped to string values)

\n\n

Step 5: Categorize with Symlinks

\n

After creating the skill in .github/skills/, create a symlink in the appropriate category:

\n
# Pattern: skills/<language>/<category>/<short-name> -> ../../../.github/skills/<full-skill-name>\n\n# Example for azure-ai-agents-py in python/foundry:\ncd skills/python/foundry\nln -s ../../../.github/skills/azure-ai-agents-py agents\n\n# Example for azure-cosmos-db-py in python/data:\ncd skills/python/data\nln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db\n\n# Example for azure-storage-blob-go in go/data:\ncd skills/go/data\nln -s ../../../.github/skills/azure-storage-blob-go blob\n
\n

Symlink naming:

\n\n

Verify the symlink:

\n
ls -la skills/python/foundry/agents\n# Should show: agents -> ../../../.github/skills/azure-ai-agents-py\n
\n

Step 6: Create Tests

\n

Every skill MUST have acceptance criteria and test scenarios.

\n

6.1 Create Acceptance Criteria

\n

Location: tests/scenarios/<skill-name>/acceptance-criteria.md

\n
\n

Keep acceptance criteria in the tests/ tree (never beside SKILL.md inside the skill folder).

\n
\n

Source materials (in priority order):

\n
    \n
  1. Official Microsoft Learn docs (via microsoft-docs MCP)
    2. \n
  2. SDK source code from the repository
    3. \n
  3. Existing reference files in the skill
    4. \n
\n

Format:

\n
# Acceptance Criteria: <skill-name>\n\n**SDK**: `package-name`\n**Repository**: https://github.com/Azure/azure-sdk-for-<language>\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 / account key when Entra is supported\n\n\\`\\`\\`python\nclient = MyClient.from_connection_string(os.environ[\"CONNECTION_STRING\"]) # Bypasses Entra audit/rotation\n\\`\\`\\`\n\n#### ❌ INCORRECT: Bare client without context manager\n\n\\`\\`\\`python\nclient = MyClient(endpoint, credential) # Leaks HTTP transport on exception / interpreter exit\nclient.do_thing()\n\\`\\`\\`\n
\n

Critical patterns to document:

\n\n

6.2 Create Test Scenarios

\n

Location: tests/scenarios/<skill-name>/scenarios.yaml

\n
config:\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

Scenario design principles:

\n\n

6.3 Run Tests

\n
cd tests\npnpm install\n\n# Check skill is discovered\npnpm harness --list\n\n# Run in mock mode (fast, deterministic)\npnpm harness <skill-name> --mock --verbose\n\n# Run with Ralph Loop (iterative improvement)\npnpm harness <skill-name> --ralph --mock --max-iterations 5 --threshold 85\n
\n

Success criteria:

\n\n

Step 7: Update Documentation

\n

After creating the skill:

\n
    \n

  1. Update README.md — Add the skill to the appropriate language section in the Skill Catalog

    \n\n
    2. \n

  2. Regenerate GitHub Pages data — Run the extraction script and rebuild the docs site from one scoped directory change

    \n
    (cd docs-site && npx tsx scripts/extract-skills.ts && npm run build)\n
    \n

    This updates docs-site/src/data/skills.json which feeds the Astro-based docs site, then rebuilds the site into docs/, which is served by GitHub Pages.

    \n
    3. \n

  3. Verify AGENTS.md — Ensure the skill count is accurate

    \n
    4. \n
\n
\n

Step 8: Regenerate Existing Skills from Latest SDK Sources

\n

Use this workflow when an existing skill has stale examples, outdated API signatures,\nor changed package guidance.

\n
    \n
  1. Identify canonical source files first
    2. \n
\n

For Azure SDK language skills, use official upstream source docs and examples as the source of truth:

\n\n
    \n
  1. Refresh skill content surgically
    2. \n
\n\n

API Surface Parity Gate (required for every regenerated skill)

\n

Use the language-specific authoritative source as the contract for every snippet in the regenerated skill:

\n\n

Before finalizing any regenerated skill:

\n
    \n
  1. Identify each SDK type/method shown in snippets (clients, operation groups, model constructors, enum members, long-running methods like begin_*).
    2. \n
  2. Verify each symbol and signature against the authoritative source for that language/package (see above).
    3. \n
  3. If the authoritative source shows a different shape (for example nested properties=... models, renamed methods, begin_* LRO methods), update the snippet to match.
    4. \n
  4. Re-check imports so model/client modules match the authoritative source exactly.
    5. \n
  5. Do not keep compatibility shortcuts that contradict authoritative examples in primary snippets.
    6. \n
\n

Scenario Coverage Gate (required for every regenerated skill, all languages)

\n

Regeneration is not complete when snippets compile — it is complete when the skill demonstrates real usage breadth.

\n

Before finalizing any regenerated skill:

\n
    \n
  1. Identify hero scenarios from the current authoritative docs/samples for that SDK (Microsoft Learn where available; otherwise the upstream SDK repo and package documentation).
    2. \n
  2. 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).
    3. \n
  3. Add/refresh test scenarios so hero flows are validated by harness patterns.
    4. \n
  4. Add at least one important non-hero scenario (for example: update/patch, delete/cleanup, export/import, advanced auth mode, paging/filtering, retries/error 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.
    5. \n
  5. For Azure SDK skills, structure references/ as:\n\n
    6. \n
  6. 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.
    7. \n
  7. 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.
    8. \n
\n

Regeneration Workflow Step 3: Validate Regenerated Skill Behavior

\n
(cd tests && pnpm harness <skill-name> --mock --verbose)\n
\n

If the skill has a Vally scenario, run that eval as well (locally or in CI) before finalizing.

\n

Rust regeneration gate (required for Rust skills):

\n

When regenerating any Rust skill, verify the generated ## Best Practices section contains these exact first two rules:

\n
    \n
  1. Use cargo add to manage dependencies, never edit Cargo.toml directly
    2. \n
  2. Add azure_core only when importing azure_core types directly
    3. \n
\n

Use a content check before finalizing:

\n
rg -n \"Use `cargo add` to manage dependencies, never edit `Cargo.toml` directly|Add `azure_core` only when importing `azure_core` types directly\" .github/plugins/azure-sdk-rust/skills/**/SKILL.md\n
\n

The regeneration is not complete unless both lines are present in each affected Rust skill.

\n

Regeneration Workflow Step 4: Regenerate Docs Artifacts After Refresh

\n
(cd docs-site && npx tsx scripts/extract-skills.ts && npm run build)\n
\n

Regeneration Workflow Step 5: Record What Changed

\n

In the PR/commit notes, include:

\n\n

Python plugin batch recipe: azure-sdk-python

\n

Use this when the request is \"regenerate all Python skills under azure-sdk-python.\"

\n
    \n
  1. Scope the exact targets first
    2. \n
\n
# Canonical source of truth for Python plugin skills\nls .github/plugins/azure-sdk-python/skills/*/SKILL.md\n
\n\n
    \n
  1. For each skill, refresh from authoritative sources
    2. \n
\n\n
    \n
  1. Apply Python enforcement rules consistently
    2. \n
\n\n","files":[{"path":"references/azure-sdk-patterns.md","sizeBytes":32551,"isText":true},{"path":"references/output-patterns.md","sizeBytes":4176,"isText":true},{"path":"references/workflows.md","sizeBytes":3196,"isText":true},{"path":"scripts/init_skill.py","sizeBytes":10863,"isText":true},{"path":"scripts/package_skill.py","sizeBytes":3288,"isText":true},{"path":"scripts/quick_validate.py","sizeBytes":3523,"isText":true},{"path":"SKILL.md","sizeBytes":68147,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"notes-only","suspicious":0,"notes":4,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-12T21:53:01.18379Z","sha256":"0755F0B4DDC2D87194CA0E6F7E6A446C45177530483793AD40C8216074E98565","sizeBytes":41283},"review":null,"source":{"repositoryUrl":"https://github.com/microsoft/skills","path":".github/skills/skill-creator","license":"MIT","commit":"23d0dac5f83f268166a17f0bc7dc6c73dc348a33","subtreeSha":"4A31DFB0B157C9808262C589AE3B11445D1EF07E9AE9F01373567BB1D21AECCE","lastSyncedAt":"2026-09-25T06:48:53.330584Z"},"reviewedAt":"2026-08-12T22:00:21.5869Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/microsoft/skills/tree/main/.github/skills/skill-creator"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart"},{"target":"git","command":"git clone https://github.com/microsoft/skills.git"}]}