AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

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.

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--skill-creator at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

SKILL.md · 24000

art 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<T>, Pageable<T>, Operation<T>, 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<T>, Pager<T>, 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):

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

  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 to ensure you are using a stable and supported release.

  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.

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:

> **⚠️ 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:

## Installation

### Legacy Package (Old Name)

\`\`\`xml
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-old-package</artifactId>
<version>4.2.0</version>
</dependency>
\`\`\`

### Recommended Package (New Name)

**For new projects, use the rebranded package:**

\`\`\`xml
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-new-package</artifactId>
<version>1.0.0</version>
</dependency>
\`\`\`

> **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

---
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://<resource>.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=<specific_credential>`) 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 <Client>(...) as client:`
>    - Async: `async with <Client>(...) 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/<skill-name>/
  5. Categorize — Create symlink in skills/<language>/<category>/
  6. Test — Create acceptance criteria and test scenarios
  7. Document — Update README.md skill catalog
  8. Iterate — Refine based on real usage

Step 1: Gather SDK Context (REQUIRED)

Before creating any SDK skill, the user MUST provide:

| Required | Example | Purpose | | ------------------------- | --------------------------------------------------------- | ------------------------ | | SDK Package | azure-ai-agents, Azure.AI.OpenAI, azblob | Identifies the exact SDK | | Documentation URL | https://learn.microsoft.com/en-us/azure/ai-services/... | Primary source of truth | | Repository (optional) | Azure/azure-sdk-for-python, Azure/azure-sdk-for-go | For code patterns |

Prompt the user if not provided:

To create this skill, I need:
1. The SDK package name (e.g., azure-ai-projects)
2. The Microsoft Learn documentation URL or GitHub repo
3. The target language (py/dotnet/ts/java/go)

Search official docs first:

# Use microsoft-docs MCP to get current API patterns
# Query: "[SDK name] [operation] [language]"
# Verify: Parameters match the latest SDK version

Step 2: Understand the Skill

Gather concrete examples:

  • "What SDK operations should this skill cover?"
  • "What triggers should activate this skill?"
  • "What errors do developers commonly encounter?"

| Example Task | Reusable Resource | | -------------------------- | ------------------------------ | | Same auth code each time | Code example in SKILL.md | | Complex streaming patterns | references/streaming.md | | Tool configurations | references/tools.md | | Error handling patterns | references/error-handling.md |

Step 3: Plan Product Area Category

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

Product Area Categories:

| Category | Description | Examples | | ------------- | --------------------------------------- | -------------------------------------------- | | foundry | AI Foundry, agents, projects, inference | azure-ai-agents-py, azure-ai-projects-py | | data | Storage, Cosmos DB, Tables, Data Lake | azure-cosmos-py, azure-storage-blob-py | | messaging | Event Hubs, Service Bus, Event Grid | azure-eventhub-py, azure-servicebus-py | | monitoring | OpenTelemetry, App Insights, Query | azure-monitor-opentelemetry-py | | identity | Authentication, DefaultAzureCredential | azure-identity-py | | security | Key Vault, secrets, keys, certificates | azure-keyvault-py | | integration | API Management, App Configuration | azure-appconfiguration-py | | compute | Batch, ML compute | azure-compute-batch-java | | container | Container Registry, ACR | azure-containerregistry-py |

Determine the category based on:

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

Step 4: Create the Skill

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

Naming convention:

  • azure-<service>-<subservice>-<language>
  • Examples: azure-ai-agents-py, azure-cosmos-java, azure-storage-blob-ts, azure-storage-blob-go
  • For Go skills in documentation prose, use the short package name (for example azblob).
  • Use the full module import path only in code/import examples (for example github.com/Azure/azure-sdk-for-go/sdk/storage/azblob).

For Azure SDK skills:

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

Write bundled resources first, then SKILL.md.

Quality assurance before finalizing:

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

Frontmatter (Enhanced with Benchmarking Metadata):

---
name: azure-service-py
description: |
  Azure Service SDK for Python. Use for [specific features].
  Triggers: "service name", "create resource", "specific operation".
metadata:
  benchmark_tokens_estimated: "1180"
  benchmark_tokens_target: "1100"
  benchmark_tokens_max: "1500"
  benchmark_quality_single_core_workflow: "true"
  benchmark_quality_examples_focused: "true"
  benchmark_quality_no_prose_bloat: "true"
  benchmark_quality_anti_patterns_checked: "true"
---

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

  • benchmark_tokens_estimated — Actual measured token count
  • benchmark_tokens_target — Target efficiency (typically 1100)
  • benchmark_tokens_max — Absolute ceiling (1500; split if exceeded)
  • benchmark_quality_* — Individual anti-pattern checks, each a "true"/"false" string (e.g., benchmark_quality_single_core_workflow)

Step 5: Categorize with Symlinks

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

# Pattern: skills/<language>/<category>/<short-name> -> ../../../.github/skills/<full-skill-name>

# Example for azure-ai-agents-py in python/foundry:
cd skills/python/foundry
ln -s ../../../.github/skills/azure-ai-agents-py agents

# Example for azure-cosmos-db-py in python/data:
cd skills/python/data
ln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db

# Example for azure-storage-blob-go in go/data:
cd skills/go/data
ln -s ../../../.github/skills/azure-storage-blob-go blob

Symlink naming:

  • Use short, descriptive names (e.g., agents, cosmos, blob)
  • Remove the azure- prefix and language suffix
  • Match existing patterns in the category

Verify the symlink:

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

Step 6: Create Tests

Every skill MUST have acceptance criteria and test scenarios.

6.1 Create Acceptance Criteria

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

Keep acceptance criteria in the tests/ tree (never beside `SKI