ma-agents 3.13.2 → 3.14.0

package/lib/bmad-cache/bmb/skills/bmad-workflow-builder/scripts/prepass-prompt-metrics.py

@@ -1,24 +1,28 @@
 #!/usr/bin/env python3
-"""Deterministic pre-pass for prompt craft scanner.
-
-Extracts metrics and flagged patterns from SKILL.md and prompt files
-so the LLM scanner can work from compact data instead of reading raw files.
-
-Covers:
-- SKILL.md line count and section inventory
-- Overview section size
-- Inline data detection (tables, fenced code blocks)
-- Defensive padding pattern grep
-- Meta-explanation pattern grep
-- Back-reference detection ("as described above")
-- Config header and progression condition presence per prompt
-- File-level token estimates (chars / 4 rough approximation)
-"""
-
 # /// script
 # requires-python = ">=3.9"
+# dependencies = ["tiktoken"]
 # ///
+"""Deterministic prompt-metrics pre-pass for the Analyze scanners.
+
+Reads SKILL.md, root-level prompt files, and references, and emits one compact
+JSON object the LLM scanners read instead of the raw files. Length is reported
+as tiktoken token counts via count_tokens (cl100k_base, chars//4 fallback);
+there is no line-count gate anywhere in this script.
+
+What it surfaces per file:
+  - token count and the counting method (tiktoken or fallback)
+  - frontmatter facts (name, description, description length, angle-bracket flag)
+  - section inventory (heading level + title)
+  - structural signals scanners care about: tables, fenced blocks, defensive
+    padding, meta-explanation, back-references, config header, progression cues
 
+Budgets the scanners compare against: SKILL.md ~1500-2500 tokens,
+multi-branch reference ~4500, single-purpose reference ~9000.
+
+Usage:
+  prepass-prompt-metrics.py <skill-dir> [--output FILE]
+"""
 from __future__ import annotations
 
 import argparse
@@ -28,258 +32,219 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+# Reuse the single length metric rather than reimplementing token counting.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+try:
+    from count_tokens import count_tokens
+except Exception:  # pragma: no cover - count_tokens ships alongside this script
+    def count_tokens(text: str) -> tuple[int, str]:
+        return len(text) // 4, "fallback"
+
 
-# Defensive padding / filler patterns
 WASTE_PATTERNS = [
-    (r'\b[Mm]ake sure (?:to|you)\b', 'defensive-padding', 'Defensive: "make sure to/you"'),
-    (r"\b[Dd]on'?t forget (?:to|that)\b", 'defensive-padding', "Defensive: \"don't forget\""),
-    (r'\b[Rr]emember (?:to|that)\b', 'defensive-padding', 'Defensive: "remember to/that"'),
-    (r'\b[Bb]e sure to\b', 'defensive-padding', 'Defensive: "be sure to"'),
-    (r'\b[Pp]lease ensure\b', 'defensive-padding', 'Defensive: "please ensure"'),
-    (r'\b[Ii]t is important (?:to|that)\b', 'defensive-padding', 'Defensive: "it is important"'),
-    (r'\b[Yy]ou are an AI\b', 'meta-explanation', 'Meta: "you are an AI"'),
-    (r'\b[Aa]s a language model\b', 'meta-explanation', 'Meta: "as a language model"'),
-    (r'\b[Aa]s an AI assistant\b', 'meta-explanation', 'Meta: "as an AI assistant"'),
-    (r'\b[Tt]his (?:workflow|skill|process) is designed to\b', 'meta-explanation', 'Meta: "this workflow is designed to"'),
-    (r'\b[Tt]he purpose of this (?:section|step) is\b', 'meta-explanation', 'Meta: "the purpose of this section is"'),
-    (r"\b[Ll]et'?s (?:think about|begin|start)\b", 'filler', "Filler: \"let's think/begin\""),
-    (r'\b[Nn]ow we(?:\'ll| will)\b', 'filler', "Filler: \"now we'll\""),
+    (r"\b[Mm]ake sure (?:to|you)\b", "defensive-padding", 'Defensive: "make sure to/you"'),
+    (r"\b[Dd]on'?t forget (?:to|that)\b", "defensive-padding", 'Defensive: "don\'t forget"'),
+    (r"\b[Rr]emember (?:to|that)\b", "defensive-padding", 'Defensive: "remember to/that"'),
+    (r"\b[Bb]e sure to\b", "defensive-padding", 'Defensive: "be sure to"'),
+    (r"\b[Pp]lease ensure\b", "defensive-padding", 'Defensive: "please ensure"'),
+    (r"\b[Ii]t is important (?:to|that)\b", "defensive-padding", 'Defensive: "it is important"'),
+    (r"\b[Yy]ou are an AI\b", "meta-explanation", 'Meta: "you are an AI"'),
+    (r"\b[Aa]s a language model\b", "meta-explanation", 'Meta: "as a language model"'),
+    (r"\b[Aa]s an AI assistant\b", "meta-explanation", 'Meta: "as an AI assistant"'),
+    (r"\b[Tt]his (?:workflow|skill|process) is designed to\b", "meta-explanation", 'Meta: "this is designed to"'),
+    (r"\b[Tt]he purpose of this (?:section|step) is\b", "meta-explanation", 'Meta: "the purpose of this is"'),
 ]
 
-# Back-reference patterns (self-containment risk)
 BACKREF_PATTERNS = [
-    (r'\bas described above\b', 'Back-reference: "as described above"'),
-    (r'\bper the overview\b', 'Back-reference: "per the overview"'),
-    (r'\bas mentioned (?:above|in|earlier)\b', 'Back-reference: "as mentioned above/in/earlier"'),
-    (r'\bsee (?:above|the overview)\b', 'Back-reference: "see above/the overview"'),
-    (r'\brefer to (?:the )?(?:above|overview|SKILL)\b', 'Back-reference: "refer to above/overview"'),
+    (r"\bas described above\b", 'Back-reference: "as described above"'),
+    (r"\bas mentioned (?:above|in|earlier)\b", 'Back-reference: "as mentioned above/earlier"'),
+    (r"\bsee (?:above|the overview)\b", 'Back-reference: "see above/the overview"'),
+    (r"\brefer to (?:the )?(?:above|overview|SKILL)\b", 'Back-reference: "refer to above/overview"'),
 ]
 
+ALLCAPS_PATTERN = re.compile(r"\b(?:ALWAYS|NEVER|MUST|DO NOT|CRITICAL|REQUIRED)\b")
+NUMBERED_PREFIX = re.compile(r"^\d{2}[-_]")
+
+
+def split_frontmatter(content: str) -> tuple[dict, str]:
+    """Return (frontmatter dict, body). Empty dict when there is no frontmatter."""
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}, content
+    end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
+    if end is None:
+        return {}, content
+    meta: dict[str, str] = {}
+    for line in lines[1:end]:
+        if ":" in line:
+            k, v = line.split(":", 1)
+            meta[k.strip()] = v.strip()
+    return meta, "\n".join(lines[end + 1:])
+
 
 def count_tables(content: str) -> tuple[int, int]:
-    """Count markdown tables and their total lines."""
-    table_count = 0
-    table_lines = 0
+    count = rows = 0
     in_table = False
-    for line in content.split('\n'):
-        if '|' in line and re.match(r'^\s*\|', line):
+    for line in content.split("\n"):
+        if re.match(r"^\s*\|", line):
             if not in_table:
-                table_count += 1
+                count += 1
                 in_table = True
-            table_lines += 1
+            rows += 1
         else:
             in_table = False
-    return table_count, table_lines
+    return count, rows
 
 
-def count_fenced_blocks(content: str) -> tuple[int, int]:
-    """Count fenced code blocks and their total lines."""
-    block_count = 0
-    block_lines = 0
+def count_fenced(content: str) -> int:
+    blocks = 0
     in_block = False
-    for line in content.split('\n'):
-        if line.strip().startswith('```'):
+    for line in content.split("\n"):
+        if line.strip().startswith("```"):
+            in_block = not in_block
             if in_block:
-                in_block = False
-            else:
-                in_block = True
-                block_count += 1
-        elif in_block:
-            block_lines += 1
-    return block_count, block_lines
-
-
-def extract_overview_size(content: str) -> int:
-    """Count lines in the ## Overview section."""
-    lines = content.split('\n')
-    in_overview = False
-    overview_lines = 0
-    for line in lines:
-        if re.match(r'^##\s+Overview\b', line):
-            in_overview = True
-            continue
-        elif in_overview and re.match(r'^##\s', line):
-            break
-        elif in_overview:
-            overview_lines += 1
-    return overview_lines
-
-
-def scan_file_patterns(filepath: Path, rel_path: str) -> dict:
-    """Extract metrics and pattern matches from a single file."""
-    content = filepath.read_text(encoding='utf-8')
-    lines = content.split('\n')
-    line_count = len(lines)
-
-    # Token estimate (rough: chars / 4)
-    token_estimate = len(content) // 4
-
-    # Section inventory
-    sections = []
-    for i, line in enumerate(lines, 1):
-        m = re.match(r'^(#{2,3})\s+(.+)$', line)
-        if m:
-            sections.append({'level': len(m.group(1)), 'title': m.group(2).strip(), 'line': i})
-
-    # Tables and code blocks
-    table_count, table_lines = count_tables(content)
-    block_count, block_lines = count_fenced_blocks(content)
-
-    # Pattern matches
-    waste_matches = []
-    for pattern, category, label in WASTE_PATTERNS:
-        for m in re.finditer(pattern, content):
-            line_num = content[:m.start()].count('\n') + 1
-            waste_matches.append({
-                'line': line_num,
-                'category': category,
-                'pattern': label,
-                'context': lines[line_num - 1].strip()[:100],
-            })
-
-    backref_matches = []
-    for pattern, label in BACKREF_PATTERNS:
-        for m in re.finditer(pattern, content, re.IGNORECASE):
-            line_num = content[:m.start()].count('\n') + 1
-            backref_matches.append({
-                'line': line_num,
-                'pattern': label,
-                'context': lines[line_num - 1].strip()[:100],
-            })
-
-    # Config header
-    has_config_header = '{communication_language}' in content or '{document_output_language}' in content
-
-    # Progression condition
-    prog_keywords = ['progress', 'advance', 'move to', 'next stage',
-                     'when complete', 'proceed to', 'transition', 'completion criteria']
-    has_progression = any(kw in content.lower() for kw in prog_keywords)
-
-    result = {
-        'file': rel_path,
-        'line_count': line_count,
-        'token_estimate': token_estimate,
-        'sections': sections,
-        'table_count': table_count,
-        'table_lines': table_lines,
-        'fenced_block_count': block_count,
-        'fenced_block_lines': block_lines,
-        'waste_patterns': waste_matches,
-        'back_references': backref_matches,
-        'has_config_header': has_config_header,
-        'has_progression': has_progression,
+                blocks += 1
+    return blocks
+
+
+def grep(content: str, lines: list[str], patterns, ignore_case: bool = False) -> list[dict]:
+    flags = re.IGNORECASE if ignore_case else 0
+    hits = []
+    for entry in patterns:
+        pattern, *rest = entry
+        if len(rest) == 2:
+            category, label = rest
+        else:
+            category, label = None, rest[0]
+        for m in re.finditer(pattern, content, flags):
+            ln = content[: m.start()].count("\n") + 1
+            hit = {"line": ln, "pattern": label, "context": lines[ln - 1].strip()[:100]}
+            if category:
+                hit["category"] = category
+            hits.append(hit)
+    return hits
+
+
+def scan_file(filepath: Path, rel_path: str) -> dict:
+    content = filepath.read_text(encoding="utf-8")
+    lines = content.split("\n")
+    meta, body = split_frontmatter(content)
+    tokens, method = count_tokens(content)
+
+    sections = [
+        {"level": len(m.group(1)), "title": m.group(2).strip()}
+        for m in (re.match(r"^(#{2,4})\s+(.+)$", ln) for ln in lines)
+        if m
+    ]
+
+    table_count, table_rows = count_tables(content)
+    allcaps = len(ALLCAPS_PATTERN.findall(content))
+
+    data = {
+        "file": rel_path,
+        "tokens": tokens,
+        "token_method": method,
+        "sections": sections,
+        "table_count": table_count,
+        "table_rows": table_rows,
+        "fenced_block_count": count_fenced(content),
+        "allcaps_directive_count": allcaps,
+        "numbered_prefix_filename": bool(NUMBERED_PREFIX.match(filepath.name)),
+        "waste_patterns": grep(content, lines, WASTE_PATTERNS),
+        "back_references": grep(content, lines, BACKREF_PATTERNS, ignore_case=True),
     }
 
-    return result
+    if meta:
+        desc = meta.get("description", "")
+        data["frontmatter"] = {
+            "name": meta.get("name", ""),
+            "description": desc,
+            "description_chars": len(desc),
+            "description_has_angle_brackets": "<" in desc or ">" in desc,
+            "keys": sorted(meta.keys()),
+        }
+    return data
 
 
-def scan_prompt_metrics(skill_path: Path) -> dict:
-    """Extract metrics from all prompt-relevant files."""
+def scan(skill_path: Path) -> dict:
     files_data = []
 
-    # SKILL.md
-    skill_md = skill_path / 'SKILL.md'
+    skill_md = skill_path / "SKILL.md"
     if skill_md.exists():
-        data = scan_file_patterns(skill_md, 'SKILL.md')
-        content = skill_md.read_text(encoding='utf-8')
-        data['overview_lines'] = extract_overview_size(content)
-        data['is_skill_md'] = True
-        files_data.append(data)
+        d = scan_file(skill_md, "SKILL.md")
+        d["is_skill_md"] = True
+        files_data.append(d)
 
-    # Prompt files at skill root (non-SKILL.md .md files)
     for f in sorted(skill_path.iterdir()):
-        if f.is_file() and f.suffix == '.md' and f.name != 'SKILL.md':
-            data = scan_file_patterns(f, f.name)
-            data['is_skill_md'] = False
-            files_data.append(data)
-
-    # References (just sizes, for progressive disclosure assessment)
-    references_dir = skill_path / 'references'
-    reference_sizes = {}
-    if references_dir.exists():
-        for f in sorted(references_dir.iterdir()):
-            if f.is_file() and f.suffix in ('.md', '.json', '.yaml', '.yml'):
-                content = f.read_text(encoding='utf-8')
-                reference_sizes[f.name] = {
-                    'lines': len(content.split('\n')),
-                    'tokens': len(content) // 4,
+        if f.is_file() and f.suffix == ".md" and f.name != "SKILL.md":
+            d = scan_file(f, f.name)
+            d["is_skill_md"] = False
+            files_data.append(d)
+
+    references = {}
+    ref_dir = skill_path / "references"
+    if ref_dir.exists():
+        for f in sorted(ref_dir.iterdir()):
+            if f.is_file() and f.suffix in (".md", ".json", ".yaml", ".yml"):
+                tokens, method = count_tokens(f.read_text(encoding="utf-8"))
+                references[f.name] = {
+                    "tokens": tokens,
+                    "token_method": method,
+                    "numbered_prefix_filename": bool(NUMBERED_PREFIX.match(f.name)),
                 }
 
-    # Aggregate stats
-    total_waste = sum(len(f['waste_patterns']) for f in files_data)
-    total_backrefs = sum(len(f['back_references']) for f in files_data)
-    total_tokens = sum(f['token_estimate'] for f in files_data)
-    prompts_with_config = sum(1 for f in files_data if not f.get('is_skill_md') and f['has_config_header'])
-    prompts_with_progression = sum(1 for f in files_data if not f.get('is_skill_md') and f['has_progression'])
-    total_prompts = sum(1 for f in files_data if not f.get('is_skill_md'))
-
-    skill_md_data = next((f for f in files_data if f.get('is_skill_md')), None)
+    skill_md_data = next((f for f in files_data if f.get("is_skill_md")), None)
 
     return {
-        'scanner': 'prompt-craft-prepass',
-        'script': 'prepass-prompt-metrics.py',
-        'version': '1.0.0',
-        'skill_path': str(skill_path),
-        'timestamp': datetime.now(timezone.utc).isoformat(),
-        'status': 'info',
-        'skill_md_summary': {
-            'line_count': skill_md_data['line_count'] if skill_md_data else 0,
-            'token_estimate': skill_md_data['token_estimate'] if skill_md_data else 0,
-            'overview_lines': skill_md_data.get('overview_lines', 0) if skill_md_data else 0,
-            'table_count': skill_md_data['table_count'] if skill_md_data else 0,
-            'table_lines': skill_md_data['table_lines'] if skill_md_data else 0,
-            'fenced_block_count': skill_md_data['fenced_block_count'] if skill_md_data else 0,
-            'fenced_block_lines': skill_md_data['fenced_block_lines'] if skill_md_data else 0,
-            'section_count': len(skill_md_data['sections']) if skill_md_data else 0,
+        "scanner": "prompt-metrics-prepass",
+        "script": "prepass-prompt-metrics.py",
+        "version": "2.0.0",
+        "skill_path": str(skill_path),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "budgets": {
+            "skill_md_tokens": [1500, 2500],
+            "multi_branch_reference_tokens": 4500,
+            "single_purpose_reference_tokens": 9000,
         },
-        'prompt_health': {
-            'total_prompts': total_prompts,
-            'prompts_with_config_header': prompts_with_config,
-            'prompts_with_progression': prompts_with_progression,
+        "skill_md": {
+            "tokens": skill_md_data["tokens"] if skill_md_data else 0,
+            "token_method": skill_md_data["token_method"] if skill_md_data else "fallback",
+            "section_count": len(skill_md_data["sections"]) if skill_md_data else 0,
+            "frontmatter": skill_md_data.get("frontmatter") if skill_md_data else None,
         },
-        'aggregate': {
-            'total_files_scanned': len(files_data),
-            'total_token_estimate': total_tokens,
-            'total_waste_patterns': total_waste,
-            'total_back_references': total_backrefs,
+        "aggregate": {
+            "total_files_scanned": len(files_data),
+            "total_tokens": sum(f["tokens"] for f in files_data),
+            "total_waste_patterns": sum(len(f["waste_patterns"]) for f in files_data),
+            "total_back_references": sum(len(f["back_references"]) for f in files_data),
+            "files_with_numbered_prefix": sum(
+                1 for f in files_data if f["numbered_prefix_filename"]
+            ) + sum(1 for r in references.values() if r["numbered_prefix_filename"]),
         },
-        'reference_sizes': reference_sizes,
-        'files': files_data,
+        "reference_sizes": references,
+        "files": files_data,
     }
 
 
-def main() -> int:
-    parser = argparse.ArgumentParser(
-        description='Extract prompt craft metrics for LLM scanner pre-pass',
-    )
-    parser.add_argument(
-        'skill_path',
-        type=Path,
-        help='Path to the skill directory to scan',
-    )
-    parser.add_argument(
-        '--output', '-o',
-        type=Path,
-        help='Write JSON output to file instead of stdout',
-    )
-    args = parser.parse_args()
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Token-based prompt metrics for the Analyze scanners")
+    p.add_argument("skill_path", type=Path, help="path to the skill directory to scan")
+    p.add_argument("--output", "-o", type=Path, help="write JSON to a file instead of stdout")
+    args = p.parse_args(argv)
 
     if not args.skill_path.is_dir():
-        print(f"Error: {args.skill_path} is not a directory", file=sys.stderr)
+        print(f"error: {args.skill_path} is not a directory", file=sys.stderr)
         return 2
 
-    result = scan_prompt_metrics(args.skill_path)
-    output = json.dumps(result, indent=2)
-
+    output = json.dumps(scan(args.skill_path), indent=2)
     if args.output:
         args.output.parent.mkdir(parents=True, exist_ok=True)
         args.output.write_text(output)
-        print(f"Results written to {args.output}", file=sys.stderr)
+        print(f"results written to {args.output}", file=sys.stderr)
     else:
         print(output)
-
     return 0
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     sys.exit(main())

package/lib/bmad-cache/bmb/skills/bmad-workflow-builder/scripts/quick_validate.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.9"
+# ///
+"""quick_validate — structural lint for a skill's SKILL.md frontmatter.
+
+Checks the few things a structural error makes obvious: the frontmatter parses,
+it carries only allowed keys, the name is hyphen-case and within length, and the
+description is present, within bounds, and free of angle brackets (which break
+the router). The allowed-key set is configurable, never baked to one provider:
+pass --allow-key to extend it or --allow-keys to replace it.
+
+Exit code is 0 when every check passes and 1 when any check fails, so a build or
+CI step can gate on it. Findings print as one JSON object on stdout.
+
+Usage:
+  quick_validate.py <skill-dir-or-SKILL.md>
+  quick_validate.py <path> --allow-key license --allow-key version
+  quick_validate.py <path> --allow-keys name,description
+  quick_validate.py <path> --max-name 64 --max-desc 1024
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+DEFAULT_ALLOWED_KEYS = ["name", "description"]
+HYPHEN_CASE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+def split_frontmatter(content: str):
+    """Return (ok, frontmatter dict, error). ok is False when there is no parseable block."""
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return False, {}, "no frontmatter block (file does not open with ---)"
+    end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
+    if end is None:
+        return False, {}, "frontmatter block is not terminated with a closing ---"
+    meta: dict[str, str] = {}
+    for line in lines[1:end]:
+        if not line.strip():
+            continue
+        if ":" not in line:
+            return False, {}, f"frontmatter line is not key: value -> {line.strip()!r}"
+        k, v = line.split(":", 1)
+        meta[k.strip()] = v.strip()
+    return True, meta, ""
+
+
+def validate(content: str, allowed_keys, max_name: int, max_desc: int) -> list[dict]:
+    errors: list[dict] = []
+
+    ok, meta, parse_error = split_frontmatter(content)
+    if not ok:
+        return [{"check": "frontmatter", "message": parse_error}]
+
+    extra = [k for k in meta if k not in allowed_keys]
+    if extra:
+        errors.append({
+            "check": "allowed-keys",
+            "message": f"unexpected frontmatter keys: {', '.join(sorted(extra))}; allowed: {', '.join(allowed_keys)}",
+        })
+
+    name = meta.get("name", "")
+    if not name:
+        errors.append({"check": "name", "message": "name is missing or empty"})
+    else:
+        if not HYPHEN_CASE.match(name):
+            errors.append({"check": "name", "message": f"name {name!r} is not hyphen-case (lowercase, digits, single hyphens)"})
+        if len(name) > max_name:
+            errors.append({"check": "name", "message": f"name is {len(name)} chars, over the {max_name} limit"})
+
+    desc = meta.get("description", "")
+    if not desc:
+        errors.append({"check": "description", "message": "description is missing or empty"})
+    else:
+        if len(desc) > max_desc:
+            errors.append({"check": "description", "message": f"description is {len(desc)} chars, over the {max_desc} limit"})
+        if "<" in desc or ">" in desc:
+            errors.append({"check": "description", "message": "description contains angle brackets, which break router matching"})
+
+    return errors
+
+
+def resolve_skill_md(path: Path) -> Path:
+    return path / "SKILL.md" if path.is_dir() else path
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Structural lint for a skill's SKILL.md frontmatter")
+    p.add_argument("path", type=Path, help="skill directory or a SKILL.md file")
+    p.add_argument("--allow-key", action="append", default=[], help="add one key to the allowed set (repeatable)")
+    p.add_argument("--allow-keys", help="comma-separated set that REPLACES the default allowed keys")
+    p.add_argument("--max-name", type=int, default=64, help="max name length (default 64)")
+    p.add_argument("--max-desc", type=int, default=1024, help="max description length (default 1024)")
+    args = p.parse_args(argv)
+
+    skill_md = resolve_skill_md(args.path)
+    if not skill_md.is_file():
+        print(json.dumps({"ok": False, "errors": [{"check": "path", "message": f"{skill_md} not found"}]}))
+        return 1
+
+    if args.allow_keys:
+        allowed = [k.strip() for k in args.allow_keys.split(",") if k.strip()]
+    else:
+        allowed = list(DEFAULT_ALLOWED_KEYS) + list(args.allow_key)
+
+    errors = validate(skill_md.read_text(encoding="utf-8"), allowed, args.max_name, args.max_desc)
+    print(json.dumps({"ok": not errors, "file": str(skill_md), "errors": errors}))
+    return 0 if not errors else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())