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.md file 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:
The skill-creator currently generates only
SKILL.mdbut doesn't include instructions for generatingreferences/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:Every Azure SDK skill MUST include a
references/examples.mdfile containingcomplete, 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:
# <Azure Service> <Language> SDK - Examples— include BOM approach where available
code for every major API operation the SDK exposes. Each example must:
"string")service-specific exceptions
multiple operations together (create → use → cleanup)
Rules:
---horizontal rules between major sectionsIDisposable (C#), Result (Rust)
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: