bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/shared/scripts/skf-validate-frontmatter.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.9"
+# requires-python = ">=3.11"
 # dependencies = ["pyyaml"]
 # ///
 """SKF Validate Frontmatter — agentskills.io frontmatter compliance checker.
@@ -22,6 +22,8 @@ system-wide:
   uv run skf-validate-frontmatter.py <skill-md-path> --skill-dir-name <name>
   uv run skf-validate-frontmatter.py <skill-md-path> --max-body-lines 500
   uv run skf-validate-frontmatter.py <skill-md-path> --max-body-lines 500 --max-body-tokens 5000
+  uv run skf-validate-frontmatter.py <skill-md-path> --forbid-angle-brackets
+  uv run skf-validate-frontmatter.py --check-name <name>
 
 Input:
   Path to a SKILL.md file.
@@ -37,6 +39,16 @@ Input:
   estimated as ceil(character_count / 4). skill-check treats
   `body.max_tokens` as a non-blocking warning, so this is advisory — the
   hard body pre-check is --max-body-lines.
+  Optional --forbid-angle-brackets: when set, count the `<` and `>` in the
+  description and emit a high-severity `description` issue when there are
+  any. Opt-in — create-skill passes it; other callers keep today's verdict.
+  The Claude platform does not accept a skill description that contains XML
+  tags; the agentskills.io specification has no such rule.
+  --check-name NAME, in place of the SKILL.md path: check NAME alone
+  against the name rule below (at most 64 characters, lower case, letters,
+  digits and single hyphens, no hyphen at either end), before any SKILL.md
+  exists. create-stack-skill checks a requested stack name with it, so a
+  name the pre-commit check would refuse halts before the run starts.
 
 Output:
   JSON object:
@@ -44,7 +56,12 @@ Output:
     issues:     list of { severity, field, message }
     frontmatter: parsed frontmatter dict (if parseable)
     body_lines: int body-line count, or null when delimiters are absent
+    description_angle_brackets: int count of `<` and `>` in the description,
+                or null unless --forbid-angle-brackets is set and the
+                description is a non-blank string
     summary:    { total, high, medium, low }
+  With --check-name: { status, name, issues, summary }, every issue on the
+  `name` field.
 
 Exit codes:
   0  — pass (no high-severity issues)
@@ -71,6 +88,13 @@ MAX_DESCRIPTION_LENGTH = 1024
 MAX_COMPATIBILITY_LENGTH = 500
 
 
+def count_angle_brackets(desc) -> int | None:
+    """Count `<` and `>` in a description; None when it is not a non-blank string."""
+    if not isinstance(desc, str) or not desc.strip():
+        return None
+    return desc.count("<") + desc.count(">")
+
+
 def parse_frontmatter(content: str) -> tuple[dict | None, list[dict]]:
     """Extract and parse YAML frontmatter from SKILL.md content.
 
@@ -244,11 +268,33 @@ def _validate_name(name: str, skill_dir_name: str | None) -> list[dict]:
     return issues
 
 
+def _summary(issues: list[dict]) -> tuple[str, dict]:
+    """The status and the summary counts of a list of issues."""
+    severity_counts = {"high": 0, "medium": 0, "low": 0}
+    for issue in issues:
+        severity_counts[issue["severity"]] += 1
+    if severity_counts["high"] > 0:
+        status = "fail"
+    elif severity_counts["medium"] > 0 or severity_counts["low"] > 0:
+        status = "warn"
+    else:
+        status = "pass"
+    return status, {"total": len(issues), **severity_counts}
+
+
+def check_name(name: str) -> dict:
+    """Check a skill name alone against the name rule (no SKILL.md, no directory match)."""
+    issues = _validate_name(name, None)
+    status, summary = _summary(issues)
+    return {"status": status, "name": name, "issues": issues, "summary": summary}
+
+
 def validate_frontmatter(
     content: str,
     skill_dir_name: str | None = None,
     max_body_lines: int | None = None,
     max_body_tokens: int | None = None,
+    forbid_angle_brackets: bool = False,
 ) -> dict:
     """Validate SKILL.md frontmatter against agentskills.io spec.
 
@@ -256,11 +302,15 @@ def validate_frontmatter(
     issue if the body exceeds that many lines. When `max_body_tokens` is
     set, emit a low-severity (advisory) `body` issue if the estimated token
     count exceeds that limit — skill-check treats body.max_tokens as a
-    non-blocking warning. Both are opt-in — the verdict is unchanged when
-    they are None. Returns a result dict with status, issues, frontmatter,
-    body_lines, body_tokens, and summary.
+    non-blocking warning. When `forbid_angle_brackets` is true, count the
+    `<` and `>` in the description as `description_angle_brackets` and emit
+    a high-severity `description` issue when there are any. All three are
+    opt-in — the verdict is unchanged when they are unset. Returns a result
+    dict with status, issues, frontmatter, body_lines, body_tokens,
+    description_angle_brackets, and summary.
     """
     fm, issues = parse_frontmatter(content)
+    angle_brackets = None
 
     body_lines = body_line_count(content)
     if max_body_lines is not None and body_lines is not None and body_lines > max_body_lines:
@@ -301,6 +351,17 @@ def validate_frontmatter(
                 "field": "description",
                 "message": f"description exceeds {MAX_DESCRIPTION_LENGTH} chars ({len(desc)} chars)",
             })
+        if forbid_angle_brackets:
+            angle_brackets = count_angle_brackets(desc)
+            if angle_brackets:
+                issues.append({
+                    "severity": "high",
+                    "field": "description",
+                    "message": (
+                        f"description contains {angle_brackets} angle bracket(s) ('<' or '>'); "
+                        "the Claude platform does not accept XML tags in a skill description"
+                    ),
+                })
 
         # Compatibility: optional, max 500 chars
         compat = fm.get("compatibility")
@@ -327,28 +388,15 @@ def validate_frontmatter(
                     "message": f"Unknown frontmatter field: '{key}'",
                 })
 
-    # Build summary
-    severity_counts = {"high": 0, "medium": 0, "low": 0}
-    for issue in issues:
-        severity_counts[issue["severity"]] += 1
-
-    if severity_counts["high"] > 0:
-        status = "fail"
-    elif severity_counts["medium"] > 0 or severity_counts["low"] > 0:
-        status = "warn"
-    else:
-        status = "pass"
-
+    status, summary = _summary(issues)
     return {
         "status": status,
         "issues": issues,
         "frontmatter": fm,
         "body_lines": body_lines,
         "body_tokens": body_tokens,
-        "summary": {
-            "total": len(issues),
-            **severity_counts,
-        },
+        "description_angle_brackets": angle_brackets,
+        "summary": summary,
     }
 
 
@@ -360,7 +408,8 @@ def main() -> int:
             "\n"
             "Checks: frontmatter delimiters, name format (Unicode letters + digits +\n"
             "hyphens, no consecutive/trailing hyphens), name-directory match,\n"
-            "description presence and length, compatibility length, and unknown fields.\n"
+            "description presence and length, compatibility length, unknown fields,\n"
+            "and (with --forbid-angle-brackets) angle brackets in the description.\n"
             "\n"
             "Exit code 0 means pass (no high-severity issues).\n"
             "Exit code 1 means fail (high-severity issues found)."
@@ -370,7 +419,17 @@ def main() -> int:
     parser.add_argument(
         "skill_md",
         metavar="SKILL.md",
-        help="path to the SKILL.md file to validate",
+        nargs="?",
+        help="path to the SKILL.md file to validate (omitted with --check-name)",
+    )
+    parser.add_argument(
+        "--check-name",
+        metavar="NAME",
+        default=None,
+        help=(
+            "check NAME alone against the skill-name rule, in place of a "
+            "SKILL.md: exit 1 when a high-severity name issue is found"
+        ),
     )
     parser.add_argument(
         "--skill-dir-name",
@@ -401,6 +460,15 @@ def main() -> int:
             "skill-check treats body.max_tokens as a non-blocking warning."
         ),
     )
+    parser.add_argument(
+        "--forbid-angle-brackets",
+        action="store_true",
+        help=(
+            "count the '<' and '>' in the description and emit a high-severity "
+            "'description' issue when there are any (opt-in). The Claude platform "
+            "does not accept XML tags in a skill description."
+        ),
+    )
     parser.add_argument(
         "-o", "--output",
         metavar="FILE",
@@ -408,20 +476,29 @@ def main() -> int:
     )
 
     args = parser.parse_args()
-    skill_md_path = Path(args.skill_md)
-
-    if not skill_md_path.exists():
+    if args.check_name is not None:
+        if args.skill_md is not None:
+            parser.error("--check-name takes no SKILL.md path")
+        result = check_name(args.check_name)
+    elif args.skill_md is None:
+        parser.error("the SKILL.md path is required (or pass --check-name NAME)")
+    elif not Path(args.skill_md).exists():
+        skill_md_path = Path(args.skill_md)
         result = {
             "status": "fail",
             "issues": [{"severity": "high", "field": "file", "message": f"File not found: {skill_md_path}"}],
             "frontmatter": None,
             "body_lines": None,
+            "description_angle_brackets": None,
             "summary": {"total": 1, "high": 1, "medium": 0, "low": 0},
         }
     else:
+        skill_md_path = Path(args.skill_md)
         content = skill_md_path.read_text(encoding="utf-8")
         skill_dir_name = args.skill_dir_name or skill_md_path.parent.name
-        result = validate_frontmatter(content, skill_dir_name, args.max_body_lines, args.max_body_tokens)
+        result = validate_frontmatter(
+            content, skill_dir_name, args.max_body_lines, args.max_body_tokens, args.forbid_angle_brackets
+        )
 
     output_text = json.dumps(result, indent=2)