Skip to content

Add references/examples.md generation instructions to skill-creator #311

@samvaity

Description

@samvaity

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:

  1. Title: # <Azure Service> <Language> SDK - Examples
  2. One-line description: "Comprehensive code examples for the for ."
  3. Table of Contents: Markdown links to all H2 sections below
  4. Dependency/Installation: Full dependency block (Maven XML, pip, npm, NuGet, Cargo)
    — include BOM approach where available
  5. 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
  6. 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
  7. Error Handling: Try/catch with HTTP status code switching and
    service-specific exceptions
  8. Complete Application Example: A single end-to-end class/script using
    multiple operations together (create → use → cleanup)
  9. Environment Variables: Bash block listing all required env vars
  10. 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:

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions