Skip to content

Instantly share code, notes, and snippets.

@kvenkatrajan

kvenkatrajan/agent-skills-progressive-disclosure.md

Last active March 12, 2026 15:45
Show Gist options

  • Select an option

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

Select an option

Learn more about clone URLs
Save kvenkatrajan/003e33cd6181cfd9b72c7482270e9078 to your computer and use it in GitHub Desktop.
Download ZIP
Progressive Disclosure for MicrosoftDocs/Agent-Skills via azure-skills — single azure-docs skill design with 3-tier loading
Raw
agent-skills-progressive-disclosure.md

Progressive Disclosure for MicrosoftDocs/Agent-Skills via azure-skills — single azure-docs skill design with 3-tier loading

Progressive Disclosure for MicrosoftDocs/Agent-Skills

Date: March 12, 2026 Problem: Agent-Skills has 193 service skills, each 100-850 lines. Loading them all is impossible. Loading even one full skill (e.g., Azure Functions at 366 lines / ~135 links) wastes tokens when the user only needs one category. Solution: Restructure Agent-Skills into a three-tier progressive disclosure model with a single router SKILL.md, per-service reference files, and on-demand Microsoft Learn fetching.

1. The Problem: Agent-Skills Are Flat, Not Progressive

Today, each Agent-Skills SKILL.md is a single monolithic file with this structure:

azure-functions/SKILL.md (366 lines)
├── YAML frontmatter (name, description, compatibility)
├── Usage instructions (how to read, freshness check, fetch tools)
├── Category Index table (9 rows with line ranges)
├── Troubleshooting (27 links)
├── Best Practices (26 links)
├── Decision Making (25 links)
├── Architecture & Design Patterns (9 links)
├── Limits & Quotas (12 links)
├── Security (17 links)
├── Configuration (45 links)
├── Integrations & Coding Patterns (117 links)
└── Deployment (47 links)

Problems with the current model:

  1. An agent must load the entire SKILL.md even if the user only needs "troubleshoot my Functions timer trigger"
  2. 193 skills × ~200 lines average = ~38,600 lines of content that cannot be surfaced progressively
  3. No routing layer — the agent must already know which skill to load
  4. Each skill is self-contained with no cross-skill navigation or shared catalog

2. Proposed Solution: Three-Tier Progressive Disclosure

Restructure the Agent-Skills repo into three tiers that load incrementally.

Three Tiers

┌─────────────────────────────────────────────────────────────────────┐
│  TIER 1: Service Catalog (single SKILL.md — always loaded)         │
│  ─ 193 services as a routing table                                 │
│  ─ Maps prompt keywords → service name → category index            │
│  ─ ~800 tokens                                                     │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ user prompt matches a service
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  TIER 2: Category Index (loaded per service, from references/)     │
│  ─ One reference file per service (e.g., references/functions.md)  │
│  ─ Contains the category index table + topic tables                │
│  ─ Agent reads only the relevant category section via line ranges  │
│  ─ ~50-200 tokens per category                                     │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ user needs specific doc content
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  TIER 3: Documentation Fetch (on demand, JIT)                      │
│  ─ Agent fetches the specific Microsoft Learn URL from the table   │
│  ─ Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage    │
│  ─ Only the exact page the user needs                              │
│  ─ ~500-2000 tokens per fetch                                      │
└─────────────────────────────────────────────────────────────────────┘

3. Skill Design

3.1 SKILL.md (Tier 1 — The Router)

A single SKILL.md at the root of the Agent-Skills repo (or a dedicated azure-docs/SKILL.md skill) acts as the entry point for all 193 services.

---
name: azure-docs
description: "Look up Azure service documentation, troubleshooting guides, best practices, architecture patterns, limits, security guidance, and deployment references for any of 193 Azure services. Use when asking about any Azure service, looking up error codes, checking service limits, or finding official Microsoft Learn guidance. WHEN: 'how do I configure', 'troubleshoot', 'best practices for', 'limits of', 'what is the quota for', 'how to deploy', 'error code AZFD', 'documentation for', 'learn about Azure', 'what Azure service should I use for'."
license: MIT
compatibility: Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata:
  author: Microsoft
  version: "1.0.0"
  source: "MicrosoftDocs/Agent-Skills"
  generated_at: "2026-03-04"
  generator: "docs2skills/1.0.0"
---

# Azure Documentation Reference

> Look up official Microsoft Learn documentation for any of 193 Azure services.
> This skill provides **progressive access** — it does NOT load all content upfront.

## Rules

1. **Match first** — Use the Service Catalog below to find the service
2. **Load reference** — Load only the matched service's reference file
3. **Read by category** — Use the category index to read only the relevant section
4. **Fetch on demand** — Use `mcp_microsoftdocs:microsoft_docs_fetch` or `fetch_webpage` to retrieve specific docs
5. **Freshness** — If reference `generated_at` is >3 months old, suggest pulling latest from MicrosoftDocs/Agent-Skills

## Workflow

| Step | Action | What Loads |
|------|--------|------------|
| 1 | Match user prompt to service | Nothing new — use catalog below |
| 2 | Load service reference | `references/<service>.md` (~100-400 lines) |
| 3 | Read relevant category only | Category section via line ranges (~10-30 lines) |
| 4 | Fetch specific doc if needed | Microsoft Learn URL from table (~500-2000 tokens) |

## Service Catalog

> **193 services across 19 categories.** Use this table to route to the correct reference file.

### Compute (11 services)
| Service | Reference | Keywords |
|---------|-----------|----------|
| App Service | [references/app-service.md](references/app-service.md) | web app, app service, webapp |
| Azure Functions | [references/functions.md](references/functions.md) | function app, serverless, timer trigger, HTTP trigger |
| Virtual Machines | [references/virtual-machines.md](references/virtual-machines.md) | VM, virtual machine, VMSS |
| Virtual Machine Scale Sets | [references/virtual-machine-scale-sets.md](references/virtual-machine-scale-sets.md) | scale set, VMSS |
| Batch | [references/batch.md](references/batch.md) | batch processing, HPC |
| Cloud Services | [references/cloud-services.md](references/cloud-services.md) | cloud service, PaaS classic |
| Azure Spring Apps | [references/spring-apps.md](references/spring-apps.md) | spring boot, spring cloud |
| Azure CycleCloud | [references/cyclecloud.md](references/cyclecloud.md) | HPC cluster |
| Azure VMware Solution | [references/vmware-solution.md](references/vmware-solution.md) | VMware, vSphere |
| SAP on Azure | [references/sap.md](references/sap.md) | SAP, HANA |
| Azure Modeling and Simulation | [references/modeling-simulation.md](references/modeling-simulation.md) | simulation |

### Containers (5 services)
| Service | Reference | Keywords |
|---------|-----------|----------|
| Azure Kubernetes Service | [references/kubernetes-service.md](references/kubernetes-service.md) | AKS, Kubernetes, k8s |
| Container Apps | [references/container-apps.md](references/container-apps.md) | container app, serverless container |
| Container Instances | [references/container-instances.md](references/container-instances.md) | ACI, container instance |
| Container Registry | [references/container-registry.md](references/container-registry.md) | ACR, container registry |
| Red Hat OpenShift | [references/openshift.md](references/openshift.md) | OpenShift, ARO |

### Databases (9 services)
| Service | Reference | Keywords |
|---------|-----------|----------|
| Cosmos DB | [references/cosmos-db.md](references/cosmos-db.md) | cosmos, document DB, NoSQL |
| SQL Database | [references/sql-database.md](references/sql-database.md) | SQL, Azure SQL |
| PostgreSQL | [references/postgresql.md](references/postgresql.md) | postgres, PostgreSQL |
| MySQL | [references/mysql.md](references/mysql.md) | MySQL |
| SQL Managed Instance | [references/sql-managed-instance.md](references/sql-managed-instance.md) | managed instance, SQL MI |
| Cache for Redis | [references/redis-cache.md](references/redis-cache.md) | Redis, cache |
| Managed Instance for Apache Cassandra | [references/cassandra.md](references/cassandra.md) | Cassandra |
| SQL Server on VMs | [references/sql-server-vms.md](references/sql-server-vms.md) | SQL Server VM |
| Database Migration Service | [references/database-migration.md](references/database-migration.md) | DMS, database migration |

### Networking (25 services)
| Service | Reference | Keywords |
|---------|-----------|----------|
| Virtual Network | [references/virtual-network.md](references/virtual-network.md) | VNet, virtual network, subnet |
| Load Balancer | [references/load-balancer.md](references/load-balancer.md) | load balancer, LB |
| Application Gateway | [references/application-gateway.md](references/application-gateway.md) | app gateway, WAF |
| VPN Gateway | [references/vpn-gateway.md](references/vpn-gateway.md) | VPN, site-to-site |
| Azure DNS | [references/dns.md](references/dns.md) | DNS, domain |
| ExpressRoute | [references/expressroute.md](references/expressroute.md) | ExpressRoute, private peering |
| Front Door | [references/front-door.md](references/front-door.md) | front door, CDN, global LB |
| Traffic Manager | [references/traffic-manager.md](references/traffic-manager.md) | traffic manager, DNS routing |
| Private Link | [references/private-link.md](references/private-link.md) | private endpoint, private link |
| Azure Firewall | [references/firewall.md](references/firewall.md) | firewall, network security |
| Azure Bastion | [references/bastion.md](references/bastion.md) | bastion, jump box |
| Network Watcher | [references/network-watcher.md](references/network-watcher.md) | network watcher, packet capture |
| NAT Gateway | [references/nat-gateway.md](references/nat-gateway.md) | NAT, outbound |
| DDoS Protection | [references/ddos-protection.md](references/ddos-protection.md) | DDoS |
| Web Application Firewall | [references/waf.md](references/waf.md) | WAF |
| ... | ... | _(10 more networking services)_ |

### AI + Machine Learning (20 services)
| Service | Reference | Keywords |
|---------|-----------|----------|
| Azure OpenAI Service | [references/openai.md](references/openai.md) | OpenAI, GPT, LLM |
| Azure AI Services | [references/ai-services.md](references/ai-services.md) | cognitive services, AI |
| Azure Machine Learning | [references/machine-learning.md](references/machine-learning.md) | ML, machine learning, AzureML |
| Azure AI Search | [references/ai-search.md](references/ai-search.md) | cognitive search, AI search |
| Azure AI Foundry | [references/ai-foundry.md](references/ai-foundry.md) | AI studio, foundry |
| ... | ... | _(15 more AI/ML services)_ |

### Storage (11 services)
| Service | Reference | Keywords |
|---------|-----------|----------|
| Blob Storage | [references/blob-storage.md](references/blob-storage.md) | blob, object storage |
| Files | [references/files.md](references/files.md) | file share, SMB, NFS |
| Queue Storage | [references/queue-storage.md](references/queue-storage.md) | queue, storage queue |
| Table Storage | [references/table-storage.md](references/table-storage.md) | table storage |
| Disk Storage | [references/disk-storage.md](references/disk-storage.md) | managed disk |
| Data Lake Storage | [references/data-lake.md](references/data-lake.md) | ADLS, data lake |
| ... | ... | _(5 more storage services)_ |

### Security (15 services)
| Service | Reference | Keywords |
|---------|-----------|----------|
| Key Vault | [references/key-vault.md](references/key-vault.md) | key vault, secrets, certificates |
| Microsoft Defender for Cloud | [references/defender.md](references/defender.md) | defender, security center |
| Microsoft Sentinel | [references/sentinel.md](references/sentinel.md) | sentinel, SIEM |
| ... | ... | _(12 more security services)_ |

### Integration (13 services)
| Service | Reference | Keywords |
|---------|-----------|----------|
| API Management | [references/api-management.md](references/api-management.md) | APIM, API gateway |
| Service Bus | [references/service-bus.md](references/service-bus.md) | service bus, queue, topic |
| Event Grid | [references/event-grid.md](references/event-grid.md) | event grid, pub/sub |
| Logic Apps | [references/logic-apps.md](references/logic-apps.md) | logic app, workflow |
| Event Hubs | [references/event-hubs.md](references/event-hubs.md) | event hub, streaming |
| ... | ... | _(8 more integration services)_ |

### Management and Governance (26 services)
| Service | Reference | Keywords |
|---------|-----------|----------|
| Azure Monitor | [references/monitor.md](references/monitor.md) | monitor, metrics, alerts |
| Azure Policy | [references/policy.md](references/policy.md) | policy, compliance |
| Azure Resource Manager | [references/resource-manager.md](references/resource-manager.md) | ARM, resource manager |
| Cost Management | [references/cost-management.md](references/cost-management.md) | cost, billing |
| Azure Advisor | [references/advisor.md](references/advisor.md) | advisor, recommendations |
| ... | ... | _(21 more management services)_ |

### _(+ 10 more categories: Analytics, Web, Developer Tools, DevOps, IoT, Hybrid, Migration, Identity, Mobile, VDI)_

> **Full catalog:** 193 services. See [references/catalog.md](references/catalog.md) for the complete listing.

3.2 Reference Files (Tier 2 — Per-Service Content)

Each existing Agent-Skills SKILL.md becomes a reference file. The body content (category index + topic tables) moves to references/<service>.md, while the YAML frontmatter stays in the router SKILL.md's catalog.

Current structure (flat):

skills/
├── azure-functions/SKILL.md         (366 lines, self-contained)
├── azure-key-vault/SKILL.md         (172 lines, self-contained)
├── azure-cosmos-db/SKILL.md         (847 lines, self-contained)
└── ... (193 total, each loaded independently)

Proposed structure (progressive):

azure-docs/
├── SKILL.md                          (router — service catalog, ~800 tokens)
└── references/
    ├── functions.md                  (body from azure-functions/SKILL.md)
    ├── key-vault.md                  (body from azure-key-vault/SKILL.md)
    ├── cosmos-db.md                  (body from azure-cosmos-db/SKILL.md)
    ├── ... (193 reference files)
    └── catalog.md                    (full 193-service listing)

Example: references/functions.md

# Azure Functions

> Generated: 2026-03-04 | Source: MicrosoftDocs/Agent-Skills

## Category Index

| Category | Lines | Description |
|----------|-------|-------------|
| Troubleshooting | L12-L38 | AZFD/AZFW error codes, runtime issues, storage/config problems |
| Best Practices | L39-L68 | Design, coding, testing, error handling, performance, scaling |
| Decision Making | L69-L94 | Hosting plans, networking, migration/upgrade paths |
| Architecture | L95-L103 | Durable patterns, container hosting, execution model |
| Limits & Quotas | L104-L115 | Scaling, billing, concurrency, language versions |
| Security | L116-L132 | Encryption, private endpoints, managed identity, keys |
| Configuration | L133-L177 | Settings, bindings, triggers, storage, monitoring |
| Integrations | L178-L294 | HTTP, queues, databases, messaging, AI, Dapr, MCP |
| Deployment | L295-L341 | Provisioning, CI/CD, containers, zero-downtime |

## Troubleshooting

| Topic | URL |
|-------|-----|
| Diagnose Durable Functions issues | https://learn.microsoft.com/...durable-functions-diagnostics |
| Troubleshoot common Durable Functions errors | https://learn.microsoft.com/...durable-functions-troubleshooting-guide |
| Resolve AZFD0001 missing AzureWebJobsStorage | https://learn.microsoft.com/...azfd0001 |
| Fix AZFD0002 invalid AzureWebJobsStorage value | https://learn.microsoft.com/...azfd0002 |
| ... (23 more troubleshooting links) |

## Best Practices

| Topic | URL |
|-------|-----|
| Apply Durable Functions best practices | https://learn.microsoft.com/...durable-functions-best-practice-reference |
| Apply code constraints for orchestrators | https://learn.microsoft.com/...durable-functions-code-constraints |
| ... (24 more best practice links) |

... (7 more categories)

Example: references/key-vault.md — same structure, 172 lines, 8 categories.

3.3 Token Budget at Each Tier

Tier What Loads Tokens When
Tier 1 SKILL.md (catalog + routing rules) ~800 Always (skill triggers)
Tier 2 One service reference file ~200-1500 After service matched
Tier 2a One category section (via line range) ~50-200 After category identified
Tier 3 One Microsoft Learn page ~500-2000 Only if user needs deep content
Total per query ~1500-4500 vs. loading full SKILL.md: 3000-12000

4. Example Walkthrough

Prompt

"My Azure Functions timer trigger isn't firing. I'm getting error AZFD0015. What's wrong?"

Step-by-Step Progressive Disclosure

Step 1: SKILL.md Triggers (Tier 1 — ~800 tokens loaded)

The skill activates on "troubleshoot" + "error code AZFD".

Service catalog scan:

Service Catalog → Compute → Azure Functions
  Keywords match: "Functions", "timer trigger"
  Reference: references/functions.md

Step 2: Load Service Reference (Tier 2 — ~100 tokens for index only)

Agent loads references/functions.md and reads the Category Index first:

Category Index:
  Troubleshooting | L12-L38 | AZFD/AZFW error codes, runtime issues
  ─────────────────────────────────────────────────
  ✓ MATCH: "error AZFD0015" → Troubleshooting category

Agent reads only lines L12-L38 (~27 rows, ~200 tokens):

Troubleshooting section:
  ...
  | Resolve AZFD0015 non-CRON timer trigger schedule | https://learn.microsoft.com/.../azfd0015 |
  ...
  ✓ EXACT MATCH: AZFD0015

Step 3: Fetch Documentation (Tier 3 — ~1000 tokens)

Agent fetches the specific URL:

mcp_microsoftdocs:microsoft_docs_fetch(
  "https://learn.microsoft.com/en-us/azure/azure-functions/errors-diagnostics/diagnostic-events/azfd0015?from=learn-agent-skill"
)

Returns the specific AZFD0015 diagnostic page explaining that the timer trigger schedule value is not a valid CRON expression.

Token Budget Summary

Step 1: SKILL.md (catalog)              ~800 tokens
Step 2: Category index (10 lines)       ~100 tokens
Step 2a: Troubleshooting table (27 rows) ~200 tokens
Step 3: AZFD0015 doc page               ~1000 tokens
──────────────────────────────────────────────────
Total:                                   ~2100 tokens

vs. loading full azure-functions SKILL.md:  ~5000 tokens
vs. loading all 193 skills:                 impossible

5. How the Reference Files Are Generated

Transformation from Current Structure

The docs2skills pipeline already generates 193 individual SKILL.md files. The change is a post-processing step that splits each into catalog metadata + reference body.

docs2skills pipeline (existing)
         │
         ▼
skills/azure-functions/SKILL.md  ──┐
skills/azure-key-vault/SKILL.md  ──┤
skills/azure-cosmos-db/SKILL.md  ──┤
skills/... (193 total)           ──┤
                                   │
              ┌────────────────────┘
              ▼
     ┌────────────────────┐
     │  split script      │
     │  (post-processing) │
     │                    │
     │  For each SKILL.md:│
     │  1. Extract name,  │     azure-docs/
     │     description,   │     ├── SKILL.md (catalog with all 193 entries)
     │     keywords from  │     └── references/
     │     frontmatter    │         ├── functions.md (body only)
     │  2. Add row to     │         ├── key-vault.md (body only)
     │     catalog table  │         ├── cosmos-db.md (body only)
     │  3. Strip YAML,    │         └── ... (193 files)
     │     write body to  │
     │     references/    │
     └────────────────────┘

Split Script (Conceptual)

#!/bin/bash
# split-to-progressive.sh — post-processing step after docs2skills generates skills

SOURCE_DIR="skills"
TARGET_DIR="azure-docs/references"
CATALOG_ENTRIES=""

mkdir -p "$TARGET_DIR"

for skill_dir in "$SOURCE_DIR"/*/; do
  service_name=$(basename "$skill_dir")
  skill_file="$skill_dir/SKILL.md"

  if [ -f "$skill_file" ]; then
    # Extract metadata from frontmatter
    name=$(grep '^name:' "$skill_file" | sed 's/name: //')
    description=$(grep '^description:' "$skill_file" | head -1)
    generated_at=$(grep 'generated_at' "$skill_file" | sed 's/.*"\(.*\)"/\1/')

    # Extract keywords from description (first sentence before "Use when")
    keywords=$(echo "$description" | sed 's/.*including //;s/\. Use when.*//' | tr ',' '\n' | head -3)

    # Strip YAML frontmatter, write body to references/
    sed '1,/^---$/d; 1,/^---$/d' "$skill_file" > "$TARGET_DIR/$service_name.md"

    # Prepend source header
    sed -i "1i\\# ${service_name}\n\n> Generated: ${generated_at} | Source: MicrosoftDocs/Agent-Skills\n" \
      "$TARGET_DIR/$service_name.md"

    # Accumulate catalog entry
    CATALOG_ENTRIES+="| ${name} | [references/${service_name}.md](references/${service_name}.md) | ${keywords} |\n"
  fi
done

# Generate catalog table into SKILL.md template
echo -e "$CATALOG_ENTRIES" >> "$TARGET_DIR/../SKILL.md"

6. Bundles as Pre-Built Reference Sets

The existing Agent-Skills bundles (Quick Start, Popular, AI/ML Developer, etc.) map naturally to pre-selected reference subsets that agents can load based on user role or project type.

Bundle-to-Reference Mapping

Bundle Services Use Case
Quick Start 7 refs: app-service, blob-storage, functions, sql-database, key-vault, app-configuration, foundry New Azure developers, getting started
Popular 22 refs: above + cosmos-db, container-registry, virtual-machines, kubernetes-service, ... Most common workloads
AI/ML Developer 24 refs: machine-learning, openai, ai-search, ai-foundry, cognitive-services, ... AI application development
Data Engineer 26 refs: synapse, data-factory, event-hubs, databricks, data-lake, ... Data pipeline development
Infrastructure Pro 90+ refs: virtual-network, load-balancer, firewall, bastion, ... Infrastructure management
Security & Compliance 33 refs: defender, sentinel, key-vault, active-directory, ... Security-focused work
DevOps & Automation 40+ refs: devops, container-apps, deployment-environments, monitor, ... CI/CD and automation
Integration 26 refs: event-grid, service-bus, logic-apps, api-management, ... System integration

How an Agent Uses Bundles

Agent detects project context:
  - package.json with @azure/openai → AI/ML Developer bundle
  - Terraform files with azurerm_kubernetes → Infrastructure Pro bundle
  - .github/workflows with azure/login → DevOps & Automation bundle

Bundle loading:
  1. Load SKILL.md (Tier 1) — always, ~800 tokens
  2. Pre-load category indexes for bundle services only
     Quick Start: 7 × ~100 tokens = ~700 tokens
     vs. all 193: ~19,300 tokens
  3. Fetch specific docs on demand (Tier 3) — unchanged

7. Proposed SKILL.md Description (for Metadata Layer)

This is the description that would appear in the skill metadata, used by all agents for skill matching:

Expert Azure documentation reference covering 193 Azure services across
compute, containers, databases, networking, AI/ML, storage, security,
integration, analytics, and management. Provides troubleshooting guides,
best practices, architecture patterns, limits and quotas, security
guidance, configuration reference, coding patterns, and deployment
instructions sourced from Microsoft Learn. Use when asking about any Azure
service, looking up error codes, checking service limits, or finding
official documentation.

8. Implementation Checklist

# Task Effort
1 Create azure-docs/SKILL.md with 193-service catalog and keyword routing 2 hr
2 Write split script to extract SKILL.md bodies → references/ 2 hr
3 Integrate split script into docs2skills pipeline as post-processing step 2 hr
4 Generate initial 193 reference files from existing skills Automated
5 Map existing bundles (BUNDLES.md) to reference subsets 1 hr
6 Test progressive disclosure with 5 sample prompts across categories 2 hr
7 Add CI validation: every catalog entry has a corresponding reference file 1 hr
Total ~10 hr
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment