feat(plugins): add FinOps Toolkit agent plugins #2167
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| { | ||
| "name": "finops-toolkit", | ||
| "owner": { | ||
| "name": "Microsoft" | ||
| }, | ||
| "metadata": { | ||
| "description": "Microsoft FinOps Toolkit plugins for AI-powered cloud financial management.", | ||
| "version": "15.0.0" | ||
| }, | ||
| "plugins": [ | ||
| { | ||
| "name": "microsoft-finops-toolkit", | ||
| "version": "15.0.0", | ||
| "source": "./plugins/microsoft-finops-toolkit", | ||
| "description": "AI-powered cloud financial management for Azure. Analyze costs with KQL queries against FinOps hubs, get CFO-level reporting, and access Azure Cost Management insights.", | ||
|
Collaborator
There was a problem hiding this comment. 🤖 [AI][Claude Code] 💡 Suggestion This description (and the matching one in |
||
| "category": "finops", | ||
| "homepage": "https://learn.microsoft.com/en-us/cloud-computing/finops/toolkit/finops-toolkit-overview" | ||
| }, | ||
| { | ||
|
MSBrett marked this conversation as resolved.
|
||
| "name": "microsoft-learn", | ||
| "source": { | ||
| "source": "url", | ||
| "url": "https://github.com/microsoftdocs/mcp.git" | ||
| }, | ||
| "description": "Access official Microsoft documentation, API references, and code samples for Azure, .NET, Windows, and more.", | ||
| "category": "documentation", | ||
| "homepage": "https://learn.microsoft.com" | ||
| } | ||
| ] | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| src/templates/agent-plugin |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| ../src/templates/agent-plugin |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,114 @@ | ||
| # Copyright (c) Microsoft Corporation. | ||
| # Licensed under the MIT License. | ||
|
|
||
| BeforeAll { | ||
| $script:RepoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../../..')).Path | ||
| $script:Plugin = Join-Path $script:RepoRoot 'src/templates/agent-plugin' | ||
| $script:PluginSource = './plugins/microsoft-finops-toolkit' | ||
| } | ||
|
|
||
| Describe 'Agent plugin manifest' { | ||
| It 'Ships a root plugin.json for GitHub Copilot CLI' { | ||
| Join-Path $script:Plugin 'plugin.json' | Should -Exist | ||
| } | ||
|
|
||
| It 'Ships a .claude-plugin/plugin.json for Claude' { | ||
| Join-Path $script:Plugin '.claude-plugin/plugin.json' | Should -Exist | ||
| } | ||
|
|
||
| It 'Uses a consistent plugin name across both manifests' { | ||
| $root = Get-Content (Join-Path $script:Plugin 'plugin.json') -Raw | ConvertFrom-Json | ||
| $claude = Get-Content (Join-Path $script:Plugin '.claude-plugin/plugin.json') -Raw | ConvertFrom-Json | ||
| $root.name | Should -Be $claude.name | ||
| } | ||
|
|
||
| It 'Points the agents field at a directory that exists' { | ||
| $root = Get-Content (Join-Path $script:Plugin 'plugin.json') -Raw | ConvertFrom-Json | ||
| Join-Path $script:Plugin ($root.agents -replace '^\./', '') | Should -Exist | ||
| } | ||
|
|
||
| It 'Loads MCP servers from .mcp.json in the plugin root' { | ||
| $root = Get-Content (Join-Path $script:Plugin 'plugin.json') -Raw | ConvertFrom-Json | ||
| $claude = Get-Content (Join-Path $script:Plugin '.claude-plugin/plugin.json') -Raw | ConvertFrom-Json | ||
|
|
||
| $root.mcpServers | Should -Be '.mcp.json' | ||
| $claude.mcpServers | Should -BeNullOrEmpty | ||
| $claude.agents | Should -BeNullOrEmpty | ||
| Join-Path $script:Plugin '.mcp.json' | Should -Exist | ||
| } | ||
|
|
||
| It 'Uses unpinned Azure MCP latest package in .mcp.json' { | ||
| $mcp = Get-Content (Join-Path $script:Plugin '.mcp.json') -Raw | ConvertFrom-Json | ||
| $args = $mcp.mcpServers.'azure-mcp-server'.args | ||
| $packageArg = $args | Where-Object { $_ -like '@azure/mcp@*' } | Select-Object -First 1 | ||
|
|
||
| $packageArg | Should -Not -BeNullOrEmpty | ||
| $packageArg | Should -Be '@azure/mcp@latest' | ||
| } | ||
| } | ||
|
|
||
| Describe 'Agent plugin components' { | ||
| It 'Ships agent definitions as NAME.agent.md files' { | ||
| $agents = Get-ChildItem (Join-Path $script:Plugin 'agents') -Filter '*.agent.md' | ||
| $agents.Count | Should -BeGreaterThan 0 | ||
| } | ||
|
|
||
| It 'Gives every agent a name and description in front matter' { | ||
| Get-ChildItem (Join-Path $script:Plugin 'agents') -Filter '*.agent.md' | ForEach-Object { | ||
| $content = Get-Content $_.FullName -Raw | ||
| $content | Should -Match '(?ms)^---\s.*^name:\s*\S.*^description:\s*\S.*^---' | ||
| } | ||
| } | ||
|
|
||
| It 'Ships slash commands under the ftk namespace' { | ||
| $commands = Get-ChildItem (Join-Path $script:Plugin 'commands/ftk') -Filter '*.md' | ||
| $commands.Count | Should -BeGreaterThan 0 | ||
| } | ||
|
|
||
| It 'Ships the finops-toolkit skill' { | ||
| Join-Path $script:Plugin 'skills/finops-toolkit/SKILL.md' | Should -Exist | ||
| } | ||
|
|
||
| It 'Documents required kusto_query parameters in skill docs' { | ||
| foreach ($doc in @('skills/finops-toolkit/SKILL.md', 'skills/finops-toolkit/README.md')) | ||
| { | ||
| $content = Get-Content (Join-Path $script:Plugin $doc) -Raw | ||
| $content | Should -Match 'azure-mcp-server' | ||
| $content | Should -Match 'kusto_query' | ||
| $content | Should -Match '"subscription"\s*:' | ||
| } | ||
| } | ||
|
|
||
| It 'Ships plugin root README for marketplace onboarding' { | ||
| Join-Path $script:Plugin 'README.md' | Should -Exist | ||
| } | ||
| } | ||
|
|
||
| Describe 'Deprecated azure-cost-management skill' { | ||
| It 'No longer ships the azure-cost-management skill' { | ||
| Join-Path $script:Plugin 'skills/azure-cost-management' | Should -Not -Exist | ||
| } | ||
|
|
||
| It 'Is not referenced by any plugin manifest' { | ||
| foreach ($manifest in @('plugin.json', '.claude-plugin/plugin.json')) | ||
| { | ||
| $content = Get-Content (Join-Path $script:Plugin $manifest) -Raw | ||
| $content | Should -Not -Match 'azure-cost-management' | ||
| } | ||
| } | ||
| } | ||
|
|
||
| Describe 'Plugin discovery and marketplaces' { | ||
| It 'Resolves the .plugin discovery pointer to a plugin manifest' { | ||
| Join-Path $script:RepoRoot '.plugin/plugin.json' | Should -Exist | ||
| } | ||
|
|
||
| It 'Points every marketplace source at the plugin directory' { | ||
| foreach ($marketplace in @('.github/plugin/marketplace.json', '.claude-plugin/marketplace.json')) | ||
| { | ||
| $json = Get-Content (Join-Path $script:RepoRoot $marketplace) -Raw | ConvertFrom-Json | ||
| $entry = $json.plugins | Where-Object { $_.name -eq 'microsoft-finops-toolkit' } | ||
| $entry.source | Should -Be $script:PluginSource | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # Copyright (c) Microsoft Corporation. | ||
| # Licensed under the MIT License. | ||
|
|
||
| [CmdletBinding()] | ||
| param( | ||
| [Parameter(Mandatory = $true)] | ||
| [string] | ||
| $DestDir | ||
| ) | ||
|
|
||
| $repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../..')).Path | ||
| $skillsDir = Join-Path $DestDir 'skills' | ||
|
|
||
| if (-not (Test-Path $skillsDir)) | ||
| { | ||
| return | ||
| } | ||
|
|
||
| $finopsSkill = Join-Path $skillsDir 'finops-toolkit' | ||
| if (Test-Path $finopsSkill) | ||
| { | ||
| $queryDest = Join-Path $finopsSkill 'references/queries' | ||
| Remove-Item $queryDest -Recurse -Force -ErrorAction SilentlyContinue | ||
| Copy-Item (Join-Path $repoRoot 'src/queries') -Destination $queryDest -Recurse -Force | ||
|
|
||
| $docsDest = Join-Path $finopsSkill 'references/docs-mslearn' | ||
| Remove-Item $docsDest -Recurse -Force -ErrorAction SilentlyContinue | ||
| Copy-Item (Join-Path $repoRoot 'docs-mslearn') -Destination $docsDest -Recurse -Force | ||
| } | ||
|
|
||
| Get-ChildItem $DestDir -Force -Recurse -Filter '.DS_Store' | Remove-Item -Force |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
MSBrett marked this conversation as resolved.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| { | ||
| "unversionedZip": true, | ||
| "scripts": [ | ||
| "Build-AgentPlugin.ps1" | ||
| ] | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| { | ||
| "mcpServers": { | ||
| "azure-mcp-server": { | ||
| "command": "npx", | ||
| "args": ["-y", "@azure/mcp@latest", "server", "start", "--namespace", "kusto", "--read-only"] | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| # FinOps Toolkit agent plugin | ||
|
|
||
| This plugin is the single source artifact used by marketplace entries in this repo. | ||
|
|
||
| For setup and usage: | ||
|
|
||
| - Skill overview and task routing: `./skills/finops-toolkit/SKILL.md` | ||
| - Querying and workflows: `./skills/finops-toolkit/README.md` | ||
| - MCP server configuration: `./.mcp.json` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| --- | ||
| name: azure-capacity-manager | ||
| description: "Use this agent when the user needs Azure capacity evidence for FinOps work: quota analysis, capacity reservation groups, SKU availability, region or zone access, AKS capacity readiness, non-compute quotas, capacity planning, or coordination between capacity guarantees and pricing commitments." | ||
| --- | ||
|
|
||
| You are an Azure capacity evidence specialist for FinOps workflows. You map Azure quota, region, SKU, zone, capacity reservation, AKS, and non-compute limit evidence into the canonical FinOps Framework. You do not present Azure capacity management or azcapman as a separate operating framework. | ||
|
|
||
| ## FinOps capability mapping | ||
|
|
||
| Use these canonical FinOps Framework capabilities when framing capacity findings: | ||
|
|
||
| - **Planning & Estimating**: Size planned workloads, scale units, deployment stamps, and upcoming demand before quota, region, SKU, or reserved-capacity requests. | ||
| - **Forecasting**: Project when demand will exceed quota, access, SKU, zone, or reserved-capacity headroom. | ||
| - **Architecting & Workload Placement**: Evaluate regions, zones, SKUs, deployment stamps, quota pools, and placement constraints. | ||
| - **Usage Optimization**: Identify overallocated, underused, or inefficient quota, capacity reservation, and workload patterns. | ||
| - **Rate Optimization**: Coordinate capacity guarantees with Azure Reservations and savings plans when cost evidence supports a pricing commitment. | ||
| - **Governance, Policy & Risk**: Surface capacity, quota, region, or zone risks with owners, thresholds, exception status, and escalation paths. | ||
| - **Automation, Tools & Services**: Recommend alerts, CI/CD gates, scripts, and operating checks that expose capacity risk before deployment or scale events. | ||
|
|
||
| ## Hard boundaries | ||
|
|
||
| - Capacity reservations guarantee compute supply. Azure Reservations and savings plans reduce price. They are coordinated, but they are not substitutes. | ||
| - Quota is an entitlement limit, not proof that physical capacity is available. | ||
| - Region access, quota increases, and zonal enablement are separate controls with separate approval paths. | ||
| - Logical availability-zone labels are subscription-specific. Verify physical zone mapping before cross-subscription CRG or zonal architecture decisions. | ||
| - Do not query FinOps Hub Kusto data directly. Ask `ftk-database-query` for cost, commitment, savings, recommendation, transaction, and forecast evidence. | ||
| - Do not make finance approval decisions. Consult `chief-financial-officer` through the FinOps practitioner when commitment, budget, or executive tradeoff decisions are material. | ||
|
|
||
| ## Evidence you own | ||
|
|
||
| - VM family quota usage, quota headroom, quota groups, and quota transfers. | ||
| - Capacity reservation groups, CRG sharing, overallocation, utilization, and region or zone alignment. | ||
| - SKU availability, offer restrictions, region access, and zonal enablement. | ||
| - AKS node pool capacity readiness and CRG association constraints. | ||
| - Storage, networking, database, and other non-compute service quota risks. | ||
| - Azure implementation guidance from Microsoft Learn and repo-provided references. | ||
|
|
||
| ## Collaboration model | ||
|
|
||
| - Work with `finops-practitioner` as the operating-rhythm owner. | ||
| - Ask `ftk-database-query` for Kusto-backed cost, commitment, recommendation, savings, and forecast evidence. | ||
| - Consult `chief-financial-officer` only through executive or financial-decision framing, not for raw telemetry collection. | ||
| - Coordinate with `ftk-hubs-agent` when capacity evidence affects FinOps Hubs platform deployment or Azure Data Explorer SKU readiness. | ||
|
|
||
| ## Output expectations | ||
|
|
||
| For capacity, quota, SKU, CRG, region, zone, AKS, or PaaS limit reports, include: | ||
|
|
||
| 1. **Summary**: Capacity posture, top blocker, exact scope, and time period. | ||
| 2. **FinOps capability status**: Findings mapped to the canonical capabilities above. | ||
| 3. **Risk register**: Subscription, region, service or SKU, usage, limit, utilization, headroom, source, status, and owner or action. | ||
| 4. **Capacity and workload actions**: Quota increase, quota transfer, region access, zonal enablement, SKU substitution, CRG create/resize/share, alert, or policy/gate action. | ||
| 5. **Confidence and caveats**: Evidence freshness, API gaps, estimated limits, zone mapping gaps, and missing owner metadata. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.