Skip to content

Add Claude Code plugin for FinOps hubs and Azure Cost Management#2043

Open
MSBrett wants to merge 31 commits intodevfrom
features/agentskills
Open

Add Claude Code plugin for FinOps hubs and Azure Cost Management#2043
MSBrett wants to merge 31 commits intodevfrom
features/agentskills

Conversation

@MSBrett
Copy link
Copy Markdown
Contributor

@MSBrett MSBrett commented Mar 4, 2026

Summary

Retry of #2013 after revert in #2023. Adds a Claude Code plugin with skills for FinOps hubs (KQL-based cost analysis) and Azure Cost Management (optimization, commitments, orphaned resources).

What's included

  • 2 skills: FinOps toolkit (hubs queries, deployment, FOCUS) and Azure Cost Management (Advisor, reservations, savings plans, orphaned resources)
  • 4 agents: CFO, FinOps practitioner, database query, hubs agent
  • 5 commands: cost-optimization, hubs-connect, hubs-healthCheck, mom-report, ytd-report
  • 1 output style: executive formatting
  • Version sync: Update-Version.ps1 now updates marketplace.json plugin versions

Issues from #2023 addressed

  • CLAUDE.md restored (symlink to AGENTS.md)
  • Packaging verified: Build-Toolkit claude-plugin resolves symlinks correctly (pwsh 7 Copy-Item -Recurse follows symlinks natively)
  • Plugin versioning aligned at 13.0.0
  • PR-2013-REVIEW-AUDIT.md removed

Test plan

  • Clean build: Build-Toolkit claude-plugin produces 293 files, 0 symlinks
  • Symlinks resolved to real content in release output
  • End-to-end plugin validation
  • ❎ Log not needed

msbrett and others added 21 commits February 9, 2026 11:38
@claude
Add AI tools: agents, skills, commands, and output style for FinOps T…
728db88 
…oolkit

Introduces the Claude Code plugin structure under src/ai-tools/ with:
- Agents: finops-practitioner, chief-financial-officer, ftk-database-query, ftk-hubs-agent
- Skills: azure-cost-management and finops-toolkit with reference docs and KQL query catalog
- Commands: hubs-connect, hubs-healthCheck, mom-report, ytd-report
- Output style: fact-grounded financial analysis formatting with evidence requirements
- Plugin manifest and marketplace configuration

Moves KQL queries from src/queries/ into skill reference structure.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Update plugin settings, paths, and command extensions
7664a38 
- Add .ftk/environments.local.md settings pattern for multi-environment config
- Rename command files from .prompt.md to .md for auto-discovery
- Replace all "project configuration" references with .ftk/environments.local.md
- Add settings-format.md reference documentation
- Update marketplace.json source to relative path
- Add docs publishing workflow to CLAUDE.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Move AI tools from src/ai-tools to src/claude-plugin
d1887fa 
Reorganize plugin components into the new src/claude-plugin directory
structure with updated plugin.json, README files, and marketplace config.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Symlink CLAUDE.md and AGENTS.md to .github/copilot-instructions.md
e1ee1a5 
Single source of truth for agent instructions across Claude Code,
GitHub Copilot, and other AI coding tools.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Add reservations and commitment discount decision references
b834fe9 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Merge branch 'dev' into features/agentskills
a33f72f
@claude
Add storage cost analysis reference and update savings plans
8a822a6 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Update azure-cost-management skill definition
aaa39f5 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Fix skill reference errors found during TDD evaluation sprint
f0fdaf7 
Fixes verified against live Azure APIs and repo source docs:
- azure-advisor: remove fabricated GUID row, add dismiss vs postpone note
- azure-credits: update stale product names (Ubuntu Pro, Citrix Virtual Apps)
- azure-savings-plans: fix REST method, API version, default params, embed scripts
- azure-reservations: new reference file for reserved instance analysis
- azure-commitment-discount-decision: new decision framework reference
- finops-hubs: add Transactions() to function list
- finops-hub-database-guide: fix CostsPlus phantom reference to costs-enriched-base
- ftk-hubs-connect: fix daterange() typo to datestring()
- quarterly-cost-by-resource-group: fix description to match top N row semantics
- Remove azure-storage-cost-analysis (non-functional)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Move plugin to src/templates/, add docs-mslearn links to SKILL.md
38952ed 
Relocated claude-plugin from src/claude-plugin to src/templates/claude-plugin
so it gets packaged by Package-Toolkit.ps1. Moved queries back to src/queries/
with symlink into plugin. Added docs-mslearn symlink and linked all 103
Microsoft Learn docs in finops-toolkit SKILL.md. Updated marketplace.json
path, reverted copilot-instructions.md and settings.json, added changelog.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Add cost optimization references and command from Azure Copilot gap a…
631a62a 
…nalysis

New reference files for orphaned resource detection (Resource Graph queries
for 8 resource types), Azure Retail Prices API (public pricing lookup), and
VM rightsizing workflow (Advisor + Monitor metrics + price validation). New
/ftk-cost-optimization command orchestrates all references into a structured
report. Updated SKILL.md with 3 new domains and trigger keywords. Added
cross-references from azure-advisor.md to rightsizing and orphaned resource
docs. Includes red/blue team remediation: fixed RI price calculation, VMSS
NIC exclusion, snapshot chain filtering, LB query null handling, bulk
cleanup error handling, BSD date syntax, Measure-Object scriptblock, and
Impact sort ordering.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@MSBrett
Update src/templates/claude-plugin/commands/ftk-mom-report.md
5799afd 
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@claude
chore: Update ms.date to fix CI workflow
9b15fac 
Update ms.date in changelog.md to today's date so the "Update ms.date
in docs-mslearn" workflow has nothing to push, avoiding the branch
protection failure.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Consolidate agent instructions into CLAUDE.md as single source of truth
735887f 
Restore CLAUDE.md as a regular file (was symlink to copilot-instructions.md),
make AGENTS.md and .github/copilot-instructions.md symlink to CLAUDE.md,
and update marketplace.json paths and categories.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Remove query catalog and coding standards from ftk-database-query agent
6455064 
The query catalog table and coding standards section were moved to the
skill reference layer, keeping the agent prompt focused on domain
expertise and operational behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Rename CLAUDE.md to AGENTS.md and update symlinks
3a44819 
AGENTS.md is now the canonical agent instructions file. CLAUDE.md and
.github/copilot-instructions.md are symlinks pointing to it, ensuring
all AI agents (Claude, Copilot) share the same instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Address all PR #2013 review feedback
63ae144 
Remediate 19 review items from flanakin's post-merge review of the
Claude Code plugin (reverted in PR #2023). Key changes:

- Update plugin version to 13.0.0 and integrate into Update-Version.ps1
- Fix plugin.json description (FinOps is a proper noun)
- Update FinOps Framework to 2025 Fx (4 principles, 2 domain names)
- Move commands into ftk/ subfolder for /ftk:* namespacing
- Prefix all working paths with ftk/ (visible, not .ftk/)
- Replace platform detection with tool availability detection
- Add phase checkpoints to mom-report, document iterative design intent
- Strengthen what-if as required pre-deployment step
- Fix Get-VmSkuPrice array bug (Select-Object -First 1)
- Copy Get-BenefitRecommendations.ps1 from azcapman
- Add FinOps alerts capability, rename to FinOps workbooks
- Update changelog version to v14
- Add PR-2013-REVIEW-AUDIT.md tracking all 19 items

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Fix copyright header casing in Get-BenefitRecommendations.ps1
0ef609e 
Match repo convention: "MIT License" (uppercase L) per finops-toolkit
style. Script sourced from microsoft/azcapman (MIT licensed).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@claude
Remove all azcapman references from finops-toolkit
ce3eb50 
Remove azure-capacity-management plugin entry from marketplace.json
and source script links from azure-advisor.md and azure-anomaly-alerts.md.
This repo should have no cross-references to external repos.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Refine Claude Code plugin: improve skills, commands, versioning, and …
fe89930 
…remove audit file

- Update SKILL.md files with streamlined task routing and best practices
- Add version sync for marketplace.json in Update-Version.ps1
- Improve command references and plugin metadata
- Remove PR-2013-REVIEW-AUDIT.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Merge dev into features/agentskills
96ae42a 
Resolved conflicts:
- .github/copilot-instructions.md: kept symlink to AGENTS.md
- docs-mslearn/toolkit/changelog.md: merged both changelog entries

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@microsoft-github-policy-service microsoft-github-policy-service bot added the Needs: Review 👀 PR that is ready to be reviewed label Mar 4, 2026
chore: Update ms.date in changelog
64e3f94 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@MSBrett MSBrett requested a review from Copilot March 4, 2026 16:32
Copilot AI reviewed Mar 4, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a Claude Code plugin template to the FinOps Toolkit repo, providing FinOps hubs (KQL-based) and Azure Cost Management workflows, agents, commands, and an executive output style, plus version sync updates.

Changes:

  • Added Claude plugin template (skills, agents, commands, output style) for FinOps hubs + Azure Cost Management.
  • Added extensive reference documentation and embedded scripts (e.g., Benefit Recommendations PowerShell).
  • Updated version automation (Update-Version.ps1) to sync Claude plugin versions in plugin.json and .claude-plugin/marketplace.json.

Reviewed changes

Copilot reviewed 46 out of 48 changed files in this pull request and generated 7 comments.

Show a summary per file
File Description
src/templates/claude-plugin/skills/finops-toolkit/references/workflows/ftk-hubs-healthCheck.md Adds FinOps hubs health check workflow reference
src/templates/claude-plugin/skills/finops-toolkit/references/workflows/ftk-hubs-connect.md Adds FinOps hubs cluster discovery/connect workflow reference
src/templates/claude-plugin/skills/finops-toolkit/references/settings-format.md Documents .ftk/environments.local.md format used by commands
src/templates/claude-plugin/skills/finops-toolkit/references/queries Adds link/symlink to shared query catalog for the plugin
src/templates/claude-plugin/skills/finops-toolkit/references/finops-hubs.md Adds FinOps hubs analysis guidance for the plugin skill
src/templates/claude-plugin/skills/finops-toolkit/references/finops-hubs-deployment.md Adds hubs deployment guidance for the plugin skill
src/templates/claude-plugin/skills/finops-toolkit/references/docs-mslearn Adds link/symlink to Microsoft Learn content within the plugin
src/templates/claude-plugin/skills/finops-toolkit/SKILL.md Defines the finops-toolkit skill triggers/routing and references
src/templates/claude-plugin/skills/finops-toolkit/README.md Documents the finops-toolkit skill contents and usage
src/templates/claude-plugin/skills/azure-cost-management/references/azure-vm-rightsizing.md Adds VM rightsizing workflow reference
src/templates/claude-plugin/skills/azure-cost-management/references/azure-savings-plans.md Adds savings plans guidance + embedded script documentation
src/templates/claude-plugin/skills/azure-cost-management/references/azure-retail-prices.md Adds Retail Prices API lookup reference
src/templates/claude-plugin/skills/azure-cost-management/references/azure-reservations.md Adds reservations guidance and comparison patterns
src/templates/claude-plugin/skills/azure-cost-management/references/azure-orphaned-resources.md Adds ARG orphaned-resource detection and cleanup patterns
src/templates/claude-plugin/skills/azure-cost-management/references/azure-macc.md Adds MACC tracking workflow reference
src/templates/claude-plugin/skills/azure-cost-management/references/azure-credits.md Adds Azure credits/prepayment tracking reference
src/templates/claude-plugin/skills/azure-cost-management/references/azure-cost-exports.md Adds Cost Management exports configuration reference
src/templates/claude-plugin/skills/azure-cost-management/references/azure-commitment-discount-decision.md Adds commitment discount decision framework reference
src/templates/claude-plugin/skills/azure-cost-management/references/azure-budgets.md Adds budgets creation/notification reference
src/templates/claude-plugin/skills/azure-cost-management/references/azure-anomaly-alerts.md Adds anomaly alert deployment reference (PowerShell/Bicep)
src/templates/claude-plugin/skills/azure-cost-management/references/azure-advisor.md Adds Advisor querying/suppression reference
src/templates/claude-plugin/skills/azure-cost-management/references/Get-BenefitRecommendations.ps1 Adds script for Cost Management benefit recommendations
src/templates/claude-plugin/skills/azure-cost-management/SKILL.md Defines the azure-cost-management skill triggers and references
src/templates/claude-plugin/skills/azure-cost-management/README.md Documents the azure-cost-management skill contents and usage
src/templates/claude-plugin/output-styles/ftk-output-style.md Adds output style for evidence-based financial reporting
src/templates/claude-plugin/commands/ftk/ytd-report.md Adds YTD report command workflow
src/templates/claude-plugin/commands/ftk/mom-report.md Adds month-over-month report command workflow
src/templates/claude-plugin/commands/ftk/hubs-healthCheck.md Adds hubs health check command workflow
src/templates/claude-plugin/commands/ftk/hubs-connect.md Adds hubs connect command workflow
src/templates/claude-plugin/commands/ftk/cost-optimization.md Adds cost optimization command workflow
src/templates/claude-plugin/agents/ftk-hubs-agent.md Adds hubs deployment/troubleshooting agent
src/templates/claude-plugin/agents/ftk-database-query.md Adds KQL/database querying agent
src/templates/claude-plugin/agents/finops-practitioner.md Adds FinOps practitioner agent
src/templates/claude-plugin/agents/chief-financial-officer.md Adds CFO agent
src/templates/claude-plugin/README.md Documents how to install/use the Claude plugin template
src/templates/claude-plugin/.claude-plugin/plugin.json Adds Claude plugin manifest and MCP server configuration
src/templates/claude-plugin/.build.config Adds build config for plugin packaging
src/scripts/Update-Version.ps1 Updates versioning script to sync plugin and marketplace versions
src/queries/finops-hub-database-guide.md Updates query best-practice pointer to costs-enriched-base
src/queries/catalog/quarterly-cost-by-resource-group.kql Adjusts header comments to match intended query semantics
src/queries/catalog/costs-enriched-base.kql Updates schema reference comment in the base query
docs-mslearn/toolkit/changelog.md Adds changelog entry for the plugin and updates ms.date
CLAUDE.md Replaces content with a link to AGENTS.md
AGENTS.md Adds agent guidance file content (restored from CLAUDE.md)
.github/copilot-instructions.md Replaces content with a link to AGENTS.md
.claude-plugin/marketplace.json Adds marketplace listing with finops-toolkit plugin entry

msbrett and others added 5 commits March 28, 2026 05:48
feat(agent-skills): consolidate skills into agent-skills/ with symlin…
e4299af 
…ks, tests, and audit fixes
fix(agent-skills): tighten finops toolkit references
a05e729 
Clarify how the finops-toolkit skill's shorthand routes map to packaged docs so the bundle layout is reviewed correctly. Correct the packaged reference links and align hub connection validation with function-based Costs() usage on the Hub database.
fix: address PR #2043 review comments
17ef5e4 
- Changelog: fix version (v13.0.0 not v14), command count (5 not 4),
  and clarify query catalog is linked not moved
- KQL: replace nonexistent numberstring()/daterange() with
  format_number()/format_datetime(), fix Costs to Costs() in command
- Grammar: add missing 'is' in hubs-healthCheck.md
- Encoding: use utf8NoBOM in Update-Version.ps1 to avoid BOM on PS 5.1

Skipped: @azure/mcp version pinning (accepted risk for latest)
Skipped: subscriptioin typo (already fixed)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Merge origin/dev into features/agentskills
2a945a6 
Resolve changelog conflicts: take newer ms.date, keep plugin section
under release date line.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
fix: resolve test failures from symlink paths on CI
8b98588 
- Update 7 test files to use agent-skills/ and src/queries/ paths
  instead of traversing symlinks (which don't resolve on Windows CI)
- Fix trailing comma parse error in DeepDiveTag test
- Sync grammar fix ('is less than') to workflow reference

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
msbrett and others added 4 commits March 30, 2026 11:14
fix: resolve remaining CI test failures
da19749 
- Skip environment evidence check when local file absent (CI compat)
- Fix learn.microsoft.com URL to root-relative in open-data.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
fix: remove brittle Foundation reference content-policing test
26e5363 
Test asserted specific regex patterns in markdown prose and had a
hardcoded local path. Not testing code behavior — just policing
doc wording, which breaks on any editorial change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
fix: remove brittle ClaudePlugin content-policing tests
b28ef1c 
All 8 ClaudePlugin.*.Tests.ps1 files were regex-matching markdown
prose rather than testing code behavior. They break on any editorial
change and had hardcoded local paths.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
chore: update ms.date in changed docs-mslearn files
5929844 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@MSBrett MSBrett marked this pull request as ready for review March 30, 2026 19:03
@MSBrett MSBrett requested a review from flanakin as a code owner March 30, 2026 19:03
@flanakin flanakin added this to the v15 milestone Mar 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@flanakin flanakin Awaiting requested review from flanakin flanakin is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

Needs: Review 👀 PR that is ready to be reviewed

Projects

None yet

Milestone

v15

Development

Successfully merging this pull request may close these issues.

3 participants

@MSBrett @flanakin