fix: make skill length-split fence-aware for vally reference extraction

The over-length split treated any line starting with "## " as a section
boundary, including lines inside fenced code blocks (some skills have "## "
inside sample-output blocks). Cutting there left SKILL.md with an odd number of
code fences, so vally treated everything after the last fence as fenced and
ignored the reference links in that region, reporting them as orphan files.

The split now only breaks at "## " headers outside code fences. Verified
locally with @microsoft/vally runLint: 33/33 skills pass.

Author: viragtripathi

.github/skills/auditing-cloud-cluster-security/SKILL.md

@@ -426,35 +426,6 @@ Severity is calibrated for production by default. Non-production environments do
 
 **Annotations:** `*(downgraded from FAIL — development cluster)*` or `*(PCI DSS compliance — cannot downgrade)*`
 
-## Report Format
-
-Save each audit report to `reports/security-audit-<cluster-name>-<YYYY-MM-DD>-<sequence>.md` (gitignored, local-only). The `reports/` directory is not committed to version control — it serves as a local log for historical comparison and remediation tracking.
-
-Generate a markdown report with the following structure:
-
-```
-# Security Audit Report — <Cluster Name>
-
-**Date:** YYYY-MM-DD
-**Cluster ID:** <cluster-id>
-**Plan:** Standard | Advanced | Self-hosted
-**CockroachDB Version:** vXX.X.X
-**Regions:** us-east-1, us-west-2
-**Deployment:** CockroachDB Cloud | Self-hosted
-**Environment:** production | staging | development | sandbox
-**Compliance:** SOC 2, PCI DSS | (none specified)
-**Data Sensitivity:** PII/PHI | financial | internal | public
-
-## Summary
-
-| Status | Count |
-|--------|-------|
-| PASS   | X     |
-| WARN   | X     |
-| FAIL   | X     |
-| INFO   | X     |
-| N/A    | X     |
-
 ## Additional details
 
 Further sections for this skill are in [references/additional-details.md](references/additional-details.md).

.github/skills/auditing-cloud-cluster-security/references/additional-details.md

@@ -1,5 +1,34 @@
 # Additional details
 
+## Report Format
+
+Save each audit report to `reports/security-audit-<cluster-name>-<YYYY-MM-DD>-<sequence>.md` (gitignored, local-only). The `reports/` directory is not committed to version control — it serves as a local log for historical comparison and remediation tracking.
+
+Generate a markdown report with the following structure:
+
+```
+# Security Audit Report — <Cluster Name>
+
+**Date:** YYYY-MM-DD
+**Cluster ID:** <cluster-id>
+**Plan:** Standard | Advanced | Self-hosted
+**CockroachDB Version:** vXX.X.X
+**Regions:** us-east-1, us-west-2
+**Deployment:** CockroachDB Cloud | Self-hosted
+**Environment:** production | staging | development | sandbox
+**Compliance:** SOC 2, PCI DSS | (none specified)
+**Data Sensitivity:** PII/PHI | financial | internal | public
+
+## Summary
+
+| Status | Count |
+|--------|-------|
+| PASS   | X     |
+| WARN   | X     |
+| FAIL   | X     |
+| INFO   | X     |
+| N/A    | X     |
+
 ## Findings
 
 ### Network Security

scripts/transform-skills-for-copilot.py

@@ -91,8 +91,19 @@ def split_for_length(skill_dir, text):
     if len(lines) <= MAX_LINES:
         return text
 
-    # Indices of level-2 section headers.
-    headers = [i for i, ln in enumerate(lines) if ln.startswith("## ")]
+    # Indices of level-2 section headers that are NOT inside a code fence.
+    # (Skill bodies contain fenced examples whose lines may start with "## ";
+    # splitting there would cut a code block in half and unbalance the fences,
+    # which breaks reference extraction in downstream linters.)
+    headers = []
+    in_fence = False
+    for i, ln in enumerate(lines):
+        stripped = ln.lstrip()
+        if stripped.startswith("```") or stripped.startswith("~~~"):
+            in_fence = not in_fence
+            continue
+        if not in_fence and ln.startswith("## "):
+            headers.append(i)
     if not headers:
         return text  # nothing safe to move