Add references/examples.md generation instructions to skill-creator
The skill-creator currently generates only SKILL.md but doesn't include instructions for generating references/examples.md. The original Java reference examples were added manually (without updating the skill-creator).
A proposed a structured spec for references/examples.md (required for all SDK skills) covering:
Reference File: references/examples.md (Required for all SDK skills)
Every Azure SDK skill MUST include a
references/examples.mdfile containing complete, runnable code examples. This file supplements SKILL.md (which shows only the core workflow) with comprehensive coverage of all major SDK operations. Structure — follow this exact order:
- Title:
# <Azure Service> <Language> SDK - Examples - One-line description: "Comprehensive code examples for the for ."
- Table of Contents: Markdown links to all H2 sections below
- Dependency/Installation: Full dependency block (Maven XML, pip, npm, NuGet, Cargo) — include BOM approach where available
- Client Creation: Show ALL supported auth methods, each as an H3:
- Service-specific credential (API key, shared key, connection string)
- DefaultAzureCredential (mark as "Recommended")
- Async client variant
- Operation Sections (one H2 per logical group): Complete, copy-paste-ready
code for every major API operation the SDK exposes. Each example must:
- Import all required classes
- Show realistic parameter values (not just
"string") - Print or return results so the user sees output
- Include inline comments only where behavior is non-obvious
- Error Handling: Try/catch with HTTP status code switching and service-specific exceptions
- Complete Application Example: A single end-to-end class/script using multiple operations together (create → use → cleanup)
- Environment Variables: Bash block listing all required env vars
- Best Practices: Numbered list (5-8 items) of SDK-specific guidance Rules:
- Use
---horizontal rules between major sections - Every code block must be self-contained (copy-paste-runnable in isolation)
- Do NOT truncate examples — show complete method bodies
- Match the language idioms: Builder pattern (Java), async/await (TS/Python), IDisposable (C#), Result (Rust)
- Target 400-800 lines total — enough for comprehensive coverage without bloat
Adding this to the skill-creator would ensure consistency across all languages when skills are regenerated.
Impact: All language skills would need regeneration once this is added.
Context:
- Current skill-creator: https://github.com/microsoft/skills/blob/main/.github/skills/skill-creator/SKILL.md
- Original PR that added Java reference examples (no skill-creator changes): TBD (by @thegovind)
Source: microsoft/skills