Add storage-fsx-windows-sla-optimizer skill

llms.txt

@@ -29,6 +29,7 @@ Skills can be used with these AWS DevOps Agent types:
 - [VPC DNS Investigation Skill](skills/aws-vpc-dns-investigation/SKILL.md): Diagnoses VPC DNS resolution failures and validates DNS control-plane changes before they are applied, driving the aws-vpc-dns-diagnostics MCP server to observe live resolution from inside the affected subnet and to simulate a proposed change
 - [Bedrock Adoption Readiness Skill](skills/bedrock-adoption-readiness/SKILL.md): Assesses an AWS account's readiness to run Amazon Bedrock at production scale across IAM governance, data retention (ZDR), quota and capacity headroom, and operational observability, covering both the standard Bedrock and bedrock-mantle (OpenAI-compatible) surfaces with multi-region discovery
 - [Analytics OpenSearch Expertise Skill](skills/analytics-opensearch-expertise/SKILL.md): Performs read-only health assessments of Amazon OpenSearch Service domains through 24 deterministic checks across cluster health, storage and shards, performance, security, and cost optimization, producing a structured findings report with prioritized remediation guidance
+- [FSx for Windows SLA Optimizer Skill](skills/storage-fsx-windows-sla-optimizer/SKILL.md): Reviews one or many Amazon FSx for Windows File Server file systems for SLA readiness across seven availability dimensions (deployment type, Active Directory health, throughput and storage sizing, backups, maintenance window, and alarms) using read-only control-plane calls, with usage-pattern trend analysis (peak-aware throughput sizing, weekday/weekend profile, and storage growth projection) that produces a rated report and flags over-provisioned or idle capacity as cost-optimization opportunities
 
 ## Key Concepts
 

skills/storage-fsx-windows-sla-optimizer/.skilleval.yaml

@@ -0,0 +1,9 @@
+audit:
+  ignore:
+    - STR-016    # README alongside SKILL.md is intentional
+    - STR-011    # False positive: skill-eval's zero-dependency _simple_yaml_parse
+                 # cannot read YAML folded block scalars ("description: >"), so it
+                 # sees the description as the literal ">" (1 char). The real
+                 # description is 965 chars and is REQUIRED to be a folded block by
+                 # the AWS DevOps Agent upload validator (1024-char limit). Verified
+                 # correct in live DevOps Agent runs. Tracked upstream (parser gap).

skills/storage-fsx-windows-sla-optimizer/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to this skill are documented here. New entries go at the top.
+
+## [1.0.0] - 2026-09-01
+
+Initial release for AWS DevOps Agent.
+
+### Review scope
+- Read-only SLA-readiness and availability review of Amazon FSx for Windows File
+  Server file systems across seven dimensions: deployment type (Single-AZ vs
+  Multi-AZ), Active Directory health, throughput capacity sizing, storage capacity
+  headroom, backups, maintenance window, and CloudWatch alarm coverage.
+- **SLA Readiness rating** (High / Medium / Low / Indeterminate) with per-dimension
+  findings and remediation, grounded in AWS documentation thresholds (the 20%
+  free-storage guidance, the read + 2 × write throughput sizing formula, the Multi-AZ
+  recommendation from Security Hub control FSx.5, and the Misconfigured / Active
+  Directory reachability model). Rating precedence: any Critical → Low; else any
+  Warning or unverifiable dimension → Medium; else High.
+- Automatic single-file-system vs multi-file-system (fleet) routing by input count,
+  including batched review with manifest tracking and resume for 21+ file systems.
+
+### Active Directory / Misconfigured handling
+- `MISCONFIGURED` lifecycle is a 🔴 Critical availability finding (AD unreachable).
+- Targeted AD root-cause matching: the finding matches the reported failure detail
+  against known lifecycle codes and quotes a specific fix —
+  `ACTIVE_DIRECTORY_INVALID_CREDENTIALS` (rotated/expired service-account password,
+  plus the Protected Users / NTLM caveat),
+  `ACTIVE_DIRECTORY_INSUFFICIENT_PERMISSIONS` (OU delegation), and
+  `ACTIVE_DIRECTORY_COMP_ACC_REUSE_BLOCKED_BY_POLICY` (KB5020276 netjoin hardening →
+  "Allow computer account re-use" GPO).
+- `MISCONFIGURED_UNAVAILABLE` (quarantined) recognized as the most severe AD state —
+  data currently inaccessible after prolonged AD failure.
+- Names the read-only `AWSSupport-ValidateFSxWindowsADConfig` runbook as a follow-up
+  diagnostic (never executes it).
+
+### Trend / usage-pattern analysis
+- Usage-pattern (trend) analysis on the throughput and storage dimensions, built on
+  daily-aggregate CloudWatch metrics (`Period=86400`) over a configurable lookback
+  (default 30 days; 14 / 21 / 30 / 60 accepted).
+- **Peak-aware throughput sizing:** evaluates provisioned capacity against measured
+  **peak** demand (read + 2 × write at the daily peak), not just the window average,
+  catching weekday-morning throttling that an average hides. Peak figures are labeled
+  approximate (derived from daily `Maximum`).
+- **Weekday/weekend usage profile** classification, used as evidence for the
+  throughput cost note.
+- **Storage growth projection** to the 20%-full floor; a projection of ≤ 4 weeks is
+  surfaced as at least a Warning even when current free % is healthy.
+- New file systems (< ~14 days of history) report `insufficient-data` and skip
+  projections rather than extrapolating.
+
+### Cost optimization (advisory; never lowers the SLA rating)
+- Heavily over-provisioned throughput or storage flagged as 💰 right-sizing
+  opportunities.
+- **Idle-file-system** signal (near-zero data I/O and operations across the window) —
+  the strongest cost signal, surfaced first as a decommission candidate; supersedes
+  the over-provisioned-throughput note.
+- Throughput cost note carries a caveat when the recommended tier is at or below
+  32 MBps: FSx emits throughput-utilization metrics only at ≥ 32 MBps, so the 8/16
+  MBps tiers cannot be validated from CloudWatch and require customer-side observation.
+
+### Availability nuances
+- **Multi-AZ client-side failover caveat:** Linux/macOS clients and DNS-caching
+  runtimes (.NET on Linux, Lambda) do not auto-fail-over like Windows SMB clients;
+  third-party DNS (e.g. Infoblox) needs two A records (one per file-system IP); a
+  throughput-capacity update is a safe way to test failover.
+- **Single-AZ maintenance wording** is honest that the AWS "typically under ~20
+  minutes" figure is best-effort, not a guarantee; the whole window is treated as
+  potentially unavailable.
+- **Storage-optimization sequencing:** a storage increase triggers a background
+  optimization phase that can pin `FileServerDiskThroughputUtilization` near 100%, so
+  throughput should be raised before storage (notes the 4-modifications-per-24h
+  limit); an in-progress `STORAGE_OPTIMIZATION` action is surfaced as an ℹ️ info note
+  so elevated throughput metrics are read as transient.
+
+### Safety & operations
+- Self-contained data collection via read-only control-plane API calls and CloudWatch
+  metric reads (`use_aws`); no AWS profile or credentials requested from the user. The
+  skill never reads file/share data over SMB and never performs a write, update,
+  create, or delete.
+- Fully covered by the `AIDevOpsAgentAccessPolicy` managed policy — no additional IAM.
+- Pre-flight permissions/tooling handling reports unverifiable checks instead of
+  inferring configuration, capping the rating at Medium.
+- Deployment-type remediation correctly states Single-AZ cannot be converted to
+  Multi-AZ in place (create-new-and-migrate).
+- Final Delivery Contract: the report is emitted as a persisted artifact (when the
+  runtime supports it) and returned verbatim, preventing the host agent from
+  summarizing or reformatting it.
+- README documents out-of-scope FSx for Windows support themes (shadow copies/VSS, SMB
+  over WAN, file-search indexing, NTFS/SYSTEM ACLs, GPOs not applying to FSx nodes,
+  anti-malware) so the skill does not over-promise.
+
+### Notes
+- The frontmatter `description` is 965 characters, within the AWS DevOps Agent upload
+  validator's 1024-character limit.

skills/storage-fsx-windows-sla-optimizer/README.md

@@ -0,0 +1,202 @@
+# FSx for Windows SLA Optimizer Skill
+
+A skill for AWS DevOps Agent that performs a structured, **read-only** SLA-readiness
+and availability review of Amazon FSx for Windows File Server file systems, and
+surfaces cost-optimization opportunities where capacity is over-provisioned. It
+produces a rated report with prioritized findings and remediation guidance.
+
+## What it does
+
+Given one or more FSx for Windows file-system IDs (or a region to discover them in),
+the skill collects each file system's configuration and CloudWatch metrics using
+read-only control-plane API calls and evaluates it across seven availability
+dimensions:
+
+1. **Deployment type** — Single-AZ vs Multi-AZ (the primary availability lever;
+   Multi-AZ provides automatic cross-AZ failover)
+2. **Active Directory health** — Misconfigured-state detection and AD reachability,
+   the most common cause of FSx for Windows unavailability
+3. **Throughput capacity** — provisioned throughput vs measured **peak** demand
+   (read + 2 × write), for under-provisioning (SLA risk)
+4. **Storage capacity headroom** — free-space against the 20% guidance, with a
+   growth projection ("projected to reach the 20% floor in ~N weeks")
+5. **Backups** — automatic backup enablement and retention
+6. **Maintenance window** — configured, and (on Single-AZ) placed off peak hours
+7. **Alarms / observability** — CloudWatch alarm coverage, especially on
+   `FreeStorageCapacity`
+
+Each file system receives an **SLA Readiness rating** (High / Medium / Low /
+Indeterminate) with per-dimension findings.
+
+The throughput and storage checks are enriched with **usage-pattern (trend)
+analysis** built on daily-aggregate CloudWatch metrics over a configurable window
+(default 30 days): it evaluates throughput against **peak** demand (not just the
+average, catching e.g. weekday-morning throttling that averages hide), classifies the
+**weekday/weekend usage profile**, and projects **storage growth** to the 20%-full
+floor.
+
+While measuring utilization for the SLA checks, the skill also flags cost
+opportunities as 💰 advisory notes that never lower the SLA rating: **heavily
+over-provisioned throughput and storage**, and — the strongest signal — an
+**idle file system** (near-zero activity across the window) as a decommission
+candidate. Reviews are routed automatically:
+
+- **1 file system** → full single-file-system report
+- **2–20 file systems** → fleet report (summary matrix + details)
+- **21+ file systems** → batched fleet review with a manifest for progress tracking
+  and resume
+
+## Prerequisites
+
+The DevOps Agent role must have **read-only** permissions for the review to produce
+complete results:
+
+```
+fsx:DescribeFileSystems
+fsx:DescribeBackups
+ds:DescribeDirectories
+cloudwatch:GetMetricData
+cloudwatch:DescribeAlarms
+```
+
+(`sts:GetCallerIdentity` is also used to resolve the account ID; it requires no IAM
+permission.)
+
+**All of these are already covered by the AWS managed policy
+[`AIDevOpsAgentAccessPolicy`](https://docs.aws.amazon.com/devopsagent/latest/userguide/aws-devops-agent-security-devops-agent-iam-permissions.html)**
+(via `fsx:Describe*`, `ds:Describe*`, `cloudwatch:GetMetricData`, and
+`cloudwatch:Describe*`), so this skill needs **no additional IAM policy**. The skill
+reads the `Name` and cost-allocation tags from the `Tags` array returned inline by
+`fsx describe-file-systems`, so it does not require `fsx:ListTagsForResource` (which
+the managed policy does not grant). If a check ever lacks permission, the skill
+reports it as "Unable to verify" and caps the SLA Readiness rating at Medium rather
+than guessing the configuration.
+
+The skill **never** reads file or share data over SMB and **never** performs any
+write, create, update, or delete operation.
+
+> **Optional — running the AD validation runbook.** For a Misconfigured file system,
+> the skill recommends the `AWSSupport-ValidateFSxWindowsADConfig` Systems Manager
+> Automation runbook — a **read-only diagnostic** that checks Active Directory
+> reachability, credentials, and OU permissions. The skill only *names* it; it never
+> executes it. If your AgentSpace has **Agent Actions** enabled and the agent's role
+> is permitted to run it (`ssm:StartAutomationExecution` plus the runbook's own
+> permissions), the DevOps Agent can execute this runbook on your behalf as a
+> follow-up action. That execution is governed by your AgentSpace configuration and
+> IAM, independent of this skill's read-only control-plane allowlist.
+
+## Limitations
+
+- **Region-scoped.** FSx file-system IDs are region-scoped; the skill reviews one
+  region per run and will ask for the region if IDs are provided without one.
+- **Self-managed AD health is inferred.** For self-managed Active Directory there is
+  no Directory Service object to read, so AD health is inferred from the
+  file-system lifecycle (`MISCONFIGURED`) rather than a directory `Stage`. The skill
+  never connects to customer domain controllers directly.
+- **Deployment type is immutable.** The skill recommends creating a new Multi-AZ
+  file system and migrating; it cannot and does not change deployment type in place.
+- **Cost notes are directional.** Over-provisioning notes are based on measured
+  utilization vs provisioned capacity, not on billing data; they are advisory
+  right-sizing signals, not exact savings figures.
+- **Throughput metrics floor.** Some throughput metrics are only published for file
+  systems provisioned at ≥ 32 MBps; below that the report notes limited metrics.
+- **Trend needs history.** Usage-pattern analysis, peak detection, and the storage
+  growth projection need enough daily datapoints; for a file system younger than
+  ~14 days the skill reports "insufficient data" and skips the projections rather
+  than extrapolating. Peak figures are derived from daily `Maximum` statistics and
+  are therefore **approximate** (the busiest sub-interval of each day), not exact
+  instantaneous peaks.
+- **Throughput cost recommendations stop at 32 MBps.** Because FSx emits
+  throughput-utilization metrics only at ≥ 32 MBps, the skill can recommend stepping
+  *toward* the 32 MBps tier but cannot validate the 8/16 MBps tiers from CloudWatch;
+  those require customer-side observation after the change.
+
+## Scope boundaries (what this skill does not cover)
+
+This skill reviews **availability posture and capacity right-sizing** from the FSx
+control plane and CloudWatch. It deliberately does not diagnose data-plane, SMB, or
+Windows-feature behavior. The following are common FSx for Windows support themes
+that are **out of scope** — the skill will not flag or remediate them:
+
+- **Shadow copies (VSS).** FSx can auto-delete shadow copies under IOPS/latency
+  pressure or during data-deduplication optimization; shadow-copy tuning is not
+  assessed here.
+- **SMB over WAN / on-premises latency** is not a supported/measured access pattern.
+- **No built-in file-search indexing** — slow enterprise file search is a Windows
+  Search Service concern, not an FSx SLA dimension.
+- **NTFS permissions and the SYSTEM account.** The `SYSTEM` account requires Full
+  Control at the share root; removing it breaks automatic backups. The skill does not
+  read or audit NTFS ACLs (it never touches the data plane).
+- **GPOs do not apply to FSx file-server nodes** — you cannot harden or reconfigure
+  the managed nodes via Group Policy; the skill does not evaluate GPO posture.
+- **Anti-malware / AV** on file content is a customer shared-responsibility task and
+  is out of scope.
+- **Deployment type, storage-type direction, and AZ placement are immutable** — the
+  skill recommends migration paths but performs no changes.
+
+## Agent Types
+
+This skill is used by the following agent types (selected in the Operator Web App at
+upload time):
+
+- **Chat tasks** — conversational, on-demand reviews ("is `fs-0123...` highly
+  available?", "why is my FSx file system Misconfigured?", "is it over-provisioned?").
+- **Evaluation** — proactive, best-practices SLA reviews of a file system or fleet
+  against the seven dimensions.
+- **Incident RCA** — automated root cause analysis where an FSx for Windows file
+  system's availability posture (Single-AZ, Misconfigured AD, throughput
+  saturation, full storage) may be a contributing factor.
+
+Select **Generic** instead if you want the skill available to all agent types.
+
+## Uploading to AWS DevOps Agent
+
+To deploy this skill to your Agent Space, you can use any of three ways:
+
+**Option A: Import from GitHub (recommended)**
+
+If you have a [GitHub connection configured](https://docs.aws.amazon.com/devopsagent/latest/userguide/connecting-to-cicd-pipelines-connecting-github.html) in your Agent Space, you can import this skill directly from the repository. In the DevOps Agent web app, go to Settings → Add Skill → Import from repository, then point to the `skills/storage-fsx-windows-sla-optimizer` directory. See [Importing a skill from a repository](https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent-devops-agent-skills.html#creating-skills) for full instructions.
+
+> **Note:** You cannot connect the `aws` GitHub organization directly because the GitHub connection setup requires admin rights on the organization. Instead, connect your personal GitHub account and select any repository from it during the connection setup. Once a GitHub connection is established, you can import skills from any public repository, including this one, even if it wasn't selected during the connection setup.
+
+**Option B: Upload as a zip file**
+
+1. Zip the `storage-fsx-windows-sla-optimizer/` directory (only including allowed extensions):
+
+   ```bash
+   cd skills
+   zip -r storage-fsx-windows-sla-optimizer.zip storage-fsx-windows-sla-optimizer/ -i '*.md' '*.txt' '*.json' '*.yaml' '*.yml' '*.xml' '*.csv' '*.tsv' '*.html' '*.htm' '*.png' '*.jpg' '*.jpeg' '*.gif' '*.svg' '*.webp' '*.pdf' -x '*/.claude/*' '*/scripts/*' '*/README.md' '*/.skilleval.yaml' '*/.skilleval.yml' '*/CHANGELOG.md' '*/evals/*'
+   ```
+
+2. In the AWS DevOps Agent web app, navigate to the **Skills** page.
+3. Click **Add skill** → **Upload skill**.
+4. Drag and drop the `storage-fsx-windows-sla-optimizer.zip` file (max 6 MB).
+5. Select the agent types: **Chat tasks**, **Evaluation**, and **Incident RCA**.
+6. Click **Upload**.
+
+**Option C: Upload via the Asset API**
+
+Use the AWS DevOps Agent Asset API to programmatically manage skills — useful for CI/CD pipelines or automation workflows. Assign the skill to the `CHAT`, `EVALUATION`, and `INCIDENT_RCA` agent types. See [Managing a skill end-to-end](https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent-managing-assets.html#managing-a-skill-end-to-end) for the full API workflow.
+
+For more details, see [Uploading a skill](https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent-devops-agent-skills.html#creating-skills) in the AWS DevOps Agent User Guide.
+
+## How to use it with DevOps Agent
+
+Works with the **Chat**, **Evaluation**, and **Investigations / Incident RCA**
+subagents. Describe the task in natural language — you do not need to name the skill:
+
+- "Run an FSx for Windows SLA review on `fs-0123456789abcdef0` in us-east-1."
+- "Is my FSx file system `fs-0123...` highly available?"
+- "Why is my FSx for Windows file system in a Misconfigured state?"
+- "Is `fs-0123...` over-provisioned on throughput or storage?"
+- "Review these FSx Windows file systems for availability: `fs-aaa...`, `fs-bbb...`."
+- "Audit all my FSx for Windows file systems in eu-west-1 for SLA readiness."
+
+The agent gathers configuration and CloudWatch metrics via its `use_aws` tool under
+the assumed role in the target account, applies the finding logic, and returns a
+Markdown report artifact.
+
+## Non-production disclaimer
+
+> ⚠️ This skill is sample code, not intended for production use without additional
+> review and testing. Users should validate in a non-production environment first.