feat: (azure-cost) add storage optimization guide and fix token limit (#2554)

* feat(azure-cost): add storage optimization guide and fix token limit

- Add services/storage/azure-storage.md with optimization rules, lifecycle
  policy templates, Resource Graph queries, and pricing reference
- Add references/tools-and-best-practices.md (extracted from SKILL.md)
- Slim SKILL.md from ~2100 to ~490 tokens (fixes #2157)
- Add Step 1.7 Storage routing in optimization workflow
- Add 4 vally eval stimuli (3 routing + 1 response quality)

Closes #2524 (partial: storage service guide)

* fix: revert lockfile changes that desync npm ci

* fix: tighten routing triggers to avoid azure-storage skill overlap

Address Copilot review feedback:
- Replace 'storage tiering' with 'reduce storage costs' in description
- Tighten workflow triggers to storage-cost-specific terms (LRS/GRS, savings)
- Clarify orphaned disks rule is compute-adjacent (billed as storage)
- Add explicit cost/savings language to eval prompts for stable routing

* fix: add required --resource-group params to CLI examples

* fix: address third Copilot review round

- Clarify Reader role is scoped (not global) in Quick Reference
- Add --resource-group to inline verification command
- Add explicit routing note for storage-only vs general optimization

Author: jongio

evals/azure-cost/eval.yaml

@@ -310,6 +310,67 @@ stimuli:
         config:
           pattern: "(?i)fatal error|unhandled exception|stack trace"
 
+  # ═══════════════════════════════════════════
+  # Storage Cost Optimization routing prompts
+  # ═══════════════════════════════════════════
+
+  # ── storage-lifecycle-policy-prompt ──
+  # Assertions: softCheckSkill + isSkillInvoked (invocation rate ≥ 80%)
+  - name: "Storage lifecycle policy optimization"
+    prompt: "Help me reduce storage costs by setting up lifecycle policies to move old data to cheaper tiers"
+    tags:
+      type: integration
+      tier: full
+      cost: llm
+      area: routing
+      earlyTerminate: '[{"type":"skill-call","skill":"azure-cost"},{"type":"tool-call-count","count":3}]'
+    graders:
+      - type: skill-invocation
+        config:
+          required:
+            - azure-cost
+      - type: output-not-matches
+        config:
+          pattern: "(?i)fatal error|unhandled exception|stack trace"
+
+  # ── storage-redundancy-downgrade-prompt ──
+  # Assertions: softCheckSkill + isSkillInvoked (invocation rate ≥ 80%)
+  - name: "Storage redundancy downgrade for dev"
+    prompt: "I have GRS storage accounts in my dev environment, can I save money by downgrading to LRS?"
+    tags:
+      type: integration
+      tier: full
+      cost: llm
+      area: routing
+      earlyTerminate: '[{"type":"skill-call","skill":"azure-cost"},{"type":"tool-call-count","count":3}]'
+    graders:
+      - type: skill-invocation
+        config:
+          required:
+            - azure-cost
+      - type: output-not-matches
+        config:
+          pattern: "(?i)fatal error|unhandled exception|stack trace"
+
+  # ── storage-blob-tiering-prompt ──
+  # Assertions: softCheckSkill + isSkillInvoked (invocation rate ≥ 80%)
+  - name: "Blob access tier optimization"
+    prompt: "Analyze my blob storage costs and recommend which containers should move to cheaper tiers to save money"
+    tags:
+      type: integration
+      tier: full
+      cost: llm
+      area: routing
+      earlyTerminate: '[{"type":"skill-call","skill":"azure-cost"},{"type":"tool-call-count","count":3}]'
+    graders:
+      - type: skill-invocation
+        config:
+          required:
+            - azure-cost
+      - type: output-not-matches
+        config:
+          pattern: "(?i)fatal error|unhandled exception|stack trace"
+
   # ═══════════════════════════════════════════
   # Response quality tests
   # ═══════════════════════════════════════════
@@ -376,3 +437,23 @@ stimuli:
       - type: output-not-matches
         config:
           pattern: "(?i)fatal error|unhandled exception|stack trace"
+
+  # ── storage-lifecycle-policy-quality ──
+  # Assertions: assistant output mentions lifecycle policy concepts
+  - name: "Storage optimization mentions lifecycle policies and tiers"
+    prompt: "How can I optimize costs on my Azure storage accounts that have data sitting in hot tier for months?"
+    config:
+      runs: 1
+    tags:
+      type: integration
+      tier: full
+      cost: llm
+      area: response-quality
+    graders:
+      - type: output-matches
+        config:
+          pattern: "(?i)lifecycle|cool|archive|tiering|access tier"
+      - type: completed
+      - type: output-not-matches
+        config:
+          pattern: "(?i)fatal error|unhandled exception|stack trace"

plugin/skills/azure-cost/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: azure-cost
-description: "Unified Azure cost management: query historical costs, forecast future spending, and optimize to reduce waste. WHEN: \"Azure costs\", \"Azure spending\", \"Azure bill\", \"cost breakdown\", \"cost by service\", \"cost by resource\", \"how much am I spending\", \"show my bill\", \"monthly cost summary\", \"cost trends\", \"top cost drivers\", \"actual cost\", \"amortized cost\", \"forecast spending\", \"projected costs\", \"estimate bill\", \"future costs\", \"budget forecast\", \"end of month costs\", \"how much will I spend\", \"optimize costs\", \"reduce spending\", \"find cost savings\", \"orphaned resources\", \"rightsize VMs\", \"cost analysis\", \"reduce waste\", \"unused resources\", \"optimize Redis costs\", \"cost by tag\", \"cost by resource group\", \"AKS cost analysis add-on\", \"namespace cost\", \"cost spike\", \"anomaly\", \"budget alert\", \"AKS cost visibility\". DO NOT USE FOR: deploying resources, provisioning infrastructure, diagnostics, security audits, or estimating costs for new resources not yet deployed."
+description: "Azure cost management: query costs, forecast spending, optimize to reduce waste. WHEN: \"Azure costs\", \"Azure bill\", \"cost breakdown\", \"how much am I spending\", \"forecast spending\", \"optimize costs\", \"reduce spending\", \"orphaned resources\", \"rightsize VMs\", \"cost spike\", \"reduce storage costs\", \"AKS cost\". DO NOT USE FOR: deploying resources, provisioning, diagnostics, or security audits."
 license: MIT
 metadata:
   author: Microsoft
@@ -9,132 +9,37 @@ metadata:
 
 # Azure Cost Management Skill
 
-Unified skill for all Azure cost management tasks: querying historical costs, forecasting future spending, and optimizing to reduce waste.
+Query historical costs, forecast future spending, optimize to reduce waste.
 
-## When to Use This Skill
+## Routing
 
-Activate this skill when user wants to:
-- Query or analyze Azure costs (how much am I spending, show my bill, cost breakdown)
-- Break down costs by service, resource, location, or tag
-- Analyze cost trends over time
-- Forecast future Azure spending or project end-of-month costs
-- Optimize Azure costs, reduce spending, or find savings
-- Find orphaned or unused resources
-- Rightsize Azure VMs, containers, or services
-- Generate cost optimization reports
+| User Intent | Workflow |
+|-------------|----------|
+| Understand current costs | [Cost Query](cost-query/workflow.md) |
+| Reduce costs / find waste | [Cost Optimization](cost-optimization/workflow.md) |
+| Project future costs | [Cost Forecast](cost-forecast/workflow.md) |
 
 ## Quick Reference
 
 | Property | Value |
 |----------|-------|
-| **Query API Endpoint** | `POST {scope}/providers/Microsoft.CostManagement/query?api-version=2023-11-01` |
-| **Forecast API Endpoint** | `POST {scope}/providers/Microsoft.CostManagement/forecast?api-version=2023-11-01` |
-| **MCP Tools** | `azure__documentation`, `azure__extension_cli_generate`, `azure__get_azure_bestpractices` |
-| **CLI** | `az rest`, `az monitor metrics list`, `az resource list` |
-| **Required Role** | Cost Management Reader + Monitoring Reader + Reader on scope |
-
-## MCP Tools
-
-| Tool | Description | Parameters | When to Use |
-|------|-------------|------------|-------------|
-| `azure__documentation` | Search Azure documentation | `query` (Required): search terms | Research Cost Management API parameters and options |
-| `azure__extension_cli_generate` | Generate Azure CLI commands | `intent` (Required): task description, `cli-type` (Required): `"az"` | Construct `az rest` commands for cost queries |
-| `azure__get_azure_bestpractices` | Get Azure best practices | `intent` (Required): optimization context | Inform query design with cost management best practices |
-| `azure__extension_azqr` | Run Azure Quick Review compliance scan | `subscription` (Required): subscription ID, `resource-group` (Optional): resource group name | Find orphaned resources and cost optimization opportunities |
-| `azure__aks` | Azure Kubernetes Service operations | varies by sub-command | AKS cost analysis: list clusters, get node pools, inspect configuration |
-
-> 💡 **Tip:** Prefer MCP tools over direct CLI commands. Use `az rest` only when MCP tools don't cover the specific operation.
-
----
-
-## Routing
-
-Read the user's request and follow the appropriate workflow below.
-
-| User Intent | Workflow | Example Prompts |
-|-------------|----------|-----------------|
-| Understand current costs | [Cost Query Workflow](cost-query/workflow.md) | "how much am I spending", "cost by service", "show my bill" |
-| Reduce costs / find waste | [Cost Optimization Workflow](cost-optimization/workflow.md) | "optimize costs", "find orphaned resources", "reduce spending" |
-| Project future costs | [Cost Forecast Workflow](cost-forecast/workflow.md) | "forecast costs", "end of month estimate", "how much will I spend" |
-| Full cost picture | All three workflows combined | "give me the full picture of my Azure costs" |
-
-> **Important:** When optimizing costs, always present the total bill and cost breakdown alongside optimization recommendations.
-
----
-
-## Scope Reference (Shared Across All Workflows)
-
-| Scope | URL Pattern |
-|-------|-------------|
-| Subscription | `/subscriptions/<subscription-id>` |
-| Resource Group | `/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>` |
-| Management Group | `/providers/Microsoft.Management/managementGroups/<management-group-id>` |
-| Billing Account | `/providers/Microsoft.Billing/billingAccounts/<billing-account-id>` |
-| Billing Profile | `/providers/Microsoft.Billing/billingAccounts/<billing-account-id>/billingProfiles/<billing-profile-id>` |
-
-> 💡 **Tip:** These are scope paths only — not complete URLs. Combine with the API endpoint and version.
-
----
-
-## Part 1: Cost Query Workflow
-
-For the full cost query workflow (scope selection, report types, timeframes, dataset configuration, API calls, pagination, guardrails, examples, and error handling), see:
-
-📄 **[Cost Query Workflow](cost-query/workflow.md)**
-
----
-
-## Part 2: Cost Optimization Workflow
-
-For the full cost optimization workflow (prerequisites, best practices, Redis/AKS-specific analysis, Azure Quick Review, resource discovery, cost queries, pricing validation, utilization metrics, and report generation), see:
-
-📄 **[Cost Optimization Workflow](cost-optimization/workflow.md)**
-
----
-
-## Part 3: Cost Forecast Workflow
-
-For the full cost forecast workflow (scope selection, time period rules, dataset configuration, forecast-specific options, API calls, response interpretation, guardrails, and error handling), see:
-
-📄 **[Cost Forecast Workflow](cost-forecast/workflow.md)**
-
----
-
-## Data Classification
-
-- **ACTUAL DATA** = Retrieved from Azure Cost Management API
-- **ACTUAL METRICS** = Retrieved from Azure Monitor
-- **VALIDATED PRICING** = Retrieved from official Azure pricing pages
-- **ESTIMATED SAVINGS** = Calculated based on actual data and validated pricing
-
-## Best Practices
-
-- Always query actual costs first — never estimate or assume
-- Always present the total bill alongside optimization recommendations
-- Validate pricing from official sources — account for free tiers
-- Use REST API for cost queries (more reliable than `az costmanagement query`)
-- Always include the `ClientType: GitHubCopilotForAzure` header on all Cost Management API requests (`--headers "ClientType=GitHubCopilotForAzure"` in `az rest`)
-- Save audit trail — include all queries and responses
-- Include Azure Portal links for all resources
-- For costs < $10/month, emphasize operational improvements over financial savings
-- Never execute destructive operations without explicit approval
-- On 429 responses, check all `x-ms-ratelimit-microsoft.costmanagement-*-retry-after` headers (`qpu-retry-after`, `entity-retry-after`, `tenant-retry-after`), wait for the longest value, and do not retry until that duration has elapsed. The per-scope limit (4 requests/minute) is the most restrictive.
+| **Query API** | `POST {scope}/providers/Microsoft.CostManagement/query?api-version=2023-11-01` |
+| **Forecast API** | `POST {scope}/providers/Microsoft.CostManagement/forecast?api-version=2023-11-01` |
+| **Required Role** | Cost Management Reader + Monitoring Reader + Reader (on target scope) |
 
-## Common Pitfalls
+## Scope Patterns
 
-- **Assuming costs**: Always query actual data from Cost Management API
-- **Ignoring free tiers**: Many services have generous allowances
-- **Using wrong date ranges**: 30 days for costs, 14 days for utilization
-- **Not showing the bill**: Always present cost breakdown alongside optimization recommendations
-- **Cost query failures**: Use `az rest` with JSON body, not `az costmanagement query`
+- Subscription: `/subscriptions/<id>`
+- Resource Group: `/subscriptions/<id>/resourceGroups/<name>`
+- Management Group: `/providers/Microsoft.Management/managementGroups/<id>`
+- Billing Account: `/providers/Microsoft.Billing/billingAccounts/<id>`
 
-## Safety Requirements
+## Service-Specific Optimization
 
-- Get approval before deleting resources
-- Test changes in non-production first
-- Provide dry-run commands for validation
-- Include rollback procedures
+- [Redis](cost-optimization/services/redis/azure-cache-for-redis.md)
+- [Storage](cost-optimization/services/storage/azure-storage.md)
 
-## SDK Quick References
+## References
 
-- **Redis Management**: [.NET](cost-optimization/sdk/azure-resource-manager-redis-dotnet.md)
+- [MCP Tools, Best Practices, Safety](references/tools-and-best-practices.md)
+- [SDK: Redis .NET](cost-optimization/sdk/azure-resource-manager-redis-dotnet.md)