fix(scripts): satisfy validate-scripts checks for skills list updates

Author: odinr

README.md

@@ -285,8 +285,9 @@ Capture Fusion skill workflow failure context and guide a draft-first bug report
 In this repository, use `fusion-<skill-name>` as the default skill naming convention.
 
 Some conventions you may see:
+- `skills/` 👍 Working skills
 - `skills/.experimental/` 🧪 preview / in-development skills
-- `skills/.curated/` ✅ curated, broadly reusable skills
+- `skills/.curated/` 👌 curated, broadly reusable skills
 - `skills/.system/` ⚙️ internal/system skills and shared building blocks
 
 ## 🔖 Versioning

scripts/list-skills/parse-frontmatter.ts

@@ -19,30 +19,50 @@ export function parseFrontmatter(frontmatter: string): Record<string, string> {
    * @returns Line with YAML inline comment removed when applicable.
    */
   function stripInlineComment(line: string): string {
-    let inSingleQuote = false;
-    let inDoubleQuote = false;
-    let escaped = false;
+    const quoteState = { inSingleQuote: false, inDoubleQuote: false, escaped: false };
+    const characters = Array.from(line);
 
-    for (let index = 0; index < line.length; index += 1) {
-      const char = line[index];
-      const previous = index > 0 ? line[index - 1] : "";
+    /**
+     * Determines whether a single-character token should count as whitespace.
+     *
+     * @param value - Single-character token.
+     * @returns True when the token is whitespace.
+     */
+    function isWhitespace(value: string): boolean {
+      return value.trim().length === 0;
+    }
+
+    // Walk the line left-to-right so we can stop at the first valid inline comment marker.
+    for (const [index, char] of characters.entries()) {
+      const previous = index > 0 ? characters[index - 1] : "";
 
-      if (char === "\\" && inDoubleQuote && !escaped) {
-        escaped = true;
+      // Track escapes only inside double-quoted strings so escaped quotes do not toggle quote state.
+      if (char === "\\" && quoteState.inDoubleQuote && !quoteState.escaped) {
+        quoteState.escaped = true;
         continue;
       }
 
-      if (char === "'" && !inDoubleQuote) {
-        inSingleQuote = !inSingleQuote;
-      } else if (char === '"' && !inSingleQuote && !escaped) {
-        inDoubleQuote = !inDoubleQuote;
+      // Toggle quote tracking so # inside quoted text is preserved as literal content.
+      if (char === "'" && !quoteState.inDoubleQuote) {
+        quoteState.inSingleQuote = !quoteState.inSingleQuote;
+      }
+
+      // Toggle double-quote tracking so escaped quotes do not prematurely end quoted text.
+      if (char === '"' && !quoteState.inSingleQuote && !quoteState.escaped) {
+        quoteState.inDoubleQuote = !quoteState.inDoubleQuote;
       }
 
-      if (char === "#" && !inSingleQuote && !inDoubleQuote && (!previous || /\s/.test(previous))) {
+      // Treat # as an inline comment marker only when it appears outside quotes after whitespace.
+      if (
+        char === "#" &&
+        !quoteState.inSingleQuote &&
+        !quoteState.inDoubleQuote &&
+        (!previous || isWhitespace(previous))
+      ) {
         return line.slice(0, index).trimEnd();
       }
 
-      escaped = false;
+      quoteState.escaped = false;
     }
 
     return line;

scripts/release-prepare/update-readme-skills-table.ts

@@ -22,14 +22,17 @@ type SkillRow = {
  * @returns Type icon for the README skills list.
  */
 function getSkillTypeIcon(relativePath: string): string {
+  // Match experimental skill paths first so preview entries get the dedicated icon.
   if (relativePath.startsWith("skills/.experimental/")) {
     return "🧪";
   }
 
+  // Match curated skill paths to keep curated content visually distinct.
   if (relativePath.startsWith("skills/.curated/")) {
     return "👌";
   }
 
+  // Match system skill paths to separate platform/internal skills from defaults.
   if (relativePath.startsWith("skills/.system/")) {
     return "⚙️";
   }
@@ -93,6 +96,7 @@ export function updateReadmeSkillsTable(repoRoot: string): number {
     const name = frontmatter.name?.trim();
     const description = frontmatter.description?.trim();
     const version = frontmatter["metadata.version"]?.trim();
+    // This regex normalizes Windows separators to POSIX separators for markdown links.
     const relativePath = relative(repoRoot, skillFile).replace(/\\/g, "/");
 
     // Fail fast here so the remaining logic can assume valid input.