--- name: Skill Creator slug: skill-creator-11 category: AI Engineering description: Skill Creator guides creation of effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use it when creating new skills or updating existing ones. github: "https://github.com/microsoft/skills/tree/main/.github/skills/skill-creator" language: TypeScript stars: 2909 forks: 331 install: "npx degit https://github.com/microsoft/skills/tree/main/.github/skills/skill-creator ~/.claude/skills/skill-creator" installs_to: ~/.claude/skills/skill-creator source_path: .github/skills/skill-creator/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/microsoft/skills" added: 2026-08-17T07:10:09.777Z last_synced: 2026-08-17T07:10:09.777Z canonical_url: "https://dirskills.com/skills/skill-creator-11" --- # Skill Creator Skill Creator guides creation of effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use it when creating new skills or updating existing ones. **Install:** ```bash npx degit https://github.com/microsoft/skills/tree/main/.github/skills/skill-creator ~/.claude/skills/skill-creator ``` ## README # 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,