agentskill-toolkit 0.1.0__py3-none-any.whl

agentskill_kit/lint.py

@@ -0,0 +1,201 @@
+"""Structural checks for SKILL.md files. Works offline and needs no model."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .skillfile import Skill, SkillError, load_skill
+
+NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+KNOWN_KEYS = {"name", "description", "license", "compatibility", "metadata", "allowed-tools"}
+LEGACY_KEYS = {"version", "author", "tags"}
+RESERVED_WORDS = ("anthropic", "claude")
+TRIGGER_RE = re.compile(
+    r"\b(use when|use this|use for|use it|when the user|when you|whenever|if the user|"
+    r"trigger|invoke|asks? (?:to|for)|needs? to|when (?:asked|working|reviewing|writing|"
+    r"creating|debugging|analy[sz]ing|you))\b", re.I)
+FIRST_PERSON_RE = re.compile(r"^\s*(i|i'll|i can|i will|my|we|you can|you will)\b", re.I)
+PLACEHOLDER_RE = re.compile(
+    r"\b(?:TODO|FIXME|TBD):|[\[<](?:TODO|FIXME|TBD)[\]>]|\blorem ipsum\b|<your[ -][^>]*>|\[insert [^\]]*\]"
+    r"|\bReplace this (?:line|step)\b|\bDescribe what this skill does\b", re.I)
+REF_RE = re.compile(r"(?<![\w/.-])((?:scripts|references|assets|tests|evals)/[\w./-]+\.[A-Za-z0-9]+)")
+LINK_RE = re.compile(r"\]\((?!https?:|mailto:|#)([^)\s#]+)")
+
+SEVERITY_ORDER = {"error": 0, "warning": 1, "info": 2}
+
+
+@dataclass
+class Issue:
+    code: str
+    severity: str
+    message: str
+    file: str = "SKILL.md"
+    line: int = 0
+    hint: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"code": self.code, "severity": self.severity, "message": self.message,
+                "file": self.file, "line": self.line, "hint": self.hint}
+
+
+@dataclass
+class LintResult:
+    skill: str
+    path: str
+    issues: List[Issue] = field(default_factory=list)
+
+    @property
+    def errors(self) -> List[Issue]:
+        return [i for i in self.issues if i.severity == "error"]
+
+    @property
+    def warnings(self) -> List[Issue]:
+        return [i for i in self.issues if i.severity == "warning"]
+
+    @property
+    def score(self) -> int:
+        return max(0, 100 - 25 * len(self.errors) - 6 * len(self.warnings))
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"skill": self.skill, "path": self.path, "score": self.score,
+                "errors": len(self.errors), "warnings": len(self.warnings),
+                "issues": [i.to_dict() for i in self.issues]}
+
+
+def _find_line(skill: Skill, key: str) -> int:
+    for idx, ln in enumerate(skill.fm_lines):
+        if ln.startswith(key + ":"):
+            return idx + 2
+    return 1
+
+
+def lint_skill(target: Any) -> LintResult:
+    """Lint a skill directory (or SKILL.md path)."""
+    try:
+        skill = load_skill(target)
+    except SkillError as exc:
+        return LintResult(skill=Path(str(target)).name, path=str(target),
+                          issues=[Issue("E001", "error", str(exc), file=str(target))])
+    return lint_loaded(skill)
+
+
+def lint_loaded(skill: Skill) -> LintResult:
+    res = LintResult(skill=skill.name, path=str(skill.path))
+    add = res.issues.append
+
+    if not skill.has_frontmatter:
+        add(Issue("E002", "error", "SKILL.md must start with a YAML frontmatter block between --- lines",
+                  line=1, hint="Add name and description at the top of the file."))
+        return res
+
+    for line_no, msg in skill.fm_errors:
+        add(Issue("E010", "error", "frontmatter: " + msg, line=line_no))
+    for idx, ln in enumerate(skill.fm_lines):
+        if "\t" in ln:
+            add(Issue("W010", "warning", "tab character in frontmatter; use spaces", line=idx + 2))
+
+    meta = skill.meta
+    name = meta.get("name")
+    if not name or not isinstance(name, str):
+        add(Issue("E003", "error", "missing required field: name", line=1))
+    else:
+        line = _find_line(skill, "name")
+        if len(name) > 64:
+            add(Issue("E004", "error", "name is %d characters; the limit is 64" % len(name), line=line))
+        if not NAME_RE.match(name):
+            add(Issue("E005", "error",
+                      "name must use lowercase letters, digits and single hyphens (got %r)" % name,
+                      line=line, hint="Example: log-analyzer"))
+        if name != skill.path.name:
+            add(Issue("E006", "error",
+                      "name %r does not match the directory name %r" % (name, skill.path.name),
+                      line=line, hint="Rename the directory or the name field so both agree."))
+        if any(w in name for w in RESERVED_WORDS):
+            add(Issue("W011", "warning", "name contains a reserved word (%s)" % "/".join(RESERVED_WORDS),
+                      line=line, hint="Some agents reject skill names that include these words."))
+
+    desc = meta.get("description")
+    dline = _find_line(skill, "description")
+    if not desc or not isinstance(desc, str):
+        add(Issue("E007", "error", "missing required field: description", line=1,
+                  hint="Describe what the skill does and when an agent should use it."))
+    else:
+        if len(desc) > 1024:
+            add(Issue("E008", "error", "description is %d characters; the limit is 1024" % len(desc), line=dline))
+        if re.search(r"</?[A-Za-z][^>]*>", desc):
+            add(Issue("E009", "error", "description must not contain XML or HTML tags", line=dline))
+        if PLACEHOLDER_RE.search(desc):
+            add(Issue("W007", "warning", "description still contains template text", line=dline))
+        if len(desc) < 40:
+            add(Issue("W001", "warning", "description is very short (%d characters)" % len(desc), line=dline,
+                      hint="Agents pick skills by description. Say what it does and when to use it."))
+        if not TRIGGER_RE.search(desc):
+            add(Issue("W002", "warning", "description does not say when to use the skill", line=dline,
+                      hint="Add a sentence such as 'Use when the user asks to ...'."))
+        if FIRST_PERSON_RE.match(desc):
+            add(Issue("W012", "warning", "description should be written in the third person", line=dline,
+                      hint="Write 'Analyzes logs ...' instead of 'I analyze logs ...'."))
+
+    comp = meta.get("compatibility")
+    if isinstance(comp, str) and len(comp) > 500:
+        add(Issue("E011", "error", "compatibility is %d characters; the limit is 500" % len(comp),
+                  line=_find_line(skill, "compatibility")))
+
+    if "metadata" in meta and not isinstance(meta["metadata"], dict):
+        add(Issue("E012", "error", "metadata must be a mapping of keys to values",
+                  line=_find_line(skill, "metadata")))
+
+    for key in meta:
+        if key in KNOWN_KEYS:
+            continue
+        if key in LEGACY_KEYS:
+            add(Issue("I002", "info", "top-level key %r is accepted but belongs under metadata" % key,
+                      line=_find_line(skill, key)))
+        else:
+            add(Issue("I003", "info", "unknown frontmatter key %r (ignored by most agents)" % key,
+                      line=_find_line(skill, key)))
+    if not meta.get("license"):
+        add(Issue("I001", "info", "no license field", line=1,
+                  hint="Add license: MIT (or similar) if you plan to share the skill."))
+
+    body = skill.body
+    nonblank = [ln for ln in body.splitlines() if ln.strip()]
+    if len(nonblank) < 3:
+        add(Issue("W003", "warning", "the instructions are empty or nearly empty", line=skill.body_line))
+    total_lines = len(body.splitlines())
+    if total_lines > 500:
+        add(Issue("W004", "warning", "body has %d lines; keep SKILL.md under 500" % total_lines,
+                  line=skill.body_line, hint="Move long reference material to references/*.md."))
+    if nonblank and not re.search(r"^#{1,3}\s+\S", body, re.M):
+        add(Issue("W005", "warning", "no markdown headings in the instructions", line=skill.body_line))
+    for m in PLACEHOLDER_RE.finditer(body):
+        line = skill.body_line + body.count("\n", 0, m.start())
+        add(Issue("W007", "warning", "placeholder text found: %r" % m.group(0), line=line))
+        break
+
+    seen = set()
+    for m in list(REF_RE.finditer(body)) + list(LINK_RE.finditer(body)):
+        ref = m.group(1).strip("`.,;:")
+        if ref in seen or not ref:
+            continue
+        seen.add(ref)
+        if not (skill.path / ref).exists():
+            line = skill.body_line + body.count("\n", 0, m.start())
+            add(Issue("W006", "warning", "referenced file does not exist: %s" % ref, line=line))
+
+    res.issues.sort(key=lambda i: (SEVERITY_ORDER.get(i.severity, 3), i.line, i.code))
+    return res
+
+
+def format_github(result: LintResult) -> List[str]:
+    out = []
+    for i in result.issues:
+        if i.severity == "info":
+            continue
+        level = "error" if i.severity == "error" else "warning"
+        path = Path(result.path) / i.file
+        out.append("::%s file=%s,line=%d::[%s] %s" % (level, path.as_posix(), max(1, i.line), i.code, i.message))
+    return out

agentskill_kit/mine.py

@@ -0,0 +1,291 @@
+"""Find repeated workflows in shell history and suggest skills.
+
+Everything runs locally. Commands are normalised (paths, numbers, quoted
+strings and hashes become placeholders) and secrets are masked before
+anything is shown or written.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Tuple
+
+from .scan import redact
+from .skillfile import dump_frontmatter, slugify
+
+TRIVIAL = {
+    "cd", "ls", "ll", "la", "dir", "pwd", "clear", "cls", "exit", "logout", "history", "echo", "man", "help",
+    "which", "where", "whoami", "date", "top", "htop", "vim", "vi", "nano", "code", "type", "cat", "less",
+    "more", "head", "tail", "mkdir", "touch", "source", "export", "set", "alias", "sleep", "true", "false",
+    "pushd", "popd", "tree", "open", "start", "tldr", "z", "j",
+}
+
+_PATHISH = re.compile(r"[\\/]")
+_NUM = re.compile(r"^\d+(?:[.:_-]\d+)*$")
+_HASH = re.compile(r"^[0-9a-f]{7,40}$")
+_FILE = re.compile(r"^[\w.-]+\.(?:py|js|ts|tsx|json|ya?ml|md|txt|csv|log|toml|sh|ini|cfg|xml|html|sql|zip|tar|gz)$", re.I)
+_URL = re.compile(r"^[a-z]+://", re.I)
+
+
+@dataclass
+class Candidate:
+    kind: str  # sequence | command
+    template: List[str]
+    count: int
+    examples: List[str]
+    score: float = 0.0
+
+    @property
+    def tools(self) -> List[str]:
+        seen: List[str] = []
+        for line in self.template:
+            tool = line.split()[0] if line.split() else ""
+            if tool and tool not in seen:
+                seen.append(tool)
+        return seen
+
+    @property
+    def name(self) -> str:
+        tools = self.tools
+        if self.kind == "command" and self.template:
+            toks = [t for t in self.template[0].split() if re.match(r"^[a-z][a-z0-9-]*$", t)][:2]
+            return slugify("-".join(toks) or "command")
+        if len(tools) == 1:
+            subs: List[str] = []
+            for line in self.template:
+                parts = line.split()
+                if len(parts) > 1 and re.match(r"^[a-z][a-z0-9-]*$", parts[1]) and parts[1] not in subs:
+                    subs.append(parts[1])
+            return slugify("-".join([tools[0]] + subs[:3]))
+        return slugify("-".join(tools[:3]) + "-workflow")
+
+
+# ---------------------------------------------------------------------------
+# Reading history
+# ---------------------------------------------------------------------------
+
+def default_history_files() -> List[Path]:
+    home = Path.home()
+    cands = [home / ".bash_history", home / ".zsh_history", home / ".local/share/fish/fish_history"]
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        cands.append(Path(appdata) / "Microsoft/Windows/PowerShell/PSReadLine/ConsoleHost_history.txt")
+    cands.append(home / ".local/share/powershell/PSReadLine/ConsoleHost_history.txt")
+    histfile = os.environ.get("HISTFILE")
+    if histfile:
+        cands.insert(0, Path(histfile).expanduser())
+    out, seen = [], set()
+    for c in cands:
+        if c.is_file() and str(c) not in seen:
+            out.append(c)
+            seen.add(str(c))
+    return out
+
+
+def parse_history(text: str, hint: str = "") -> List[str]:
+    """Parse bash, zsh, fish or PowerShell history text into a list of commands."""
+    cmds: List[str] = []
+    lines = text.splitlines()
+    is_fish = hint == "fish" or any(ln.startswith("- cmd: ") for ln in lines[:20])
+    if is_fish:
+        for ln in lines:
+            if ln.startswith("- cmd: "):
+                cmds.append(ln[7:].strip())
+        return cmds
+    buf = ""
+    for ln in lines:
+        if re.match(r"^#\d{9,}$", ln):  # bash timestamps
+            continue
+        m = re.match(r"^: \d+:\d+;(.*)$", ln)  # zsh extended history
+        if m:
+            ln = m.group(1)
+        if buf:
+            ln = buf + "\n" + ln
+            buf = ""
+        if ln.endswith("\\") or ln.endswith("`"):
+            buf = ln[:-1].rstrip()
+            continue
+        if ln.strip():
+            cmds.append(ln.strip())
+    if buf:
+        cmds.append(buf.strip())
+    return cmds
+
+
+def read_history(paths: Optional[Iterable[Path]] = None) -> List[str]:
+    files = list(paths) if paths else default_history_files()
+    cmds: List[str] = []
+    for p in files:
+        try:
+            text = Path(p).read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        hint = "fish" if "fish" in str(p).lower() else ""
+        cmds.extend(parse_history(text, hint))
+    return cmds
+
+
+# ---------------------------------------------------------------------------
+# Normalisation
+# ---------------------------------------------------------------------------
+
+def normalize(cmd: str) -> str:
+    c = re.sub(r'"[^"]*"|\'[^\']*\'', "<str>", cmd.strip())
+    c = redact(c)
+    out: List[str] = []
+    for i, tok in enumerate(c.split()):
+        if tok == "<str>" or tok.startswith("<redacted"):
+            out.append("<str>" if tok == "<str>" else tok)
+        elif i == 0:
+            out.append(tok)
+        elif _URL.match(tok):
+            out.append("<url>")
+        elif tok.startswith("-"):
+            out.append(tok)
+        elif i == 1 and re.match(r"^[a-z][a-z0-9:-]*$", tok):
+            out.append(tok)  # keep the subcommand (git commit, docker build)
+        elif _PATHISH.search(tok) or tok in (".", "..", "~"):
+            out.append("<path>")
+        elif _FILE.match(tok):
+            out.append("<file>")
+        elif _HASH.match(tok) and re.search(r"\d", tok):
+            out.append("<hash>")
+        elif _NUM.match(tok):
+            out.append("<n>")
+        else:
+            out.append(tok)
+    return " ".join(out)
+
+
+def _is_trivial(cmd: str) -> bool:
+    toks = cmd.split()
+    if not toks:
+        return True
+    base = Path(toks[0]).name.lower()
+    return base in TRIVIAL or toks[0].startswith("#")
+
+
+# ---------------------------------------------------------------------------
+# Mining
+# ---------------------------------------------------------------------------
+
+def find_candidates(commands: List[str], min_count: int = 3, max_len: int = 4, limit: int = 15) -> List[Candidate]:
+    pairs = [(c, normalize(c)) for c in commands if not _is_trivial(c)]
+    norms = [n for _, n in pairs]
+    originals = [redact(o) for o, _ in pairs]
+
+    seq_counts: Counter = Counter()
+    seq_positions: Dict[Tuple[str, ...], int] = {}
+    for length in range(2, max_len + 1):
+        for i in range(0, len(norms) - length + 1):
+            window = tuple(norms[i:i + length])
+            if len(set(window)) == 1:
+                continue
+            seq_counts[window] += 1
+            seq_positions[window] = i
+    seqs = {w: c for w, c in seq_counts.items() if c >= min_count}
+
+    maximal: Dict[Tuple[str, ...], int] = {}
+    for w, c in sorted(seqs.items(), key=lambda kv: -len(kv[0])):
+        covered = any(len(o) > len(w) and oc >= c and _contains(o, w) for o, oc in maximal.items())
+        if not covered:
+            maximal[w] = c
+
+    # A workflow repeated back to back shows up as several rotations of itself.
+    # Keep one candidate per set of commands: the most frequent, then the longest.
+    best_by_set: Dict[frozenset, Tuple[Tuple[str, ...], int]] = {}
+    for w, c in maximal.items():
+        key = frozenset(w)
+        cur = best_by_set.get(key)
+        if cur is None or (c, len(w)) > (cur[1], len(cur[0])):
+            best_by_set[key] = (w, c)
+
+    out: List[Candidate] = []
+    for w, c in best_by_set.values():
+        pos = seq_positions[w]
+        out.append(Candidate("sequence", list(w), c, originals[pos:pos + len(w)],
+                             score=c * (len(w) ** 1.5)))
+
+    cmd_counts = Counter(norms)
+    for n, c in cmd_counts.items():
+        if c >= max(min_count * 2, 4) and len(n.split()) >= 3:
+            if any(n in cand.template for cand in out):
+                continue
+            idx = max(i for i, x in enumerate(norms) if x == n)
+            out.append(Candidate("command", [n], c, [originals[idx]], score=c * 1.2))
+    out.sort(key=lambda cand: -cand.score)
+    return out[:limit]
+
+
+def _contains(big: Tuple[str, ...], small: Tuple[str, ...]) -> bool:
+    n = len(small)
+    return any(big[i:i + n] == small for i in range(len(big) - n + 1))
+
+
+# ---------------------------------------------------------------------------
+# Drafting
+# ---------------------------------------------------------------------------
+
+def placeholders(candidate: Candidate) -> List[str]:
+    found: List[str] = []
+    for line in candidate.template:
+        for ph in re.findall(r"<(?:str|path|file|url|n|hash|redacted)>", line):
+            if ph not in found:
+                found.append(ph)
+    return found
+
+
+_PLACEHOLDER_HELP = {
+    "<str>": "a quoted text value such as a message or name",
+    "<path>": "a file or directory path",
+    "<file>": "a file name",
+    "<url>": "a URL",
+    "<n>": "a number such as a version, port or count",
+    "<hash>": "a commit hash or other identifier",
+    "<redacted>": "a secret; read it from the environment, never inline it",
+}
+
+
+def draft_skill_files(candidate: Candidate, name: Optional[str] = None) -> Dict[str, str]:
+    """Write a deterministic SKILL.md for a mined workflow (no model needed)."""
+    name = slugify(name or candidate.name)
+    tools = ", ".join(candidate.tools[:4])
+    first = candidate.template[0]
+    plain = [re.sub(r"<[^>]*>", "...", t) for t in candidate.template[:3]]
+    steps = "; ".join(t if len(t) <= 50 else t[:47] + "..." for t in plain)
+    desc = ("Runs a recurring %s workflow: %s. Use when the user asks to repeat this sequence "
+            "of commands or to automate the same routine." % (tools, steps))
+    if len(desc) > 600:
+        desc = desc[:597] + "..."
+    fm = dump_frontmatter({
+        "name": name,
+        "description": desc,
+        "license": "MIT",
+        "metadata": {"version": "0.1.0", "tags": [slugify(t) for t in candidate.tools[:4]] + ["workflow"],
+                     "source": "askit mine"},
+    })
+    lines = [fm, "# %s\n" % name.replace("-", " ").capitalize(),
+             "This workflow was found %d times in shell history. Review the steps and fill in the "
+             "parameters before running them.\n" % candidate.count,
+             "## When to use\n",
+             "- The user wants to repeat the routine below on a different target.",
+             "- The user describes the same goal in different words.\n",
+             "## Steps\n"]
+    for i, tmpl in enumerate(candidate.template, 1):
+        lines.append("%d. Run:\n\n   ```bash\n   %s\n   ```" % (i, tmpl))
+    phs = placeholders(candidate)
+    if phs:
+        lines.append("\n## Parameters\n")
+        for ph in phs:
+            lines.append("- `%s`: %s" % (ph, _PLACEHOLDER_HELP.get(ph, "a value that changes between runs")))
+    lines.append("\n## Example from history\n")
+    lines.append("```bash\n%s\n```" % "\n".join(candidate.examples))
+    lines.append("\n## Notes\n")
+    lines.append("- Stop and report the error if a step fails; do not continue with the remaining steps.")
+    lines.append("- Ask the user to confirm any step that deletes or overwrites data.")
+    return {"SKILL.md": "\n".join(lines) + "\n"}

agentskill_kit/mockmodel.py

@@ -0,0 +1,124 @@
+"""Built-in offline model used by ``--provider mock``.
+
+It always answers with the same small, working skill. That makes the full
+forge loop (draft, lint, scan, test, score, write) demonstrable without
+network access, and keeps the test suite deterministic.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+_SKILL_MD = """---
+name: text-stats
+description: Computes word, sentence and line counts, average word length and the most frequent words of a text. Use when the user asks for statistics, a quick readability overview or word frequency of plain text or a file.
+license: MIT
+metadata:
+  version: 0.1.0
+  tags: [text, analysis, statistics]
+---
+
+# Text statistics
+
+Summarizes a piece of text with a small Python script that has no dependencies.
+
+## When to use
+
+- The user pastes text or points to a file and wants counts or word frequency.
+- The user wants a quick sense of length before editing or summarizing.
+
+## How to run
+
+```bash
+python scripts/text_stats.py --top 5 notes.txt
+cat notes.txt | python scripts/text_stats.py
+```
+
+The script reads the file given as the last argument, or standard input when no file is given.
+
+## Output
+
+A JSON object with `words`, `sentences`, `lines`, `avg_word_length` and `top_words`
+(a list of `[word, count]` pairs). Words shorter than three letters are ignored in `top_words`.
+
+## Example
+
+Input: `The cat sat. The cat ran.`
+
+Output: `{"words": 6, "sentences": 2, "lines": 1, "avg_word_length": 3.0, "top_words": [["the", 2], ["cat", 2], ["sat", 1], ["ran", 1]]}`
+
+## Errors
+
+A missing file exits with code 2 and a message on stderr. Empty input returns zero counts.
+"""
+
+_SCRIPT = '''#!/usr/bin/env python3
+"""Print word, sentence and line statistics for text."""
+import argparse
+import json
+import re
+import sys
+from collections import Counter
+
+
+def analyze(text, top=5):
+    words = re.findall(r"[A-Za-z0-9']+", text)
+    sentences = [s for s in re.split(r"[.!?]+", text) if s.strip()]
+    lines = [ln for ln in text.splitlines() if ln.strip()]
+    counts = Counter(w.lower() for w in words if len(w) >= 3)
+    avg = round(sum(len(w) for w in words) / len(words), 2) if words else 0.0
+    return {
+        "words": len(words),
+        "sentences": len(sentences),
+        "lines": len(lines),
+        "avg_word_length": avg,
+        "top_words": [[w, c] for w, c in counts.most_common(top)],
+    }
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("file", nargs="?", help="text file (reads stdin when omitted)")
+    parser.add_argument("--top", type=int, default=5, help="number of frequent words to list")
+    args = parser.parse_args(argv)
+    if args.file:
+        try:
+            with open(args.file, encoding="utf-8") as fh:
+                text = fh.read()
+        except OSError:
+            print("file not found: %s" % args.file, file=sys.stderr)
+            return 2
+    else:
+        text = sys.stdin.read()
+    print(json.dumps(analyze(text, args.top)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+'''
+
+_CASES = """{
+  "entry": "scripts/text_stats.py",
+  "cases": [
+    {"name": "counts words and sentences", "kind": "happy",
+     "stdin": "The cat sat. The cat ran.",
+     "stdout_json": {"words": 6, "sentences": 2, "top_words": [["the", 2], ["cat", 2], ["sat", 1], ["ran", 1]]}},
+    {"name": "empty input", "kind": "edge", "stdin": "",
+     "stdout_json": {"words": 0, "sentences": 0, "lines": 0}},
+    {"name": "missing file", "kind": "error", "args": ["nope.txt"],
+     "expect_exit": 2, "stderr_contains": "file not found"}
+  ]
+}
+"""
+
+
+def draft_files() -> Dict[str, str]:
+    return {"SKILL.md": _SKILL_MD, "scripts/text_stats.py": _SCRIPT, "tests/cases.json": _CASES}
+
+
+def mock_reply(messages: List[Dict[str, str]]) -> str:
+    parts = []
+    for path, content in draft_files().items():
+        parts.append("=== FILE: %s ===\n%s\n=== END FILE ===" % (path, content.rstrip("\n")))
+    return "\n\n".join(parts)