Date: March 11, 2026 Context: Beyond diagnostics/troubleshooting, where else do azure-skills and Agent-Skills overlap? What content from Agent-Skills should azure-skills reference?
There are 6 major overlap areas between azure-skills (24 operational skills) and MicrosoftDocs/Agent-Skills (193 service documentation skills):
| Overlap Area | azure-skills Depth | Agent-Skills Depth | Priority | Effort |
|---|---|---|---|---|
| Diagnostics/Troubleshooting | 2 services deep | 180+ services | P0 | Medium |
| Security hardening | Scattered, thin | 40-56 entries per service | P1 | Low |
| Cost optimization | Actionable but narrow | 73 config + 52 decision entries | P1 | Low |
| Monitoring limits & config | None | 1,343 config + 63 limits entries | P2 | Low |
| Storage operations | SDK only | 68 config + 34 best practices | P2 | Medium |
| Compliance frameworks | AZQR only | 40+ framework mappings | P2 | Low |
| Messaging architecture | None | 9 architecture entries | P3 | Low |
| ARM deployment troubleshooting | AZD/Bicep errors | 94 troubleshooting entries | P3 | Low |
| Skill | Security Content | Gap |
|---|---|---|
azure-rbac |
Minimal — role selection, prerequisites for granting roles, CLI commands. SKILL.md only, no references/ directory. | No built-in role catalog, no ABAC conditions, no PIM guidance, no deny assignments |
entra-app-registration |
Good — OAuth flows (4 types), MSAL (5 languages), security best practices, troubleshooting | No microsoft-entra-id skill exists in Agent-Skills — azure-skills is the only source for identity platform guidance |
azure-compliance |
AZQR workflow, Key Vault expiration auditing, remediation patterns | No compliance framework mappings (CIS, NIST, PCI DSS, etc.) |
azure-storage |
Auth best practices (managed identity, DefaultAzureCredential) | No storage-specific security hardening (encryption, SAS, SFTP, firewall, anonymous access) |
azure-messaging |
RBAC roles (Data Owner/Sender/Receiver) | No network security (VNet, Private Link, TLS, firewalls) |
azure-aigateway |
Content safety, jailbreak detection, token limiting | No APIM-level security (certificates, OAuth validation, IP filtering) |
| Agent-Skills Skill | Security Entries | Key Topics |
|---|---|---|
azure-rbac |
40+ entries | Built-in roles by category (AI/ML, compute, containers, databases, DevOps, identity, networking, security, storage, web), ABAC conditions, deny assignments, PIM, policy-based governance |
azure-policy |
40+ entries | Compliance framework mappings: CIS 1.1-2.0, NIST SP 800-53 R4/R5, NIST 800-171, FedRAMP High/Moderate, ISO 27001, PCI DSS 3.2.1/4.0, HIPAA HITRUST, SOC 2, CMMC L3, plus regional standards |
azure-blob-storage |
56 entries | RBAC/ABAC, Entra ID auth, SAS tokens, SFTP access, ACLs, encryption (server/client, CMK, scopes), anonymous access prevention |
azure-event-hubs |
22 entries | Entra ID, SAS, managed identities, encryption, TLS, VNet, Private Link, NSP, firewalls, Azure Policy |
azure-service-bus |
19 entries | Entra ID, SAS, managed identities, encryption, TLS, VNet, Private Link, firewalls, compliance |
azure-key-vault |
25 entries | Auth (RBAC vs access policies), network/firewall/Private Link, BYOK/HSM keys, certificates, backup/restore, key attestation |
azure-monitor |
51 entries | Network isolation, TLS, Private Link, RBAC, Azure Policy, CMK, secure APIs |
azure-rbac is the highest-impact candidate. It currently has no references/ directory. Adding:
azure-rbac/
├── SKILL.md ← Existing (role selection, CLI commands)
├── references/ ← NEW
│ ├── built-in-roles.md ← NEW: role catalog by category + Learn URLs
│ ├── abac-conditions.md ← NEW: attribute-based access control patterns
│ ├── security-best-practices.md ← NEW: PIM, deny assignments, scope management
│ └── compliance-roles.md ← NEW: roles needed for compliance frameworks
Each file would combine a short actionable section (CLI examples) with curated Learn URLs from Agent-Skills' azure-rbac Security category.
azure-compliance could add:
azure-compliance/
├── references/
│ ├── ... (existing)
│ └── compliance-frameworks.md ← NEW: framework-to-policy mapping
│ sourced from Agent-Skills azure-policy
│ Security category (40+ entries)
azure-cost-optimization covers:
- Orphaned resource cleanup (via AZQR + ARG queries)
- Rightsizing recommendations
- Pricing API queries (
azure-retail-prices) - Free tier analysis
- Redis-specific cost optimization
| Category | Entries | Key Topics |
|---|---|---|
| Configuration | 73 entries | Billing accounts, credits, reservations, savings plans, budgets, cost alerts, tags, exports, invoices, payment methods |
| Decision Making | 52 entries | EA vs MCA account types, commitment discount tiers, hybrid benefit eligibility, reservation exchanges, savings plan scope selection |
| Troubleshooting | 22 entries | Unexpected charges, billing access issues, failed payments, cost anomalies |
| Security | 21 entries | Billing roles, admin elevation, tenant/subscription protection, fraud prevention, EA/MCA/reservation permissions |
| Best Practices | 10 entries | Cost optimization strategies, budget management, tag governance |
| Integrations | 17 entries | Cost Management APIs, Power BI, Logic Apps |
azure-skills has the actionable workflow (find waste → query pricing → rightsizing). Agent-Skills has the enterprise reference depth (billing config, reservations, EA decisions).
azure-cost-optimization/
├── references/
│ ├── ... (existing: azure-quick-review.md, azure-redis.md, etc.)
│ ├── enterprise-cost-management.md ← NEW: reservation/savings plan URLs,
│ │ EA vs MCA decision URLs,
│ │ billing configuration URLs
│ └── cost-troubleshooting.md ← NEW: unexpected charges,
│ billing access issues,
│ cost anomaly detection URLs
Three separate skills touch monitoring, each covering a narrow slice:
| Skill | Focus | What's missing |
|---|---|---|
azure-kusto |
KQL query patterns (basic retrieval, aggregation, time series, joins) | No alerting, no agent config, no limits awareness |
appinsights-instrumentation |
SDK setup for .NET, Node.js, Python; auto-instrumentation | No performance tuning, no cost control, no sampling config |
azure-diagnostics |
Generic diagnostic flow, ARG queries, 2 service guides | No monitoring configuration, no alert setup, no dashboard creation |
This is Agent-Skills' largest skill by volume:
| Category | Entries | Key Topics |
|---|---|---|
| Configuration | 1,343 entries | Agents (AMA, Log Analytics), data collection rules, pipelines, alerts, autoscale, workbooks, Private Link, log/metric schemas, Prometheus, Container Insights, Grafana |
| Troubleshooting | 65+ entries | Per-agent issues (AMA Linux/Windows, Log Analytics agent), per-feature issues (alerts, Prometheus, Container Insights, Profiler, Snapshot Debugger), ITSM Connector |
| Limits & Quotas | 63 entries | Ingestion caps, query timeouts, Prometheus scrape scale limits, workspace retention, alert rule limits, metric dimensions |
| Security | 51 entries | Network isolation, TLS, Private Link, RBAC, Azure Policy, CMK, secure API access |
| Best Practices | 40 entries | Cost control, alerting patterns, autoscale, Kubernetes monitoring, Prometheus |
| Deployment | 38 entries | ARM/Bicep/Terraform for monitoring resources |
The three azure-skills monitoring skills should each get a targeted reference file:
azure-kusto/
├── references/ ← NEW (currently no references/)
│ └── monitor-limits.md ← Query timeouts, ingestion caps,
│ workspace retention limits
appinsights-instrumentation/
├── references/
│ ├── ... (existing SDK guides)
│ └── monitor-best-practices.md ← Cost control, sampling config,
│ alerting patterns, autoscale
azure-diagnostics/
├── references/
│ ├── ... (existing)
│ └── monitor-troubleshooting.md ← Per-agent troubleshooting,
│ per-feature troubleshooting,
│ AMA issues, alert failures
Highest value: The Limits & Quotas content. Users hit ingestion caps, query timeouts, and alert rule limits regularly — and azure-skills has zero coverage of this. Adding 63 curated Learn URLs costs almost nothing in tokens but prevents common operational surprises.
azure-storage covers:
- SDK patterns across 4 languages (Blob, Queue, Files, Tables, Data Lake)
- Auth best practices (managed identity, DefaultAzureCredential)
- Access tier overview (Hot/Cool/Cold/Archive)
- Redundancy options (LRS/ZRS/GRS/GZRS)
- 13 SDK reference files
Missing: Troubleshooting, lifecycle management, immutability policies, performance tuning, security hardening beyond auth.
| Category | Entries | Key Topics |
|---|---|---|
| Security | 56 entries | RBAC/ABAC conditions, Entra ID auth, SAS token management, SFTP access controls, ACLs, server-side encryption (CMK, scopes), client-side encryption, anonymous access prevention |
| Configuration | 68 entries | Lifecycle policies, immutability (legal hold, time-based retention), soft delete (blob + container), NFS 3.0 protocol, SFTP, blob inventory, object replication, change feed |
| Best Practices | 34 entries | Performance tuning per SDK (.NET v12, Java, Python, JavaScript), cost optimization, reliability patterns, client configuration |
| Limits & Quotas | 20 entries | Account limits, container limits, throughput targets, scalability targets |
| Troubleshooting | 5 entries | Latency issues, availability issues, performance diagnostics |
azure-storage/
├── references/
│ ├── ... (existing 13 SDK refs + auth-best-practices.md)
│ ├── storage-security.md ← NEW: encryption, SAS management,
│ │ anonymous access, firewall rules
│ ├── storage-lifecycle.md ← NEW: lifecycle policies, immutability,
│ │ soft delete, replication
│ ├── storage-performance.md ← NEW: per-SDK tuning URLs,
│ │ throughput targets, scalability
│ └── storage-limits.md ← NEW: account limits, container limits,
│ throughput targets
azure-compliance covers:
- Azure Quick Review (AZQR) scan workflow
- Key Vault expiration auditing
- Orphaned resource detection
- Remediation patterns for AZQR findings
Missing: Compliance framework mappings, Azure Policy built-in initiatives, regulatory standard mappings.
| Category | Entries | Key Topics |
|---|---|---|
| Security | 40+ entries | Compliance framework mappings — this is the unique content: |
Framework mappings available in Agent-Skills:
- CIS Azure Foundations Benchmark 1.1, 1.3, 1.4, 2.0
- NIST SP 800-53 Rev. 4, Rev. 5
- NIST 800-171 Rev. 2
- FedRAMP High, FedRAMP Moderate
- ISO 27001:2013
- PCI DSS 3.2.1, PCI DSS 4.0
- HIPAA HITRUST 9.2
- SOC 2 Type 2
- CMMC Level 3
- Canada Federal PBMM
- Australia ISM PROTECTED
- New Zealand ISM Restricted
- UK OFFICIAL, NHS
- SWIFT CSP-CSCF v2022
- Plus Linux/Windows/Docker security baselines
azure-compliance/
├── references/
│ ├── ... (existing AZQR guides)
│ └── compliance-frameworks.md ← NEW: framework-to-policy-initiative
│ mapping table with Learn URLs
│ sourced from Agent-Skills azure-policy
This is a high-value, low-effort addition. A single reference file with a table mapping framework names to Azure Policy initiative URLs would make the compliance skill significantly more useful for regulated industries.
azure-messaging covers:
- SDK troubleshooting (4 languages × Event Hubs + Service Bus)
- Connectivity diagnostics (ports, WebSocket, firewall)
- Auth checklist and RBAC roles
Missing: Architecture patterns, geo-disaster recovery, federation, message ordering strategies, dead-letter queue management.
| Service | Architecture Entries | Key Topics |
|---|---|---|
azure-event-hubs |
4 entries | Availability zones, consistency guarantees, geo-DR, event replication |
azure-service-bus |
5 entries | Federation patterns, message replication, topic partitioning, NServiceBus integration |
azure-service-bus |
11 Best Practices | Message ordering, sessions, TTL, dead-lettering, performance tuning |
azure-messaging/
├── references/
│ ├── ... (existing SDK troubleshooting + auth guides)
│ ├── architecture-patterns.md ← NEW: geo-DR, federation, replication
│ │ URLs from Agent-Skills
│ └── messaging-best-practices.md ← NEW: ordering, sessions, dead-letter,
│ TTL, performance URLs
azure-deploy covers:
- AZD errors (
azd up,azd deploy) - Bicep template validation errors
- Terraform errors
- SWA deployment issues
- Post-deployment steps (EF migrations, SQL managed identity)
Missing: ARM-level deployment failures, resource provider registration, quota exceeded errors, dependency resolution failures.
| Category | Entries | Key Topics |
|---|---|---|
| Troubleshooting | 94 entries | ARM deployment errors, resource provider registration, quota issues, template validation, dependency failures, move resource errors, throttling, lock conflicts |
| Best Practices | 46 entries | Template design, modularization, testing, CI/CD patterns |
| Deployment | 57 entries | ARM/Bicep/Terraform deployment patterns, what-if, rollback |
azure-deploy/
├── references/
│ ├── ... (existing troubleshooting.md, recipe errors)
│ └── arm-troubleshooting.md ← NEW: ARM deployment error URLs,
│ provider registration,
│ quota exceeded, throttling
Every overlap area follows the same reference file pattern:
┌──────────────────────────────────────────────────────────┐
│ azure-skills reference file │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ TOP: Actionable content (azure-skills strength) │ │
│ │ • CLI commands with placeholders │ │
│ │ • KQL query templates │ │
│ │ • Step-by-step workflows │ │
│ │ • MCP tool invocations │ │
│ │ • Decision tables (when to use what) │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ BOTTOM: Learn references (Agent-Skills strength) │ │
│ │ <!-- Sourced from MicrosoftDocs/Agent-Skills --> │ │
│ │ • Troubleshooting URLs │ │
│ │ • Security hardening URLs │ │
│ │ • Limits & quotas URLs │ │
│ │ • Best practices URLs │ │
│ │ • Configuration deep-dive URLs │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ Token cost: 150-600 tokens per file │
│ Loaded: JIT only when service/topic is mentioned │
└──────────────────────────────────────────────────────────┘
| Concern | Answer |
|---|---|
| Token budget | References load JIT — only relevant file loads. 20+ new files cost 0 tokens until activated. |
| Freshness | Learn URLs are stable. Agent-Skills' weekly crawl validates them. A sync script can detect new entries. |
| Actionability | azure-skills' CLI/KQL/MCP content stays at the top. Agent-Skills URLs supplement, not replace. |
| Maintenance | Agent-Skills content is auto-generated. azure-skills only maintains the actionable top section. |
| Single skill routing | No new skills needed. Existing skills get richer references. |
| Deliverable | Skill | Effort |
|---|---|---|
references/built-in-roles.md |
azure-rbac | 3 hours |
references/abac-conditions.md |
azure-rbac | 2 hours |
references/security-best-practices.md |
azure-rbac | 2 hours |
references/compliance-frameworks.md |
azure-compliance | 3 hours |
references/enterprise-cost-management.md |
azure-cost-optimization | 3 hours |
references/cost-troubleshooting.md |
azure-cost-optimization | 2 hours |
references/storage-security.md |
azure-storage | 3 hours |
| Version bumps + test updates | All affected skills | 2 hours |
| Deliverable | Skill | Effort |
|---|---|---|
references/monitor-limits.md |
azure-kusto | 2 hours |
references/monitor-best-practices.md |
appinsights-instrumentation | 3 hours |
references/monitor-troubleshooting.md |
azure-diagnostics | 3 hours |
references/storage-lifecycle.md |
azure-storage | 2 hours |
references/storage-performance.md |
azure-storage | 2 hours |
references/storage-limits.md |
azure-storage | 2 hours |
| Service-specific diagnostics references (from prior gist) | azure-diagnostics | 4 hours |
| Deliverable | Skill | Effort |
|---|---|---|
references/architecture-patterns.md |
azure-messaging | 3 hours |
references/messaging-best-practices.md |
azure-messaging | 3 hours |
references/arm-troubleshooting.md |
azure-deploy | 3 hours |
| Version bumps + test updates | All affected skills | 3 hours |
Build a sync script that:
- Reads Agent-Skills SKILL.md files for target services
- Extracts URLs by category (Troubleshooting, Security, Best Practices, Limits & Quotas)
- Compares against existing azure-skills reference files
- Flags new entries that should be added
- Validates existing URLs still resolve (404 check)
- Generates thin reference files for uncovered services (Template B from diagnostics gist)
MicrosoftDocs/Agent-Skills azure-skills
┌─────────────────────────────┐ ┌──────────────────────────────┐
│ skills/ │ │ plugin/skills/ │
│ azure-rbac/SKILL.md │ sync │ azure-rbac/ │
│ Security: 40+ entries │──script──────▶│ references/ │
│ azure-policy/SKILL.md │ │ built-in-roles.md │
│ Security: 40+ entries │ │ (CLI + Learn URLs) │
│ azure-blob-storage/SKILL.md│ │ azure-storage/ │
│ Security: 56 entries │ │ references/ │
│ Config: 68 entries │ │ storage-security.md │
│ azure-monitor/SKILL.md │ │ (CLI + Learn URLs) │
│ Config: 1343 entries │ │ azure-diagnostics/ │
│ Limits: 63 entries │ │ references/ │
│ ... │ │ monitor-limits.md │
└─────────────────────────────┘ └──────────────────────────────┘
(auto-updated weekly) (actionable + sourced URLs)
| azure-skills Skill | Service-Specific Reference Files | Agent-Skills Categories Covered |
|---|---|---|
| azure-rbac | 0 | 0 of 7 |
| azure-compliance | 5 (AZQR-focused) | 0 of 7 |
| azure-cost-optimization | 4 (cleanup-focused) | 0 of 7 |
| azure-storage | 14 (SDK-focused) | 0 of 7 |
| azure-kusto | 0 | 0 of 7 |
| appinsights-instrumentation | 6 (SDK-focused) | 0 of 7 |
| azure-diagnostics | 4 (2 services) | 0 of 7 |
| azure-messaging | 10 (SDK troubleshooting) | 0 of 7 |
| azure-deploy | 12 (recipe errors) | 0 of 7 |
| azure-skills Skill | New Reference Files | Agent-Skills Categories Now Covered |
|---|---|---|
| azure-rbac | +3 | Security, Best Practices, Limits |
| azure-compliance | +1 | Security (compliance frameworks) |
| azure-cost-optimization | +2 | Configuration, Troubleshooting, Decision Making |
| azure-storage | +4 | Security, Configuration, Best Practices, Limits |
| azure-kusto | +1 | Limits & Quotas |
| appinsights-instrumentation | +1 | Best Practices |
| azure-diagnostics | +10-15 (service guides) | Troubleshooting (per service) |
| azure-messaging | +2 | Architecture, Best Practices |
| azure-deploy | +1 | Troubleshooting (ARM-level) |
Total: ~25-30 new reference files across 9 skills, each 150-600 tokens, loaded JIT only.
Not all Agent-Skills content belongs in azure-skills. Skip:
| Category | Why skip |
|---|---|
| Configuration (1,343 entries for Monitor alone) | Too granular — these are "how to set up feature X" docs, not operational guidance. Link only the most operationally relevant ones. |
| Integrations & Coding Patterns | This is microsoft/skills territory (SDK coding patterns), not azure-skills (operational workflows). |
| Deployment (for most services) | azure-skills already has deep deployment coverage via azure-prepare/deploy/validate. Only add ARM-level troubleshooting. |
| Decision Making (most services) | Useful for cost optimization, but for most services these are architecture decisions that belong at planning time (azure-prepare), not operations time. |
Include from Agent-Skills: Troubleshooting, Security, Limits & Quotas, and operationally-relevant Best Practices. Exclude from Agent-Skills: Configuration (too granular), Integrations (SDK territory), Deployment (already covered), Architecture (planning territory).