skill-creator

# 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 `<!-- Token Count: ~XXXX (target: 1100, max: 1500) -->` 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 `<specific_credential>`) 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=<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. ``` **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 `<SERVICE>_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=<specific_credential> 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=<specific_credential> 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,