skill-runner 0.1.0__tar.gz

skill_runner-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: skill-runner
+Version: 0.1.0
+Summary: Minimal headless agent that executes skill.md files via OpenAI-compatible Chat Completion API
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.0.0

skill_runner-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skill-runner"
+version = "0.1.0"
+description = "Minimal headless agent that executes skill.md files via OpenAI-compatible Chat Completion API"
+requires-python = ">=3.10"
+dependencies = [
+    "openai>=1.0.0",
+]
+
+[project.scripts]
+skill-runner = "skill_runner.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

skill_runner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skill_runner-0.1.0/src/skill_runner/__init__.py

@@ -0,0 +1,3 @@
+"""Minimal headless agent that executes skill.md files via Chat Completion API."""
+
+__version__ = "0.1.0"

skill_runner-0.1.0/src/skill_runner/__main__.py

@@ -0,0 +1,86 @@
+"""CLI entry point: python -m skill_runner"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .api import Config, create_client
+from .loop import run
+from .skill import load_skill
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="skill-runner",
+        description="Headless agent that executes skill.md files via Chat Completion API",
+    )
+    parser.add_argument(
+        "--skill", required=True, help="Path to a skill.md file"
+    )
+    parser.add_argument(
+        "--input",
+        default=None,
+        help="Path to input file (reads stdin if omitted)",
+    )
+    parser.add_argument(
+        "--output",
+        default=None,
+        help="Path to output file (prints to stdout if omitted)",
+    )
+    parser.add_argument(
+        "--api-base",
+        default=None,
+        help="API base URL (overrides SKILL_RUNNER_BASE_URL)",
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        help="Model name (overrides SKILL_RUNNER_MODEL)",
+    )
+    parser.add_argument(
+        "--max-turns",
+        type=int,
+        default=None,
+        help="Max agent loop turns (overrides skill front matter)",
+    )
+
+    args = parser.parse_args()
+
+    # Load skill
+    skill = load_skill(args.skill)
+    if args.max_turns is not None:
+        skill.max_turns = args.max_turns
+
+    # Build config from env, then override with CLI args
+    config = Config.from_env()
+    if args.api_base:
+        config.base_url = args.api_base
+    if args.model:
+        config.model = args.model
+
+    # Read user input
+    if args.input:
+        with open(args.input) as f:
+            user_input = f.read()
+    elif not sys.stdin.isatty():
+        user_input = sys.stdin.read()
+    else:
+        print("Error: No input provided. Use --input FILE or pipe via stdin.", file=sys.stderr)
+        sys.exit(1)
+
+    # Run agent loop
+    client = create_client(config)
+    result = run(skill=skill, user_input=user_input, client=client, model=config.model)
+
+    # Output result
+    if args.output:
+        with open(args.output, "w") as f:
+            f.write(result)
+        print(f"Result written to {args.output}", file=sys.stderr)
+    else:
+        print(result)
+
+
+if __name__ == "__main__":
+    main()

skill_runner-0.1.0/src/skill_runner/api.py

@@ -0,0 +1,32 @@
+"""OpenAI Chat Completion API wrapper."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from openai import OpenAI
+
+
+@dataclass
+class Config:
+    base_url: str | None = None
+    api_key: str | None = None
+    model: str = "gpt-4o"
+
+    @classmethod
+    def from_env(cls) -> Config:
+        return cls(
+            base_url=os.environ.get("SKILL_RUNNER_BASE_URL"),
+            api_key=os.environ.get("SKILL_RUNNER_API_KEY"),
+            model=os.environ.get("SKILL_RUNNER_MODEL", "gpt-4o"),
+        )
+
+
+def create_client(config: Config) -> OpenAI:
+    kwargs: dict = {}
+    if config.base_url:
+        kwargs["base_url"] = config.base_url
+    if config.api_key:
+        kwargs["api_key"] = config.api_key
+    return OpenAI(**kwargs)

skill_runner-0.1.0/src/skill_runner/loop.py

@@ -0,0 +1,63 @@
+"""Agent loop — the core of skill-runner.
+
+Calls Chat Completion API, parses tool_calls, executes tools, feeds results
+back, and repeats until a text-only response or max_turns is reached.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from openai import OpenAI
+
+from .skill import Skill
+from .tools import execute_tool, get_tool_schemas
+
+
+def run(
+    skill: Skill,
+    user_input: str,
+    client: OpenAI,
+    model: str,
+) -> str:
+    """Execute the agent loop and return the final text response."""
+    tools = get_tool_schemas(skill.allowed_tools)
+    messages: list[dict] = [
+        {"role": "system", "content": skill.system_prompt},
+        {"role": "user", "content": user_input},
+    ]
+
+    for turn in range(skill.max_turns):
+        kwargs: dict = {"model": model, "messages": messages}
+        if tools:
+            kwargs["tools"] = tools
+
+        response = client.chat.completions.create(**kwargs)
+        choice = response.choices[0]
+        message = choice.message
+
+        # Text-only response — done
+        if not message.tool_calls:
+            return message.content or ""
+
+        # Tool calls — execute and continue
+        # Append assistant message (with tool_calls)
+        messages.append(message.model_dump())
+
+        for call in message.tool_calls:
+            print(
+                f"  [turn {turn + 1}] {call.function.name}({call.function.arguments[:80]}...)"
+                if len(call.function.arguments) > 80
+                else f"  [turn {turn + 1}] {call.function.name}({call.function.arguments})",
+                file=sys.stderr,
+            )
+            result = execute_tool(call.function.name, call.function.arguments)
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": call.id,
+                    "content": result,
+                }
+            )
+
+    return "[max_turns reached]"

skill_runner-0.1.0/src/skill_runner/skill.py

@@ -0,0 +1,62 @@
+"""skill.md parser — loads markdown with optional YAML front matter."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+DEFAULT_MAX_TURNS = 50
+ALL_TOOLS = ["file_read", "file_write", "file_patch", "bash", "grep", "glob"]
+
+
+@dataclass
+class Skill:
+    system_prompt: str
+    allowed_tools: list[str] = field(default_factory=lambda: list(ALL_TOOLS))
+    max_turns: int = DEFAULT_MAX_TURNS
+
+
+def _parse_front_matter(text: str) -> tuple[dict, str]:
+    """Extract YAML front matter (between --- delimiters) and body.
+
+    Uses simple regex parsing to avoid PyYAML dependency.
+    Only supports `tools` (list) and `max_turns` (int).
+    """
+    m = re.match(r"\A---\s*\n(.*?)\n---\s*\n(.*)", text, re.DOTALL)
+    if not m:
+        return {}, text
+
+    raw, body = m.group(1), m.group(2)
+    meta: dict = {}
+
+    # Parse tools: [file_read, bash]
+    tools_match = re.search(r"tools:\s*\[([^\]]*)\]", raw)
+    if tools_match:
+        meta["tools"] = [t.strip() for t in tools_match.group(1).split(",") if t.strip()]
+
+    # Parse max_turns: 20
+    turns_match = re.search(r"max_turns:\s*(\d+)", raw)
+    if turns_match:
+        meta["max_turns"] = int(turns_match.group(1))
+
+    return meta, body
+
+
+def load_skill(path: str) -> Skill:
+    """Load a skill.md file and return a Skill instance."""
+    with open(path) as f:
+        text = f.read()
+
+    meta, body = _parse_front_matter(text)
+
+    allowed_tools = meta.get("tools", list(ALL_TOOLS))
+    # Validate tool names
+    for t in allowed_tools:
+        if t not in ALL_TOOLS:
+            raise ValueError(f"Unknown tool in front matter: {t}")
+
+    return Skill(
+        system_prompt=body.strip(),
+        allowed_tools=allowed_tools,
+        max_turns=meta.get("max_turns", DEFAULT_MAX_TURNS),
+    )

skill_runner-0.1.0/src/skill_runner/tools.py

@@ -0,0 +1,309 @@
+"""Tool definitions and execution for the agent loop.
+
+Six tools: file_read, file_write, file_patch, bash, grep, glob.
+Each tool is a plain function that returns a string result.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+# ---------- blocked commands for bash tool ----------
+
+BLOCKED_COMMANDS = [
+    "rm -rf /",
+    "rm -rf /*",
+    "git push --force",
+    "git push -f",
+    "mkfs.",
+    "dd if=/dev/zero",
+    ":(){ :|:& };:",
+    "> /dev/sda",
+]
+
+# ---------- tool implementations ----------
+
+
+def file_read(path: str, offset: int = 0, limit: int = 2000) -> str:
+    """Read a file and return its contents with line numbers."""
+    try:
+        with open(path) as f:
+            lines = f.readlines()
+        selected = lines[offset : offset + limit]
+        numbered = [f"{offset + i + 1}\t{line}" for i, line in enumerate(selected)]
+        return "".join(numbered)
+    except Exception as e:
+        return f"[ERROR] {e}"
+
+
+def file_write(path: str, content: str) -> str:
+    """Write content to a file, creating parent directories if needed."""
+    try:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            f.write(content)
+        return f"[OK] Wrote {len(content)} bytes to {path}"
+    except Exception as e:
+        return f"[ERROR] {e}"
+
+
+def file_patch(path: str, old_string: str, new_string: str) -> str:
+    """Replace old_string with new_string in a file."""
+    try:
+        with open(path) as f:
+            content = f.read()
+        if old_string not in content:
+            return f"[ERROR] old_string not found in {path}"
+        count = content.count(old_string)
+        if count > 1:
+            return f"[ERROR] old_string found {count} times in {path} (must be unique)"
+        patched = content.replace(old_string, new_string, 1)
+        with open(path, "w") as f:
+            f.write(patched)
+        return f"[OK] Patched {path}"
+    except Exception as e:
+        return f"[ERROR] {e}"
+
+
+def bash(command: str, timeout: int = 30) -> str:
+    """Execute a shell command with timeout and safety checks."""
+    for blocked in BLOCKED_COMMANDS:
+        if blocked in command:
+            return f"[BLOCKED] Dangerous command detected: {blocked}"
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        output = result.stdout + result.stderr
+        if len(output) > 50000:
+            output = output[:50000] + "\n[TRUNCATED]"
+        return output if output else "[OK] (no output)"
+    except subprocess.TimeoutExpired:
+        return f"[ERROR] Command timed out after {timeout}s"
+    except Exception as e:
+        return f"[ERROR] {e}"
+
+
+def grep(pattern: str, path: str = ".", include: str = "") -> str:
+    """Search file contents using regex pattern."""
+    try:
+        results = []
+        search_path = Path(path)
+
+        if search_path.is_file():
+            files = [search_path]
+        else:
+            glob_pattern = include if include else "**/*"
+            files = sorted(search_path.glob(glob_pattern))
+
+        regex = re.compile(pattern)
+        for fpath in files:
+            if not fpath.is_file():
+                continue
+            try:
+                with open(fpath) as f:
+                    for lineno, line in enumerate(f, 1):
+                        if regex.search(line):
+                            results.append(f"{fpath}:{lineno}:{line.rstrip()}")
+            except (UnicodeDecodeError, PermissionError):
+                continue
+
+        if not results:
+            return "[NO MATCHES]"
+        output = "\n".join(results)
+        if len(output) > 50000:
+            output = output[:50000] + "\n[TRUNCATED]"
+        return output
+    except Exception as e:
+        return f"[ERROR] {e}"
+
+
+def glob_search(pattern: str, path: str = ".") -> str:
+    """Find files matching a glob pattern."""
+    try:
+        search_path = Path(path)
+        matches = sorted(str(p) for p in search_path.glob(pattern) if p.is_file())
+        if not matches:
+            return "[NO MATCHES]"
+        return "\n".join(matches)
+    except Exception as e:
+        return f"[ERROR] {e}"
+
+
+# ---------- tool registry ----------
+
+TOOL_FUNCTIONS = {
+    "file_read": file_read,
+    "file_write": file_write,
+    "file_patch": file_patch,
+    "bash": bash,
+    "grep": grep,
+    "glob": glob_search,
+}
+
+TOOL_SCHEMAS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "file_read",
+            "description": "Read a file and return its contents with line numbers.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Path to the file"},
+                    "offset": {
+                        "type": "integer",
+                        "description": "Line offset to start reading from (0-based)",
+                        "default": 0,
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum number of lines to read",
+                        "default": 2000,
+                    },
+                },
+                "required": ["path"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "file_write",
+            "description": "Write content to a file, creating parent directories if needed.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Path to the file"},
+                    "content": {
+                        "type": "string",
+                        "description": "Content to write",
+                    },
+                },
+                "required": ["path", "content"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "file_patch",
+            "description": "Replace old_string with new_string in a file. The old_string must appear exactly once.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Path to the file"},
+                    "old_string": {
+                        "type": "string",
+                        "description": "The exact string to find",
+                    },
+                    "new_string": {
+                        "type": "string",
+                        "description": "The replacement string",
+                    },
+                },
+                "required": ["path", "old_string", "new_string"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "bash",
+            "description": "Execute a shell command and return stdout+stderr. Dangerous commands are blocked.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "The shell command to execute",
+                    },
+                    "timeout": {
+                        "type": "integer",
+                        "description": "Timeout in seconds",
+                        "default": 30,
+                    },
+                },
+                "required": ["command"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "grep",
+            "description": "Search file contents using a regex pattern.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "Regex pattern to search for",
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "File or directory to search in",
+                        "default": ".",
+                    },
+                    "include": {
+                        "type": "string",
+                        "description": "Glob pattern to filter files (e.g. '**/*.py')",
+                        "default": "",
+                    },
+                },
+                "required": ["pattern"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "glob",
+            "description": "Find files matching a glob pattern.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "Glob pattern (e.g. '**/*.py')",
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Base directory to search from",
+                        "default": ".",
+                    },
+                },
+                "required": ["pattern"],
+            },
+        },
+    },
+]
+
+
+def get_tool_schemas(allowed_tools: list[str]) -> list[dict]:
+    """Return OpenAI function calling schemas for allowed tools."""
+    return [s for s in TOOL_SCHEMAS if s["function"]["name"] in allowed_tools]
+
+
+def execute_tool(name: str, arguments: str) -> str:
+    """Execute a tool by name with JSON arguments string."""
+    func = TOOL_FUNCTIONS.get(name)
+    if not func:
+        return f"[ERROR] Unknown tool: {name}"
+    try:
+        args = json.loads(arguments)
+    except json.JSONDecodeError as e:
+        return f"[ERROR] Invalid JSON arguments: {e}"
+    try:
+        return func(**args)
+    except TypeError as e:
+        return f"[ERROR] Invalid arguments for {name}: {e}"

skill_runner-0.1.0/src/skill_runner.egg-info/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: skill-runner
+Version: 0.1.0
+Summary: Minimal headless agent that executes skill.md files via OpenAI-compatible Chat Completion API
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.0.0

skill_runner-0.1.0/src/skill_runner.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+pyproject.toml
+src/skill_runner/__init__.py
+src/skill_runner/__main__.py
+src/skill_runner/api.py
+src/skill_runner/loop.py
+src/skill_runner/skill.py
+src/skill_runner/tools.py
+src/skill_runner.egg-info/PKG-INFO
+src/skill_runner.egg-info/SOURCES.txt
+src/skill_runner.egg-info/dependency_links.txt
+src/skill_runner.egg-info/entry_points.txt
+src/skill_runner.egg-info/requires.txt
+src/skill_runner.egg-info/top_level.txt
+tests/test_loop.py
+tests/test_skill.py
+tests/test_tools.py

skill_runner-0.1.0/src/skill_runner.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

skill_runner-0.1.0/src/skill_runner.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skill-runner = skill_runner.__main__:main

skill_runner-0.1.0/src/skill_runner.egg-info/requires.txt

@@ -0,0 +1 @@
+openai>=1.0.0

skill_runner-0.1.0/src/skill_runner.egg-info/top_level.txt

@@ -0,0 +1 @@
+skill_runner

skill_runner-0.1.0/tests/test_loop.py

@@ -0,0 +1,110 @@
+"""Tests for the agent loop using mock API responses."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from skill_runner.loop import run
+from skill_runner.skill import Skill
+
+
+def _make_text_response(content: str):
+    """Create a mock API response with text content only."""
+    message = MagicMock()
+    message.content = content
+    message.tool_calls = None
+    choice = MagicMock()
+    choice.message = message
+    response = MagicMock()
+    response.choices = [choice]
+    return response
+
+
+def _make_tool_response(tool_calls: list[dict]):
+    """Create a mock API response with tool calls."""
+    mock_calls = []
+    for tc in tool_calls:
+        call = MagicMock()
+        call.id = tc["id"]
+        call.function.name = tc["name"]
+        call.function.arguments = tc["arguments"]
+        mock_calls.append(call)
+
+    message = MagicMock()
+    message.tool_calls = mock_calls
+    message.content = None
+    message.model_dump.return_value = {
+        "role": "assistant",
+        "content": None,
+        "tool_calls": [
+            {
+                "id": tc["id"],
+                "type": "function",
+                "function": {"name": tc["name"], "arguments": tc["arguments"]},
+            }
+            for tc in tool_calls
+        ],
+    }
+    choice = MagicMock()
+    choice.message = message
+    response = MagicMock()
+    response.choices = [choice]
+    return response
+
+
+def test_text_only_response():
+    """Loop returns immediately on text-only response."""
+    client = MagicMock()
+    client.chat.completions.create.return_value = _make_text_response("Hello!")
+
+    skill = Skill(system_prompt="You are helpful.", allowed_tools=[], max_turns=10)
+    result = run(skill, "Hi", client, "test-model")
+    assert result == "Hello!"
+    assert client.chat.completions.create.call_count == 1
+
+
+def test_tool_call_then_text(tmp_path):
+    """Loop executes tool, feeds result back, then gets text response."""
+    test_file = tmp_path / "test.txt"
+    test_file.write_text("file content here\n")
+
+    client = MagicMock()
+    client.chat.completions.create.side_effect = [
+        _make_tool_response(
+            [
+                {
+                    "id": "call_1",
+                    "name": "file_read",
+                    "arguments": f'{{"path": "{test_file}"}}',
+                }
+            ]
+        ),
+        _make_text_response("I read the file. It says: file content here"),
+    ]
+
+    skill = Skill(
+        system_prompt="Read files when asked.",
+        allowed_tools=["file_read"],
+        max_turns=10,
+    )
+    result = run(skill, "Read the test file", client, "test-model")
+    assert "file content here" in result
+    assert client.chat.completions.create.call_count == 2
+
+
+def test_max_turns_reached():
+    """Loop stops at max_turns and returns sentinel."""
+    client = MagicMock()
+    # Always return tool calls — should hit max_turns
+    client.chat.completions.create.return_value = _make_tool_response(
+        [{"id": "call_1", "name": "bash", "arguments": '{"command": "echo hi"}'}]
+    )
+
+    skill = Skill(
+        system_prompt="Keep going.",
+        allowed_tools=["bash"],
+        max_turns=3,
+    )
+    result = run(skill, "Loop forever", client, "test-model")
+    assert result == "[max_turns reached]"
+    assert client.chat.completions.create.call_count == 3

skill_runner-0.1.0/tests/test_skill.py

@@ -0,0 +1,62 @@
+"""Tests for skill.md parser."""
+
+import os
+import tempfile
+
+from skill_runner.skill import ALL_TOOLS, DEFAULT_MAX_TURNS, load_skill
+
+
+def _write_tmp(content: str) -> str:
+    fd, path = tempfile.mkstemp(suffix=".md")
+    with os.fdopen(fd, "w") as f:
+        f.write(content)
+    return path
+
+
+def test_plain_markdown():
+    """Skill with no front matter — entire file is system prompt."""
+    path = _write_tmp("# Hello\n\nDo something useful.")
+    skill = load_skill(path)
+    assert skill.system_prompt == "# Hello\n\nDo something useful."
+    assert skill.allowed_tools == ALL_TOOLS
+    assert skill.max_turns == DEFAULT_MAX_TURNS
+    os.unlink(path)
+
+
+def test_front_matter_tools():
+    """Skill with tools restriction in front matter."""
+    path = _write_tmp("---\ntools: [file_read, bash]\n---\n# Review\nReview code.")
+    skill = load_skill(path)
+    assert skill.allowed_tools == ["file_read", "bash"]
+    assert skill.system_prompt == "# Review\nReview code."
+    os.unlink(path)
+
+
+def test_front_matter_max_turns():
+    """Skill with max_turns in front matter."""
+    path = _write_tmp("---\nmax_turns: 10\n---\n# Short\nQuick task.")
+    skill = load_skill(path)
+    assert skill.max_turns == 10
+    assert skill.allowed_tools == ALL_TOOLS
+    os.unlink(path)
+
+
+def test_front_matter_both():
+    """Skill with both tools and max_turns."""
+    path = _write_tmp("---\ntools: [grep, glob]\nmax_turns: 5\n---\n# Search\nFind files.")
+    skill = load_skill(path)
+    assert skill.allowed_tools == ["grep", "glob"]
+    assert skill.max_turns == 5
+    os.unlink(path)
+
+
+def test_invalid_tool_raises():
+    """Unknown tool name in front matter raises ValueError."""
+    path = _write_tmp("---\ntools: [file_read, unknown_tool]\n---\n# Bad\nFail.")
+    try:
+        load_skill(path)
+        assert False, "Should have raised ValueError"
+    except ValueError as e:
+        assert "unknown_tool" in str(e)
+    finally:
+        os.unlink(path)

skill_runner-0.1.0/tests/test_tools.py

@@ -0,0 +1,163 @@
+"""Tests for tool implementations."""
+
+import json
+import os
+import tempfile
+
+from skill_runner.tools import (
+    bash,
+    execute_tool,
+    file_patch,
+    file_read,
+    file_write,
+    get_tool_schemas,
+    glob_search,
+    grep,
+)
+
+
+class TestFileRead:
+    def test_read_file(self, tmp_path):
+        p = tmp_path / "test.txt"
+        p.write_text("line1\nline2\nline3\n")
+        result = file_read(str(p))
+        assert "1\tline1" in result
+        assert "3\tline3" in result
+
+    def test_read_with_offset(self, tmp_path):
+        p = tmp_path / "test.txt"
+        p.write_text("line1\nline2\nline3\n")
+        result = file_read(str(p), offset=1, limit=1)
+        assert "2\tline2" in result
+        assert "line1" not in result
+
+    def test_read_nonexistent(self):
+        result = file_read("/nonexistent/file.txt")
+        assert "[ERROR]" in result
+
+
+class TestFileWrite:
+    def test_write_file(self, tmp_path):
+        p = tmp_path / "output.txt"
+        result = file_write(str(p), "hello world")
+        assert "[OK]" in result
+        assert p.read_text() == "hello world"
+
+    def test_write_creates_dirs(self, tmp_path):
+        p = tmp_path / "sub" / "dir" / "file.txt"
+        result = file_write(str(p), "nested")
+        assert "[OK]" in result
+        assert p.read_text() == "nested"
+
+
+class TestFilePatch:
+    def test_patch_unique(self, tmp_path):
+        p = tmp_path / "test.txt"
+        p.write_text("hello world")
+        result = file_patch(str(p), "hello", "goodbye")
+        assert "[OK]" in result
+        assert p.read_text() == "goodbye world"
+
+    def test_patch_not_found(self, tmp_path):
+        p = tmp_path / "test.txt"
+        p.write_text("hello world")
+        result = file_patch(str(p), "missing", "replacement")
+        assert "[ERROR]" in result
+        assert "not found" in result
+
+    def test_patch_multiple_matches(self, tmp_path):
+        p = tmp_path / "test.txt"
+        p.write_text("aaa aaa")
+        result = file_patch(str(p), "aaa", "bbb")
+        assert "[ERROR]" in result
+        assert "2 times" in result
+
+
+class TestBash:
+    def test_simple_command(self):
+        result = bash("echo hello")
+        assert "hello" in result
+
+    def test_blocked_rm_rf(self):
+        result = bash("rm -rf /")
+        assert "[BLOCKED]" in result
+
+    def test_blocked_force_push(self):
+        result = bash("git push --force")
+        assert "[BLOCKED]" in result
+
+    def test_timeout(self):
+        result = bash("sleep 10", timeout=1)
+        assert "[ERROR]" in result
+        assert "timed out" in result
+
+    def test_stderr_captured(self):
+        result = bash("ls /nonexistent_dir_12345 2>&1 || true")
+        # Should have some output (error message)
+        assert result  # non-empty
+
+
+class TestGrep:
+    def test_grep_file(self, tmp_path):
+        p = tmp_path / "test.txt"
+        p.write_text("hello world\nfoo bar\nhello again\n")
+        result = grep("hello", str(p))
+        assert "1:" in result
+        assert "3:" in result
+
+    def test_grep_no_match(self, tmp_path):
+        p = tmp_path / "test.txt"
+        p.write_text("nothing here\n")
+        result = grep("missing", str(p))
+        assert "[NO MATCHES]" in result
+
+    def test_grep_directory(self, tmp_path):
+        (tmp_path / "a.py").write_text("import os\n")
+        (tmp_path / "b.py").write_text("import sys\n")
+        result = grep("import", str(tmp_path), include="*.py")
+        assert "a.py" in result
+        assert "b.py" in result
+
+
+class TestGlob:
+    def test_glob_pattern(self, tmp_path):
+        (tmp_path / "a.py").write_text("")
+        (tmp_path / "b.py").write_text("")
+        (tmp_path / "c.txt").write_text("")
+        result = glob_search("*.py", str(tmp_path))
+        assert "a.py" in result
+        assert "b.py" in result
+        assert "c.txt" not in result
+
+    def test_glob_no_match(self, tmp_path):
+        result = glob_search("*.xyz", str(tmp_path))
+        assert "[NO MATCHES]" in result
+
+
+class TestExecuteTool:
+    def test_execute_known_tool(self, tmp_path):
+        p = tmp_path / "test.txt"
+        p.write_text("content")
+        result = execute_tool("file_read", json.dumps({"path": str(p)}))
+        assert "content" in result
+
+    def test_execute_unknown_tool(self):
+        result = execute_tool("unknown", "{}")
+        assert "[ERROR]" in result
+        assert "Unknown tool" in result
+
+    def test_execute_invalid_json(self):
+        result = execute_tool("file_read", "not json")
+        assert "[ERROR]" in result
+
+
+class TestGetToolSchemas:
+    def test_all_tools(self):
+        schemas = get_tool_schemas(["file_read", "file_write", "file_patch", "bash", "grep", "glob"])
+        assert len(schemas) == 6
+
+    def test_filtered_tools(self):
+        schemas = get_tool_schemas(["file_read", "bash"])
+        assert len(schemas) == 2
+        names = {s["function"]["name"] for s in schemas}
+        assert names == {"file_read", "bash"}