From b2b26345a7a9669afbba177b3da0a61ae30118d3 Mon Sep 17 00:00:00 2001
From: ppiankov <103106369+ppiankov@users.noreply.github.com>
Date: Sat, 1 Aug 2026 23:25:50 +0800
Subject: [PATCH 1/2] fix: co-locate SKILL.md JSON output with the --format
 flag

ANCC's skill-md-flags and skill-md-json-output checks want the JSON
output schema documented under the same command section as the
--format flag that produces it. The prior rewrite put --format under
aws/gcp but the JSON block under the flagless version command, and
never spelled out the literal --format json value. Move the schema
under aws (gcp references it), and make the json value explicit.
---
 docs/SKILL.md | 64 ++++++++++++++++++++++++++-------------------------
 1 file changed, 33 insertions(+), 31 deletions(-)

diff --git a/docs/SKILL.md b/docs/SKILL.md
index 2a390a7..6bcb8e7 100644
--- a/docs/SKILL.md
+++ b/docs/SKILL.md
@@ -28,42 +28,14 @@ Scans AWS RDS instances and manual snapshots for waste and security findings.
 - `--cpu-threshold float` — flag oversized if p95 CPU is below this percent (default 20.0)
 - `--idle-cpu float` — flag idle if avg CPU is below this percent (default 5.0)
 - `--metric-days int` — CloudWatch metric lookback period in days (default 14)
-- `--format string` — output format: text, json, sarif, spectrehub (default "text")
+- `--format string` — output format: `text` (default), `sarif`, `spectrehub`, or `--format json` for the `spectre/v1` envelope
 - `-o, --output string` — output file path (default: stdout)
 - `--min-monthly-cost float` — minimum monthly cost to report, in USD (default 0.10)
 - `--no-progress` — disable progress output
 - `--timeout duration` — scan timeout (default 10m)
 - `--exclude-tags strings` — exclude resources by tag, `Key=Value`, comma-separated
 
-### rdsspectre gcp
-
-Scans GCP Cloud SQL instances for waste and security findings.
-
-**Flags:**
-- `--project string` — GCP project ID (required)
-- `--format string` — output format: text, json, sarif, spectrehub (default "text")
-- `-o, --output string` — output file path (default: stdout)
-- `--min-monthly-cost float` — minimum monthly cost to report, in USD (default 0.10)
-- `--no-progress` — disable progress output
-- `--timeout duration` — scan timeout (default 10m)
-- `--exclude-tags strings` — exclude resources by label, `Key=Value`, comma-separated
-
-### rdsspectre init
-
-Writes a sample `.rdsspectre.yaml` config and a read-only IAM policy
-(`rdsspectre-policy.json`) to the current directory.
-
-**Flags:**
-- `--force` — overwrite existing files
-
-**Exit codes:**
-- 0: files written, or already present and left unchanged (a message is printed; use `--force` to overwrite)
-
-### rdsspectre version
-
-Prints version, commit, and build date. No flags.
-
-**JSON output** (`--format json` on `aws`/`gcp`, `spectre/v1` schema):
+**JSON output** (`--format json`, `spectre/v1` schema — `gcp` uses the same envelope):
 ```json
 {
   "schema": "spectre/v1",
@@ -103,10 +75,40 @@ Prints version, commit, and build date. No flags.
 }
 ```
 
-**Exit codes** (`aws`/`gcp`):
+**Exit codes:**
 - 0: scan completed — a clean account and a scan with findings both exit 0; check `findings`/`summary`, not the exit code, for results
 - 1: scan failed (authentication, network, invalid flags/config, or output-file write error)
 
+### rdsspectre gcp
+
+Scans GCP Cloud SQL instances for waste and security findings.
+
+**Flags:**
+- `--project string` — GCP project ID (required)
+- `--format string` — output format: `text` (default), `sarif`, `spectrehub`, or `--format json` for the same `spectre/v1` envelope as `aws` (see above)
+- `-o, --output string` — output file path (default: stdout)
+- `--min-monthly-cost float` — minimum monthly cost to report, in USD (default 0.10)
+- `--no-progress` — disable progress output
+- `--timeout duration` — scan timeout (default 10m)
+- `--exclude-tags strings` — exclude resources by label, `Key=Value`, comma-separated
+
+**Exit codes:** same as `aws` above.
+
+### rdsspectre init
+
+Writes a sample `.rdsspectre.yaml` config and a read-only IAM policy
+(`rdsspectre-policy.json`) to the current directory.
+
+**Flags:**
+- `--force` — overwrite existing files
+
+**Exit codes:**
+- 0: files written, or already present and left unchanged (a message is printed; use `--force` to overwrite)
+
+### rdsspectre version
+
+Prints version, commit, and build date. No flags.
+
 ## Handoffs
 
 - Output: `spectre/v1` JSON envelope. Next: `spectrehub collect --tool rdsspectre` for aggregation across scanners.

From b1010d042682e5b1cc5543a4f14bf141452ee07d Mon Sep 17 00:00:00 2001
From: ppiankov <103106369+ppiankov@users.noreply.github.com>
Date: Sat, 1 Aug 2026 23:37:32 +0800
Subject: [PATCH 2/2] fix: match ANCC's exact bold-label and flag-name parsing

Verified against ancc's own internal/skillmd/parser.go and
internal/validator/checks.go source: reBoldLabel requires the colon
INSIDE the ** markers (my prior "**JSON output** (...):" put it
outside, so the subsection was never recognized), and checkFlags only
inspects each flag's own backtick span (a "--format string" flag
description mentioning --format json in prose doesn't count). Use a
literal --format json flag entry and a bare **JSON output:** label,
simulated against the actual regexes before pushing.
---
 docs/SKILL.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/SKILL.md b/docs/SKILL.md
index 6bcb8e7..fda241d 100644
--- a/docs/SKILL.md
+++ b/docs/SKILL.md
@@ -28,14 +28,14 @@ Scans AWS RDS instances and manual snapshots for waste and security findings.
 - `--cpu-threshold float` — flag oversized if p95 CPU is below this percent (default 20.0)
 - `--idle-cpu float` — flag idle if avg CPU is below this percent (default 5.0)
 - `--metric-days int` — CloudWatch metric lookback period in days (default 14)
-- `--format string` — output format: `text` (default), `sarif`, `spectrehub`, or `--format json` for the `spectre/v1` envelope
+- `--format json` — output the `spectre/v1` JSON envelope (`--format` also accepts `text`, the default, `sarif`, and `spectrehub`)
 - `-o, --output string` — output file path (default: stdout)
 - `--min-monthly-cost float` — minimum monthly cost to report, in USD (default 0.10)
 - `--no-progress` — disable progress output
 - `--timeout duration` — scan timeout (default 10m)
 - `--exclude-tags strings` — exclude resources by tag, `Key=Value`, comma-separated
 
-**JSON output** (`--format json`, `spectre/v1` schema — `gcp` uses the same envelope):
+**JSON output:** `gcp` uses the same envelope.
 ```json
 {
   "schema": "spectre/v1",
@@ -85,7 +85,7 @@ Scans GCP Cloud SQL instances for waste and security findings.
 
 **Flags:**
 - `--project string` — GCP project ID (required)
-- `--format string` — output format: `text` (default), `sarif`, `spectrehub`, or `--format json` for the same `spectre/v1` envelope as `aws` (see above)
+- `--format json` — output the same `spectre/v1` envelope as `aws` (`--format` also accepts `text`, the default, `sarif`, and `spectrehub`)
 - `-o, --output string` — output file path (default: stdout)
 - `--min-monthly-cost float` — minimum monthly cost to report, in USD (default 0.10)
 - `--no-progress` — disable progress output