novahiz 0.1.0

package/skills/write-a-skill/scripts/skill_description_validator.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""skill_description_validator.py — Validate a skill's description against Matt Pocock's rules.
+
+Stdlib-only. Parses YAML frontmatter of a SKILL.md and checks the `description`
+field against the criteria from Matt Pocock's write-a-skill:
+
+  1. Description present (non-empty after `description:` key)
+  2. Length <= 1024 characters
+  3. Written in third person (no first-person pronouns I/me/my; no second-person you)
+  4. Has explicit trigger phrase: "Use when ..." (or similar trigger pattern)
+  5. First sentence describes what the skill does (heuristic: at least one verb)
+
+Outputs pass/fail per check + overall verdict.
+
+Deterministic logic. No LLM calls. Stdlib only.
+
+Usage:
+    python skill_description_validator.py                       # uses embedded sample
+    python skill_description_validator.py path/to/SKILL.md
+    python skill_description_validator.py path/to/SKILL.md --output json
+"""
+
+import argparse
+import json
+import re
+import sys
+from typing import Any, Dict, List, Optional
+
+
+# Embedded sample: a SKILL.md description that PASSES all checks
+SAMPLE_DESCRIPTION = (
+    "Extract text and tables from PDF files, fill forms, merge documents. "
+    "Use when working with PDF files or when user mentions PDFs, forms, or document extraction."
+)
+
+# Embedded sample: SKILL.md content (just the frontmatter + body shell)
+SAMPLE_SKILL_MD = f"""---
+name: pdf-tools
+description: {SAMPLE_DESCRIPTION}
+---
+
+# PDF Tools
+
+## Quick start
+...
+"""
+
+
+# First-person pronouns + second-person pronouns to flag
+FIRST_PERSON = {"i", "me", "my", "myself", "we", "us", "our", "ours", "ourselves"}
+SECOND_PERSON = {"you", "your", "yours", "yourself"}
+
+# Trigger phrases that count as explicit "use when" triggers
+# Per Matt Pocock's rule: descriptions need an explicit trigger so agents know when to invoke.
+# Natural English variants are all accepted: "Use when/before/during/after/for/while ..." etc.
+TRIGGER_PATTERNS = [
+    re.compile(r"\buse\s+when\b", re.IGNORECASE),
+    re.compile(r"\buse\s+for\b", re.IGNORECASE),
+    re.compile(r"\buse\s+before\b", re.IGNORECASE),
+    re.compile(r"\buse\s+during\b", re.IGNORECASE),
+    re.compile(r"\buse\s+after\b", re.IGNORECASE),
+    re.compile(r"\buse\s+while\b", re.IGNORECASE),
+    re.compile(r"\binvoke\s+when\b", re.IGNORECASE),
+    re.compile(r"\binvoke\s+before\b", re.IGNORECASE),
+    re.compile(r"\binvoke\s+after\b", re.IGNORECASE),
+    re.compile(r"\btrigger\s+when\b", re.IGNORECASE),
+    re.compile(r"\bapply\s+when\b", re.IGNORECASE),
+    re.compile(r"\brun\s+when\b", re.IGNORECASE),
+    re.compile(r"\brun\s+before\b", re.IGNORECASE),
+]
+
+
+def extract_frontmatter(text: str) -> Dict[str, str]:
+    """Extract YAML frontmatter as a flat dict. Stdlib-only — minimal YAML parser
+    sufficient for SKILL.md frontmatter (key: value pairs, no nesting)."""
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    block = text[3:end].strip()
+    out: Dict[str, str] = {}
+    current_key: Optional[str] = None
+    buffer: List[str] = []
+    for line in block.splitlines():
+        if ":" in line and not line.startswith(" ") and not line.startswith("\t"):
+            # Flush previous
+            if current_key:
+                out[current_key] = " ".join(buffer).strip()
+                buffer = []
+            key, _, val = line.partition(":")
+            current_key = key.strip()
+            val = val.strip()
+            if val and val != ">":
+                buffer.append(val)
+        elif current_key and line.strip():
+            buffer.append(line.strip())
+    if current_key:
+        out[current_key] = " ".join(buffer).strip()
+    return out
+
+
+def check_present(desc: str) -> Dict[str, Any]:
+    return {
+        "rule": "description_present",
+        "pass": bool(desc and desc.strip()),
+        "detail": f"Length: {len(desc)} chars" if desc else "Missing or empty description field",
+    }
+
+
+def check_length(desc: str, max_chars: int = 1024) -> Dict[str, Any]:
+    n = len(desc)
+    return {
+        "rule": "description_length",
+        "pass": n <= max_chars,
+        "detail": f"{n} chars (limit {max_chars})",
+    }
+
+
+def check_third_person(desc: str) -> Dict[str, Any]:
+    words = re.findall(r"\b[a-zA-Z]+\b", desc.lower())
+    flagged_first = [w for w in words if w in FIRST_PERSON]
+    flagged_second = [w for w in words if w in SECOND_PERSON]
+    flagged = flagged_first + flagged_second
+    return {
+        "rule": "third_person",
+        "pass": len(flagged) == 0,
+        "detail": f"Found pronouns: {sorted(set(flagged))}" if flagged else "No 1st/2nd-person pronouns",
+    }
+
+
+def check_trigger(desc: str) -> Dict[str, Any]:
+    for pattern in TRIGGER_PATTERNS:
+        if pattern.search(desc):
+            return {
+                "rule": "explicit_trigger",
+                "pass": True,
+                "detail": f"Found trigger phrase matching: {pattern.pattern}",
+            }
+    return {
+        "rule": "explicit_trigger",
+        "pass": False,
+        "detail": 'No explicit trigger ("Use when..." or similar). Agent will struggle to know when to invoke.',
+    }
+
+
+# Action verb vocabulary used to detect "first sentence describes what the skill does"
+# This is content data, not an assumption — these are the verbs we look for in skill descriptions.
+ACTION_VERB_VOCABULARY = (
+    "extract", "fill", "merge", "create", "build", "generate", "analyze", "analyse",
+    "validate", "check", "run", "format", "parse", "render", "review", "audit", "scan",
+    "compute", "score", "track", "report", "transform", "convert", "deploy", "test",
+    "monitor", "log", "search", "find", "fetch", "store", "send", "read", "write",
+    "refresh", "remove", "process", "manage", "apply", "implement", "interrogate",
+    "orchestrate", "classify",
+)
+ACTION_VERB_RE = re.compile(
+    r"\b(" + "|".join(ACTION_VERB_VOCABULARY) + r")s?\b",
+    re.IGNORECASE,
+)
+
+
+def check_first_sentence_has_verb(desc: str) -> Dict[str, Any]:
+    # Heuristic: split on first period; first sentence should have an action verb
+    parts = re.split(r"\.\s+", desc, maxsplit=1)
+    first = parts[0] if parts else desc
+    verbs = ACTION_VERB_RE.findall(first)
+    return {
+        "rule": "first_sentence_has_action_verb",
+        "pass": len(verbs) >= 1,
+        "detail": f"Verb(s) found in first sentence: {verbs}" if verbs else "No action verb detected in first sentence",
+    }
+
+
+def analyze(skill_md_text: str) -> Dict[str, Any]:
+    fm = extract_frontmatter(skill_md_text)
+    desc = fm.get("description", "")
+    checks = [
+        check_present(desc),
+        check_length(desc),
+        check_third_person(desc),
+        check_trigger(desc),
+        check_first_sentence_has_verb(desc),
+    ]
+    passed = sum(1 for c in checks if c["pass"])
+    overall = "PASS" if passed == len(checks) else ("WARN" if passed >= 3 else "FAIL")
+    return {
+        "description": desc,
+        "checks": checks,
+        "passed": passed,
+        "total": len(checks),
+        "overall": overall,
+    }
+
+
+def render_text(r: Dict[str, Any], source: str) -> str:
+    lines = []
+    lines.append("=" * 72)
+    lines.append("SKILL DESCRIPTION VALIDATOR")
+    lines.append(f"Source: {source}")
+    lines.append("=" * 72)
+    lines.append("")
+    lines.append(f"Description ({len(r['description'])} chars):")
+    lines.append(f"  {r['description'][:200]}{'...' if len(r['description']) > 200 else ''}")
+    lines.append("")
+    lines.append("-" * 72)
+    lines.append(f"Checks: {r['passed']} / {r['total']} passed")
+    lines.append("")
+    for c in r["checks"]:
+        marker = "PASS" if c["pass"] else "FAIL"
+        lines.append(f"  [{marker}] {c['rule']:30s}  {c['detail']}")
+    lines.append("")
+    lines.append("-" * 72)
+    lines.append(f"Verdict: {r['overall']}")
+    lines.append("")
+    lines.append("Rules (per Matt Pocock's write-a-skill):")
+    lines.append("  - Max 1024 chars")
+    lines.append("  - Third person (no I/we/you)")
+    lines.append("  - First sentence: what it does (action verb)")
+    lines.append("  - Second sentence: 'Use when [specific triggers]'")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate a SKILL.md description per Matt Pocock's rules.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument("path", nargs="?", help="Path to SKILL.md (uses embedded sample if omitted)")
+    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
+    args = parser.parse_args()
+
+    if args.path:
+        try:
+            with open(args.path, "r", encoding="utf-8") as f:
+                text = f.read()
+            source = args.path
+        except (IOError, OSError) as e:
+            print(f"error: could not read {args.path}: {e}", file=sys.stderr)
+            return 1
+    else:
+        text = SAMPLE_SKILL_MD
+        source = "<embedded sample: pdf-tools description (PASS expected)>"
+
+    result = analyze(text)
+    if args.output == "json":
+        print(json.dumps({"source": source, **result}, indent=2))
+    else:
+        print(render_text(result, source))
+    return 0 if result["overall"] == "PASS" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/write-a-skill/scripts/skill_review_checklist_runner.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""skill_review_checklist_runner.py — Run Matt Pocock's 6-item review checklist programmatically.
+
+Stdlib-only. Combines the description-validator + structure-validator into a single
+report that mirrors Matt Pocock's review checklist from write-a-skill:
+
+  1. [ ] Description includes triggers ("Use when...")
+  2. [ ] SKILL.md under 100 lines
+  3. [ ] No time-sensitive info (heuristic: no year mentions / "as of" claims / version-specific dates)
+  4. [ ] Consistent terminology (heuristic: no obvious synonym pairs in same doc — light check)
+  5. [ ] Concrete examples included (>=1 code block)
+  6. [ ] References one level deep
+
+This is the canonical pre-commit check for any new skill in this repo.
+
+Deterministic logic. No LLM calls. Stdlib only.
+
+Usage:
+    python skill_review_checklist_runner.py                       # uses embedded sample (this skill's own folder)
+    python skill_review_checklist_runner.py path/to/skill-folder/
+    python skill_review_checklist_runner.py path/to/skill-folder/ --output json
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from typing import Any, Dict, List
+
+
+# Phrases that suggest time-sensitive content
+TIME_SENSITIVE_PATTERNS = [
+    re.compile(r"\bas\s+of\s+\d{4}\b", re.IGNORECASE),
+    re.compile(r"\bin\s+(20\d{2})\b", re.IGNORECASE),
+    re.compile(r"\b(?:january|february|march|april|may|june|july|august|september|october|november|december)\s+\d{4}\b", re.IGNORECASE),
+    re.compile(r"\b(?:released|launched|published|updated)\s+(?:on|in)\b", re.IGNORECASE),
+]
+
+
+def find_skill_md(folder: str) -> str:
+    candidate = os.path.join(folder, "SKILL.md")
+    return candidate if os.path.isfile(candidate) else ""
+
+
+def extract_frontmatter_description(text: str) -> str:
+    """Extract description from YAML frontmatter (single key)."""
+    if not text.startswith("---"):
+        return ""
+    end = text.find("\n---", 3)
+    if end == -1:
+        return ""
+    block = text[3:end]
+    # Match "description: ..." potentially spanning multiple lines (>- folded)
+    match = re.search(r"^description:\s*(.*)$(?:\n[ ]+(.*))*", block, re.MULTILINE)
+    if not match:
+        return ""
+    val = match.group(1).strip()
+    if val == ">" or val == "|":
+        # Folded scalar — collect indented continuation lines
+        lines_iter = iter(block.splitlines())
+        for line in lines_iter:
+            if line.strip().startswith("description:"):
+                break
+        collected = []
+        for line in lines_iter:
+            if line.startswith(" ") or line.startswith("\t"):
+                collected.append(line.strip())
+            else:
+                break
+        val = " ".join(collected)
+    return val
+
+
+# Trigger phrases that count as explicit "use when ..." triggers in a description.
+# Per Matt Pocock's rule: explicit trigger phrase. Natural English variants all accepted.
+TRIGGER_PATTERNS = [
+    re.compile(r"\buse\s+when\b", re.IGNORECASE),
+    re.compile(r"\buse\s+for\b", re.IGNORECASE),
+    re.compile(r"\buse\s+before\b", re.IGNORECASE),
+    re.compile(r"\buse\s+during\b", re.IGNORECASE),
+    re.compile(r"\buse\s+after\b", re.IGNORECASE),
+    re.compile(r"\buse\s+while\b", re.IGNORECASE),
+    re.compile(r"\binvoke\s+when\b", re.IGNORECASE),
+    re.compile(r"\binvoke\s+before\b", re.IGNORECASE),
+    re.compile(r"\binvoke\s+after\b", re.IGNORECASE),
+    re.compile(r"\btrigger\s+when\b", re.IGNORECASE),
+    re.compile(r"\bapply\s+when\b", re.IGNORECASE),
+    re.compile(r"\brun\s+when\b", re.IGNORECASE),
+    re.compile(r"\brun\s+before\b", re.IGNORECASE),
+]
+
+
+def check_description_has_trigger(text: str) -> Dict[str, Any]:
+    desc = extract_frontmatter_description(text)
+    has_trigger = any(p.search(desc) for p in TRIGGER_PATTERNS)
+    return {
+        "rule": "1. Description includes triggers",
+        "pass": has_trigger,
+        "detail": ("Found explicit trigger phrase" if has_trigger
+                   else "Missing explicit trigger phrase (Use when/before/after/for ...)"),
+    }
+
+
+def check_skill_md_length(filepath: str, max_lines: int = 100) -> Dict[str, Any]:
+    with open(filepath, "r", encoding="utf-8") as f:
+        lines = sum(1 for _ in f)
+    return {
+        "rule": f"2. SKILL.md under {max_lines} lines",
+        "pass": lines <= max_lines,
+        "detail": f"{lines} lines",
+    }
+
+
+def check_no_time_sensitive(text: str) -> Dict[str, Any]:
+    flagged = []
+    for pattern in TIME_SENSITIVE_PATTERNS:
+        for m in pattern.finditer(text):
+            flagged.append(m.group(0))
+    # Limit
+    flagged = list(dict.fromkeys(flagged))[:5]
+    return {
+        "rule": "3. No time-sensitive info",
+        "pass": len(flagged) == 0,
+        "detail": ("No date/year/version-bound claims detected" if not flagged
+                   else f"Flagged phrases: {flagged}"),
+    }
+
+
+def check_consistent_terminology(text: str) -> Dict[str, Any]:
+    """Light check for common synonym mismatches in the same doc."""
+    synonyms = [
+        ("agent", "bot"),
+        ("skill", "tool"),
+        ("user", "developer"),
+    ]
+    findings = []
+    text_lower = text.lower()
+    for a, b in synonyms:
+        if re.search(rf"\b{re.escape(a)}\b", text_lower) and re.search(rf"\b{re.escape(b)}\b", text_lower):
+            findings.append(f"Both '{a}' and '{b}' used")
+    return {
+        "rule": "4. Consistent terminology",
+        "pass": len(findings) == 0,
+        "detail": ("No obvious synonym pairs detected" if not findings
+                   else "; ".join(findings)),
+    }
+
+
+def check_concrete_examples(text: str) -> Dict[str, Any]:
+    code_blocks = re.findall(r"```", text)
+    has_examples = len(code_blocks) >= 2  # opening + closing = 1 block
+    return {
+        "rule": "5. Concrete examples included",
+        "pass": has_examples,
+        "detail": f"{len(code_blocks) // 2} code block(s) found",
+    }
+
+
+def _find_nested_md(refs_subdir: str) -> List[str]:
+    """Return .md files nested deeper than refs_subdir."""
+    nested: List[str] = []
+    if not os.path.isdir(refs_subdir):
+        return nested
+    for root, _, files in os.walk(refs_subdir):
+        if root == refs_subdir:
+            continue
+        nested.extend(os.path.join(root, f) for f in files if f.endswith(".md"))
+    return nested
+
+
+def check_references_one_level_deep(folder: str) -> Dict[str, Any]:
+    deeper = _find_nested_md(os.path.join(folder, "references"))
+    return {
+        "rule": "6. References one level deep",
+        "pass": len(deeper) == 0,
+        "detail": ("All references at one level" if not deeper
+                   else f"Found nested ref files: {deeper}"),
+    }
+
+
+def analyze(folder: str) -> Dict[str, Any]:
+    skill_md = find_skill_md(folder)
+    if not skill_md:
+        detail = f"SKILL.md not found at {folder}"
+        missing_check = {"rule": "skill_md_present", "pass": False, "detail": detail}
+        return {
+            "folder": folder,
+            "checks": [missing_check],
+            "passed": 0,
+            "total": 1,
+            "overall": "FAIL",
+        }
+    with open(skill_md, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    checks = [
+        check_description_has_trigger(text),
+        check_skill_md_length(skill_md, max_lines=100),
+        check_no_time_sensitive(text),
+        check_consistent_terminology(text),
+        check_concrete_examples(text),
+        check_references_one_level_deep(folder),
+    ]
+    passed = sum(1 for c in checks if c["pass"])
+    total = len(checks)
+    overall = "PASS" if passed == total else ("WARN" if passed >= total - 1 else "FAIL")
+
+    return {
+        "folder": folder,
+        "skill_md": skill_md,
+        "checks": checks,
+        "passed": passed,
+        "total": total,
+        "overall": overall,
+    }
+
+
+def render_text(r: Dict[str, Any]) -> str:
+    lines = []
+    lines.append("=" * 72)
+    lines.append("SKILL REVIEW CHECKLIST RUNNER (per Matt Pocock's write-a-skill)")
+    lines.append(f"Folder: {r['folder']}")
+    lines.append("=" * 72)
+    lines.append("")
+    lines.append(f"Checks: {r['passed']} / {r['total']} passed")
+    lines.append("")
+    for c in r["checks"]:
+        marker = "[x]" if c["pass"] else "[ ]"
+        lines.append(f"  {marker} {c['rule']}")
+        lines.append(f"        {c['detail']}")
+    lines.append("")
+    lines.append("-" * 72)
+    lines.append(f"Verdict: {r['overall']}")
+    lines.append("")
+    lines.append("Reference: Matt Pocock's 6-item review checklist from write-a-skill (MIT).")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Run Matt Pocock's 6-item review checklist on a skill folder.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument("path", nargs="?", help="Path to skill folder (uses embedded sample if omitted)")
+    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
+    args = parser.parse_args()
+
+    if args.path:
+        folder = args.path
+    else:
+        folder = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+    if not os.path.isdir(folder):
+        print(f"error: not a directory: {folder}", file=sys.stderr)
+        return 1
+
+    result = analyze(folder)
+    if args.output == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        print(render_text(result))
+    return 0 if result["overall"] == "PASS" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())