Skip to content

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

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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions