Skip to content

Instantly share code, notes, and snippets.

@kvenkatrajan

kvenkatrajan/condensed-sdk-references-analysis.md

Created February 20, 2026 16:03
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save kvenkatrajan/e62e448d411f6bf30bba6fc124d59436 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save kvenkatrajan/e62e448d411f6bf30bba6fc124d59436 to your computer and use it in GitHub Desktop.
Download ZIP
Condensed SDK Reference — Change Analysis & CI/CD Pipeline
Raw
condensed-sdk-references-analysis.md

Condensed SDK Reference — Change Analysis

Based on the Condensed SDK Reference Process (Hybrid Inline).

Target repo: githubcopilotforAzure/plugin/skills Source repo: microsoft-skills/.github/plugins

Source path structure (by language plugin):

Plugin Source path
azure-sdk-python .github/plugins/azure-sdk-python/skills/<skill-name>/SKILL.md
azure-sdk-dotnet .github/plugins/azure-sdk-dotnet/skills/<skill-name>/SKILL.md
azure-sdk-typescript .github/plugins/azure-sdk-typescript/skills/<skill-name>/SKILL.md
azure-sdk-java .github/plugins/azure-sdk-java/skills/<skill-name>/SKILL.md
azure-sdk-rust .github/plugins/azure-sdk-rust/skills/<skill-name>/SKILL.md
azure-skills (consumers) .github/plugins/azure-skills/skills/<skill-name>/SKILL.md

Overview

Skills are sandboxed — a skill's SKILL.md can only reference files within its own folder tree. Cross-skill file references do not work. The decided approach embeds a brief quick-reference (<900 bytes per language) into each consumer skill's references/sdk/ directory, covering the 80% common-use scenario while directing users to the full plugin skill for advanced patterns.

Key principles:

  • Best practices are preserved in full — they are guardrails and are never dropped
  • LLM-aware condensation — omit code patterns LLMs already know (e.g., DefaultAzureCredential usage, blob upload/download, async patterns); only include what LLMs get wrong (correct package names, non-obvious import paths, guardrails)
  • Measured average: ~873 bytes (85% reduction from source)

Template

Each condensed file at <skill>/references/sdk/<source-skill-name>.md follows:

# <Service> — <Language> SDK Quick Reference

> Condensed from **<source-skill-name>**. Full patterns in the
> **<source-skill-name>** plugin skill if installed.

## Install
<package-install-command>

## Quick Start
<2-3 lines: import + client init — only if the API name/import path
 is non-obvious or Azure-specific. Omit patterns an LLM already knows.>

## Best Practices
<ALL best practices from source — never drop guardrails>

## Non-Obvious Patterns (optional)
<2-3 line snippets ONLY for patterns an LLM would NOT reliably
 generate — unusual import paths, Azure-specific config kwargs,
 non-standard API shapes. Omit if all patterns are well-known.>

Target size: <900 bytes. Measured average: ~873 bytes (~85% reduction from source).

LLM-Aware Condensation

Omit (LLM already knows):

  • DefaultAzureCredential() creation and usage
  • ManagedIdentityCredential() with client_id kwarg
  • ChainedTokenCredential composition
  • BlobServiceClient upload/download operations
  • Async context managers (async with ... as client)
  • Standard OpenTelemetry APIs (Resource.create, trace.get_tracer)

Include (LLM gets wrong):

  • Correct, current package names
  • Exact import paths for Azure-specific APIs
  • Best practices / guardrails (non-negotiable)
  • Non-standard configuration patterns (non-guessable kwargs)

Worked Example: azure-identity-py.md (5,608 → 874 bytes, 84% reduction)

# Authentication — Python SDK Quick Reference

> Condensed from **azure-identity-py**. Full patterns (async,
> ChainedTokenCredential, token caching, all credential types)
> in the **azure-identity-py** plugin skill if installed.

## Install
pip install azure-identity

## Quick Start
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

## Best Practices
- Use DefaultAzureCredential for code that runs locally and in Azure
- Never hardcode credentials — use environment variables or managed identity
- Prefer managed identity in production Azure deployments
- Use ChainedTokenCredential when you need a custom credential order
- Close async credentials explicitly or use context managers
- Set AZURE_CLIENT_ID env var for user-assigned managed identities
- Exclude unused credentials to speed up authentication

Cross-Reference Mapping (84 entries across 12 consumer skills)

1. azure-ai — 14 condensed files

Create directory: azure-ai/references/sdk/

File Source Skill Content Focus
azure-search-documents-py.md azure-search-documents-py Python AI Search client, vector/hybrid queries
azure-search-documents-ts.md azure-search-documents-ts TypeScript AI Search client
azure-search-documents-dotnet.md azure-search-documents-dotnet .NET AI Search client
azure-ai-openai-dotnet.md azure-ai-openai-dotnet .NET OpenAI SDK, chat completions
azure-ai-vision-imageanalysis-py.md azure-ai-vision-imageanalysis-py Python image analysis
azure-ai-vision-imageanalysis-java.md azure-ai-vision-imageanalysis-java Java image analysis
azure-ai-transcription-py.md azure-ai-transcription-py Python speech transcription
azure-ai-translation-text-py.md azure-ai-translation-text-py Python text translation
azure-ai-translation-ts.md azure-ai-translation-ts TypeScript translation
azure-ai-document-intelligence-dotnet.md azure-ai-document-intelligence-dotnet .NET Document Intelligence/OCR
azure-ai-document-intelligence-ts.md azure-ai-document-intelligence-ts TypeScript Document Intelligence
azure-ai-contentsafety-py.md azure-ai-contentsafety-py Python content safety
azure-ai-contentsafety-ts.md azure-ai-contentsafety-ts TypeScript content safety
azure-ai-contentsafety-java.md azure-ai-contentsafety-java Java content safety

SKILL.md change: Add an ## SDK Quick References section before "Service Details":

## SDK Quick References

For programmatic access to these services, see the condensed SDK guides:

- **AI Search**: [Python](references/sdk/azure-search-documents-py.md) | [TypeScript](references/sdk/azure-search-documents-ts.md) | [.NET](references/sdk/azure-search-documents-dotnet.md)
- **OpenAI**: [.NET](references/sdk/azure-ai-openai-dotnet.md)
- **Vision**: [Python](references/sdk/azure-ai-vision-imageanalysis-py.md) | [Java](references/sdk/azure-ai-vision-imageanalysis-java.md)
- **Transcription**: [Python](references/sdk/azure-ai-transcription-py.md)
- **Translation**: [Python](references/sdk/azure-ai-translation-text-py.md) | [TypeScript](references/sdk/azure-ai-translation-ts.md)
- **Document Intelligence**: [.NET](references/sdk/azure-ai-document-intelligence-dotnet.md) | [TypeScript](references/sdk/azure-ai-document-intelligence-ts.md)
- **Content Safety**: [Python](references/sdk/azure-ai-contentsafety-py.md) | [TypeScript](references/sdk/azure-ai-contentsafety-ts.md) | [Java](references/sdk/azure-ai-contentsafety-java.md)

2. azure-storage — 11 condensed files

Create directory: azure-storage/references/sdk/

File Source Skill Content Focus
azure-storage-blob-py.md azure-storage-blob-py Python BlobServiceClient, upload/download
azure-storage-blob-ts.md azure-storage-blob-ts TypeScript blob client
azure-storage-blob-java.md azure-storage-blob-java Java blob client
azure-storage-blob-rust.md azure-storage-blob-rust Rust blob client
azure-storage-queue-py.md azure-storage-queue-py Python queue send/receive
azure-storage-queue-ts.md azure-storage-queue-ts TypeScript queue client
azure-storage-file-share-py.md azure-storage-file-share-py Python file share client
azure-storage-file-share-ts.md azure-storage-file-share-ts TypeScript file share client
azure-storage-file-datalake-py.md azure-storage-file-datalake-py Python Data Lake Gen2
azure-data-tables-py.md azure-data-tables-py Python table entities
azure-data-tables-java.md azure-data-tables-java Java table entities

SKILL.md change: Replace or augment the existing ## Azure SDKs section (line 82) with:

## SDK Quick References

For building applications with Azure Storage SDKs, see the condensed guides:

- **Blob Storage**: [Python](references/sdk/azure-storage-blob-py.md) | [TypeScript](references/sdk/azure-storage-blob-ts.md) | [Java](references/sdk/azure-storage-blob-java.md) | [Rust](references/sdk/azure-storage-blob-rust.md)
- **Queue Storage**: [Python](references/sdk/azure-storage-queue-py.md) | [TypeScript](references/sdk/azure-storage-queue-ts.md)
- **File Shares**: [Python](references/sdk/azure-storage-file-share-py.md) | [TypeScript](references/sdk/azure-storage-file-share-ts.md)
- **Data Lake**: [Python](references/sdk/azure-storage-file-datalake-py.md)
- **Tables**: [Python](references/sdk/azure-data-tables-py.md) | [Java](references/sdk/azure-data-tables-java.md)

For full package listing across all languages, see [SDK Usage Guide](references/sdk-usage.md).

Note: Keep the existing references/sdk-usage.md as the comprehensive package reference; the new condensed files serve as quick-start code guides.

3. azure-compliance — 9 condensed files

Create directory: azure-compliance/references/sdk/

File Source Skill Content Focus
azure-keyvault-py.md azure-keyvault-py Python Key Vault (secrets/keys/certs)
azure-keyvault-secrets-ts.md azure-keyvault-secrets-ts TypeScript secrets client
azure-keyvault-secrets-rust.md azure-keyvault-secrets-rust Rust secrets client
azure-security-keyvault-keys-dotnet.md azure-security-keyvault-keys-dotnet .NET key management
azure-security-keyvault-keys-java.md azure-security-keyvault-keys-java Java key management
azure-keyvault-keys-rust.md azure-keyvault-keys-rust Rust key management
azure-keyvault-keys-ts.md azure-keyvault-keys-ts TypeScript key management
azure-keyvault-certificates-rust.md azure-keyvault-certificates-rust Rust certificate management
azure-security-keyvault-secrets-java.md azure-security-keyvault-secrets-java Java secrets management

SKILL.md change: Add ## SDK Quick References section:

## SDK Quick References

For programmatic Key Vault access, see the condensed SDK guides:

- **Key Vault (Python)**: [Secrets/Keys/Certs](references/sdk/azure-keyvault-py.md)
- **Secrets**: [TypeScript](references/sdk/azure-keyvault-secrets-ts.md) | [Rust](references/sdk/azure-keyvault-secrets-rust.md) | [Java](references/sdk/azure-security-keyvault-secrets-java.md)
- **Keys**: [.NET](references/sdk/azure-security-keyvault-keys-dotnet.md) | [Java](references/sdk/azure-security-keyvault-keys-java.md) | [TypeScript](references/sdk/azure-keyvault-keys-ts.md) | [Rust](references/sdk/azure-keyvault-keys-rust.md)
- **Certificates**: [Rust](references/sdk/azure-keyvault-certificates-rust.md)

4. microsoft-foundry — 8 condensed files

Create directory: microsoft-foundry/references/sdk/

File Source Skill Content Focus
azure-ai-projects-py.md azure-ai-projects-py Python AIProjectClient, agents
azure-ai-projects-dotnet.md azure-ai-projects-dotnet .NET AI Projects client
azure-ai-projects-ts.md azure-ai-projects-ts TypeScript AI Projects client
azure-ai-projects-java.md azure-ai-projects-java Java AI Projects client
agent-framework-azure-ai-py.md agent-framework-azure-ai-py Python Agent Framework
agents-v2-py.md agents-v2-py Python Agents v2 patterns
azure-ai-evaluation-py.md azure-ai-evaluation-py Python evaluation SDK
azure-search-documents-py.md azure-search-documents-py Python AI Search (for RAG)

SKILL.md change: Update ### Language-Specific Quick References section (line 566) to add:

### SDK Quick References

- **AI Projects**: [Python](references/sdk/azure-ai-projects-py.md) | [.NET](references/sdk/azure-ai-projects-dotnet.md) | [TypeScript](references/sdk/azure-ai-projects-ts.md) | [Java](references/sdk/azure-ai-projects-java.md)
- **Agent Framework**: [Python](references/sdk/agent-framework-azure-ai-py.md)
- **Agents v2**: [Python](references/sdk/agents-v2-py.md)
- **Evaluation**: [Python](references/sdk/azure-ai-evaluation-py.md)
- **AI Search (RAG)**: [Python](references/sdk/azure-search-documents-py.md)

5. entra-app-registration — 8 condensed files

Create directory: entra-app-registration/references/sdk/

File Source Skill Content Focus
azure-identity-py.md azure-identity-py Python DefaultAzureCredential, managed identity
azure-identity-dotnet.md azure-identity-dotnet .NET DefaultAzureCredential
azure-identity-ts.md azure-identity-ts TypeScript DefaultAzureCredential
azure-identity-java.md azure-identity-java Java DefaultAzureCredential
azure-identity-rust.md azure-identity-rust Rust credential patterns
azure-keyvault-py.md azure-keyvault-py Python Key Vault for secret storage
azure-keyvault-secrets-ts.md azure-keyvault-secrets-ts TypeScript Key Vault secrets
microsoft-azure-webjobs-extensions-authentication-events-dotnet.md (same name) .NET auth events extension

SKILL.md change: Add ## SDK Quick References section after ## Security Best Practices and before ## References:

## SDK Quick References

- **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md) | [Rust](references/sdk/azure-identity-rust.md)
- **Key Vault (secrets)**: [Python](references/sdk/azure-keyvault-py.md) | [TypeScript](references/sdk/azure-keyvault-secrets-ts.md)
- **Auth Events**: [.NET](references/sdk/microsoft-azure-webjobs-extensions-authentication-events-dotnet.md)

6. azure-prepare — 8 condensed files

Create directory: azure-prepare/references/sdk/

File Source Skill Content Focus
azd-deployment.md azd-deployment azd init/up/deploy commands
azure-identity-py.md azure-identity-py Python auth for prepared apps
azure-identity-dotnet.md azure-identity-dotnet .NET auth for prepared apps
azure-identity-ts.md azure-identity-ts TypeScript auth for prepared apps
azure-identity-java.md azure-identity-java Java auth for prepared apps
azure-appconfiguration-py.md azure-appconfiguration-py Python App Configuration
azure-appconfiguration-ts.md azure-appconfiguration-ts TypeScript App Configuration
azure-appconfiguration-java.md azure-appconfiguration-java Java App Configuration

SKILL.md change: Add ## SDK Quick References section:

## SDK Quick References

- **Azure Developer CLI**: [azd](references/sdk/azd-deployment.md)
- **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md)
- **App Configuration**: [Python](references/sdk/azure-appconfiguration-py.md) | [TypeScript](references/sdk/azure-appconfiguration-ts.md) | [Java](references/sdk/azure-appconfiguration-java.md)

7. azure-observability — 8 condensed files

Create directory: azure-observability/references/sdk/

File Source Skill Content Focus
azure-monitor-opentelemetry-py.md azure-monitor-opentelemetry-py Python OpenTelemetry distro
azure-monitor-opentelemetry-ts.md azure-monitor-opentelemetry-ts TypeScript OpenTelemetry
azure-monitor-opentelemetry-exporter-py.md azure-monitor-opentelemetry-exporter-py Python OTel exporter
azure-monitor-query-py.md azure-monitor-query-py Python log/metric queries
azure-monitor-query-java.md azure-monitor-query-java Java log/metric queries
azure-monitor-ingestion-py.md azure-monitor-ingestion-py Python log ingestion
azure-monitor-ingestion-java.md azure-monitor-ingestion-java Java log ingestion
azure-mgmt-applicationinsights-dotnet.md azure-mgmt-applicationinsights-dotnet .NET App Insights management

SKILL.md change: Add ## SDK Quick References section before "Service Details":

## SDK Quick References

For programmatic access to monitoring services, see the condensed SDK guides:

- **OpenTelemetry**: [Python](references/sdk/azure-monitor-opentelemetry-py.md) | [TypeScript](references/sdk/azure-monitor-opentelemetry-ts.md) | [Python Exporter](references/sdk/azure-monitor-opentelemetry-exporter-py.md)
- **Monitor Query**: [Python](references/sdk/azure-monitor-query-py.md) | [Java](references/sdk/azure-monitor-query-java.md)
- **Log Ingestion**: [Python](references/sdk/azure-monitor-ingestion-py.md) | [Java](references/sdk/azure-monitor-ingestion-java.md)
- **App Insights Mgmt**: [.NET](references/sdk/azure-mgmt-applicationinsights-dotnet.md)

8. azure-deploy — 5 condensed files

Create directory: azure-deploy/references/sdk/

File Source Skill Content Focus
azd-deployment.md azd-deployment azd deploy/up commands
azure-identity-py.md azure-identity-py Python auth for deployments
azure-identity-dotnet.md azure-identity-dotnet .NET auth for deployments
azure-identity-ts.md azure-identity-ts TypeScript auth for deployments
azure-identity-java.md azure-identity-java Java auth for deployments

SKILL.md change: Add ## SDK Quick References section:

## SDK Quick References

- **Azure Developer CLI**: [azd](references/sdk/azd-deployment.md)
- **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md)

9. azure-postgres — 4 condensed files

Create directory: azure-postgres/references/sdk/

File Source Skill Content Focus
azure-postgres-ts.md azure-postgres-ts TypeScript pg client with Entra auth
azure-identity-py.md azure-identity-py Python token-based Postgres auth
azure-identity-ts.md azure-identity-ts TypeScript token-based Postgres auth
azure-resource-manager-postgresql-dotnet.md (same name) .NET PostgreSQL management SDK

SKILL.md change: Add ## SDK Quick References section:

## SDK Quick References

- **PostgreSQL Client**: [TypeScript](references/sdk/azure-postgres-ts.md)
- **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [TypeScript](references/sdk/azure-identity-ts.md)
- **PostgreSQL Mgmt**: [.NET](references/sdk/azure-resource-manager-postgresql-dotnet.md)

10. azure-aigateway — 4 condensed files

Create directory: azure-aigateway/references/sdk/

File Source Skill Content Focus
azure-ai-contentsafety-py.md azure-ai-contentsafety-py Python content safety
azure-ai-contentsafety-ts.md azure-ai-contentsafety-ts TypeScript content safety
azure-mgmt-apimanagement-py.md azure-mgmt-apimanagement-py Python APIM management
azure-mgmt-apimanagement-dotnet.md azure-mgmt-apimanagement-dotnet .NET APIM management

SKILL.md change: Add ## SDK Quick References section:

## SDK Quick References

- **Content Safety**: [Python](references/sdk/azure-ai-contentsafety-py.md) | [TypeScript](references/sdk/azure-ai-contentsafety-ts.md)
- **API Management**: [Python](references/sdk/azure-mgmt-apimanagement-py.md) | [.NET](references/sdk/azure-mgmt-apimanagement-dotnet.md)

11. appinsights-instrumentation — 4 condensed files

Create directory: appinsights-instrumentation/references/sdk/

File Source Skill Content Focus
azure-monitor-opentelemetry-py.md azure-monitor-opentelemetry-py Python OpenTelemetry distro
azure-monitor-opentelemetry-ts.md azure-monitor-opentelemetry-ts TypeScript OpenTelemetry
azure-monitor-opentelemetry-exporter-py.md azure-monitor-opentelemetry-exporter-py Python OTel exporter
azure-monitor-opentelemetry-exporter-java.md azure-monitor-opentelemetry-exporter-java Java OTel exporter

SKILL.md change: Add ## SDK Quick References section after "Guidelines":

## SDK Quick References

- **OpenTelemetry Distro**: [Python](references/sdk/azure-monitor-opentelemetry-py.md) | [TypeScript](references/sdk/azure-monitor-opentelemetry-ts.md)
- **OpenTelemetry Exporter**: [Python](references/sdk/azure-monitor-opentelemetry-exporter-py.md) | [Java](references/sdk/azure-monitor-opentelemetry-exporter-java.md)

12. azure-cost-optimization — 1 condensed file

Create directory: azure-cost-optimization/references/sdk/

File Source Skill Content Focus
azure-resource-manager-redis-dotnet.md (same name) .NET Redis management SDK

SKILL.md change: Add ## SDK Quick References section:

## SDK Quick References

- **Redis Management**: [.NET](references/sdk/azure-resource-manager-redis-dotnet.md)

Skills Needing No Changes

These skills (under .github/plugins/azure-skills/skills/) have no SDK cross-references per the mapping:

Skill Reason
azure-validate Infrastructure validation, no SDK code generation
azure-diagnostics Diagnostics via MCP/CLI, no SDK patterns needed
azure-kusto KQL queries via MCP tools, no client SDK needed
azure-resource-visualizer Diagram generation, no SDK interaction
azure-rbac RBAC selection, no SDK patterns needed
azure-resource-lookup Resource lookup, no SDK patterns needed

Summary

Metric Count
Total consumer skills (under azure-skills plugin) 18
Skills requiring changes 12
Skills with no changes needed 6
New references/sdk/ directories to create 12
New condensed .md files to create 84
SKILL.md files to update (add links section) 12
Total file operations 96 (84 creates + 12 edits)
Target size per condensed file <900 bytes
Measured average 873 bytes (85% reduction)

CI/CD Generation Pipeline

Repositories

Repo Role Path
microsoft/skills Source — SDK reference SKILL.md files .github/plugins/<plugin>/skills/<skill-name>/SKILL.md
githubcopilotforAzure Target — consumer skills with condensed references plugin/skills/<consumer-skill>/references/sdk/<source-skill-name>.md

Plugin → Language Resolution

The source skill name suffix determines which plugin directory to read from:

Suffix Plugin directory
-py azure-sdk-python
-dotnet azure-sdk-dotnet
-ts azure-sdk-typescript
-java azure-sdk-java
-rust azure-sdk-rust
(no lang suffix, e.g. azd-deployment) Check all plugins or maintain explicit mapping

Pipeline Configuration

# mapping.yml — machine-readable cross-reference (generate from this doc)
source_repo: microsoft/skills
source_base: .github/plugins
target_base: plugin/skills

plugins:
  azure-sdk-python:    { suffix: "-py" }
  azure-sdk-dotnet:    { suffix: "-dotnet" }
  azure-sdk-typescript: { suffix: "-ts" }
  azure-sdk-java:      { suffix: "-java" }
  azure-sdk-rust:      { suffix: "-rust" }

consumers:
  azure-ai:
    - azure-search-documents-py
    - azure-search-documents-ts
    - azure-search-documents-dotnet
    - azure-ai-openai-dotnet
    # ... (full 84-entry list from cross-reference mapping above)
  azure-storage:
    - azure-storage-blob-py
    # ...

Pipeline Steps

Step 1: Trigger

Trigger: PR merge or push to `microsoft/skills` repo
Filter:  .github/plugins/azure-sdk-*/skills/*/SKILL.md

Detect which source SKILL.md files changed:

git diff --name-only HEAD~1 -- '.github/plugins/azure-sdk-*/skills/*/SKILL.md'

If no SDK SKILL.md files changed, skip pipeline. Otherwise, extract changed skill names:

# e.g. ".github/plugins/azure-sdk-python/skills/azure-storage-blob-py/SKILL.md"
#  →   "azure-storage-blob-py"

Step 2: Resolve Source Paths

For each changed source skill, resolve its full path using the suffix→plugin mapping:

azure-storage-blob-py
  → suffix: -py
  → plugin: azure-sdk-python
  → path:   .github/plugins/azure-sdk-python/skills/azure-storage-blob-py/SKILL.md

For full regeneration (not incremental), iterate all 84 entries in the mapping.

Step 3: Fetch & Parse Source SKILL.md

Clone or fetch from https://github.com/microsoft/skills. For each source skill, parse the SKILL.md to extract:

Section Extraction method Required
Install First code block after ## Install heading, or line matching pip install / npm install / dotnet add / cargo add / Maven <dependency> Yes
Quick Start First code block after ## Quick Start or ## Getting Started — only the import + client init lines (2-3 lines) Yes
Best Practices All list items under ## Best Practices heading — preserve every item, never drop Yes
Non-Obvious Patterns Code blocks containing Azure-specific import paths, unusual kwargs, non-standard API shapes that an LLM would get wrong Optional

Regex patterns for extraction:

# Install section
install_match = re.search(r'## Install.*?\n```\w*\n(.*?)\n```', content, re.DOTALL)

# Quick Start section
quickstart_match = re.search(r'## Quick Start.*?\n```\w*\n(.*?)\n```', content, re.DOTALL)

# Best Practices section (numbered or bulleted list)
bp_match = re.search(r'## Best Practices\n((?:[-*\d].*\n?)+)', content)

Step 4: Apply Condensation Template

For each extracted source, generate the condensed markdown:

# {service_name} — {language} SDK Quick Reference

> Condensed from **{source_skill_name}**. Full patterns ({2-3 advanced topics})
> in the **{source_skill_name}** plugin skill if installed.

## Install
{install_command}

## Quick Start
```{lang}
{quick_start_code}

Best Practices

{all_best_practices}


**Condensation rules:**
- Target: <900 bytes (hard warn at 1200 bytes)
- Quick Start: only include if import path or client init is non-obvious
- Best Practices: **ALL items preserved — this is non-negotiable**
- Non-Obvious Patterns: include only if API has genuinely surprising behavior

**LLM-aware filtering** (optional, use LLM or heuristics):
- Omit: `DefaultAzureCredential` usage, standard async patterns, basic CRUD
- Keep: Unusual import paths, Azure-specific kwargs, non-standard API shapes

#### Step 5: Write to Consumer Skill Directories

For each consumer skill, write the condensed files to the target repo:

target_repo/plugin/skills/{consumer_skill}/references/sdk/{source_skill_name}.md


Create `references/sdk/` directory if it doesn't exist.

**Deduplication**: Several source skills appear in multiple consumers (e.g., `azure-identity-py` → `entra-app-registration`, `azure-prepare`, `azure-deploy`, `azure-postgres`). Generate the condensed content **once per source skill**, then copy to all mapped consumers. This is by design — skills are sandboxed and cannot cross-reference.

#### Step 6: Update Consumer SKILL.md Link Sections

For each consumer skill, regenerate the `## SDK Quick References` section in its SKILL.md:

```python
# Group condensed files by service, then by language
links = group_by_service(consumer_mapping[consumer_skill])

section = "## SDK Quick References\n\n"
for service, langs in links.items():
    line = f"- **{service}**: " + " | ".join(
        f"[{lang}](references/sdk/{filename})" for lang, filename in langs
    )
    section += line + "\n"

Insertion point (per consumer skill):

  • If ## SDK Quick References already exists → replace it
  • Otherwise insert before ## Service Details, ## MCP Tools, or at end of file

Step 7: Validate

Run validation checks before committing:

# 1. All 84 mapped files exist
for file in $(cat mapping.json | jq -r '.files[]'); do
  test -f "plugin/skills/$file" || echo "MISSING: $file"
done

# 2. Size checks
find plugin/skills/*/references/sdk/ -name "*.md" | while read f; do
  size=$(wc -c < "$f")
  [ "$size" -gt 1200 ] && echo "WARN: $f is ${size} bytes (target <900)"
done

# 3. All 12 consumer SKILL.md files have link sections
for skill in azure-ai azure-storage azure-compliance microsoft-foundry \
  entra-app-registration azure-prepare azure-observability azure-deploy \
  azure-postgres azure-aigateway appinsights-instrumentation azure-cost-optimization; do
  grep -q "SDK Quick References" "plugin/skills/$skill/SKILL.md" \
    || echo "MISSING LINKS: $skill"
done

# 4. Required sections present in each condensed file
find plugin/skills/*/references/sdk/ -name "*.md" | while read f; do
  grep -q "## Install" "$f"         || echo "NO INSTALL: $f"
  grep -q "## Best Practices" "$f"  || echo "NO BEST PRACTICES: $f"
  grep -q "Condensed from" "$f"     || echo "NO ATTRIBUTION: $f"
done

Step 8: Commit & PR

# Create branch
git checkout -b auto/update-sdk-references

# Stage only the condensed files and updated SKILL.md files
git add plugin/skills/*/references/sdk/*.md
git add plugin/skills/*/SKILL.md

# Commit
git commit -m "chore: update condensed SDK references from microsoft/skills"

# Create PR to target repo
gh pr create \
  --title "Update condensed SDK references" \
  --body "Auto-generated from microsoft/skills plugin changes."

Incremental vs Full Regeneration

Mode When Scope
Incremental Source SKILL.md changed in PR Only regenerate changed source skills + their consumer copies
Full Scheduled (weekly) or manual trigger Regenerate all 84 files from scratch

Incremental requires reverse-mapping (source → consumers) to know which consumer directories need updates. Full regeneration is simpler and catches drift.

Pipeline Summary

microsoft/skills repo                    githubcopilotforAzure repo
─────────────────────                    ──────────────────────────
.github/plugins/                         plugin/skills/
  azure-sdk-python/skills/                 azure-ai/references/sdk/
    azure-storage-blob-py/SKILL.md  ──┐      azure-storage-blob-py.md  (copy)
  azure-sdk-typescript/skills/        ├──▶ azure-storage/references/sdk/
    azure-storage-blob-ts/SKILL.md  ──┘      azure-storage-blob-py.md
                                             azure-storage-blob-ts.md
                                           ...

Step 1: Detect changed SKILL.md → Step 2: Resolve plugin paths
Step 3: Parse & extract sections → Step 4: Apply template
Step 5: Write to consumer dirs  → Step 6: Update SKILL.md links
Step 7: Validate                → Step 8: Commit & PR
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment