docketeer-agentskills 0.0.5__tar.gz

docketeer_agentskills-0.0.5/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.envrc.private
+.claude/settings.local.json
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+workspace/
+.coverage
+.loq_cache

docketeer_agentskills-0.0.5/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: docketeer-agentskills
+Version: 0.0.5
+Summary: Agent Skills plugin for Docketeer
+Project-URL: Homepage, https://github.com/chrisguidry/docketeer
+Project-URL: Repository, https://github.com/chrisguidry/docketeer
+Project-URL: Issues, https://github.com/chrisguidry/docketeer/issues
+Author-email: Chris Guidry <guid@omg.lol>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: docketeer
+Requires-Dist: pyyaml
+Description-Content-Type: text/markdown
+
+# docketeer-agentskills
+
+[Agent Skills](https://agentskills.io/specification) plugin for
+[Docketeer](https://github.com/chrisguidry/docketeer).
+
+Adds support for installing, managing, and using skills packaged as directories
+with a `SKILL.md` file (YAML frontmatter + markdown instructions).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_skills` | List installed skills with descriptions |
+| `activate_skill` | Load a skill's full instructions |
+| `read_skill_file` | Read any file from a skill directory |
+| `install_skill` | Install a skill from a git repository |
+| `uninstall_skill` | Remove an installed skill |
+
+## How it works
+
+Skills live in `{workspace}/skills/`. The plugin provides three levels of
+progressive disclosure:
+
+1. **System prompt** — skill names and descriptions are always available
+2. **activate_skill** — loads the full SKILL.md body on demand
+3. **read_skill_file** — reads any file from the skill directory on demand
+
+## Configuration
+
+No configuration required. Skills are discovered automatically from the
+`skills/` directory in the agent's workspace.

docketeer_agentskills-0.0.5/README.md

@@ -0,0 +1,31 @@
+# docketeer-agentskills
+
+[Agent Skills](https://agentskills.io/specification) plugin for
+[Docketeer](https://github.com/chrisguidry/docketeer).
+
+Adds support for installing, managing, and using skills packaged as directories
+with a `SKILL.md` file (YAML frontmatter + markdown instructions).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_skills` | List installed skills with descriptions |
+| `activate_skill` | Load a skill's full instructions |
+| `read_skill_file` | Read any file from a skill directory |
+| `install_skill` | Install a skill from a git repository |
+| `uninstall_skill` | Remove an installed skill |
+
+## How it works
+
+Skills live in `{workspace}/skills/`. The plugin provides three levels of
+progressive disclosure:
+
+1. **System prompt** — skill names and descriptions are always available
+2. **activate_skill** — loads the full SKILL.md body on demand
+3. **read_skill_file** — reads any file from the skill directory on demand
+
+## Configuration
+
+No configuration required. Skills are discovered automatically from the
+`skills/` directory in the agent's workspace.

docketeer_agentskills-0.0.5/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "docketeer-agentskills"
+dynamic = ["version"]
+description = "Agent Skills plugin for Docketeer"
+readme = "README.md"
+authors = [
+    { name = "Chris Guidry", email = "guid@omg.lol" }
+]
+license = "MIT"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "docketeer",
+    "pyyaml",
+]
+
+[project.urls]
+Homepage = "https://github.com/chrisguidry/docketeer"
+Repository = "https://github.com/chrisguidry/docketeer"
+Issues = "https://github.com/chrisguidry/docketeer/issues"
+
+[project.entry-points."docketeer.tools"]
+agentskills = "docketeer_agentskills"
+
+[project.entry-points."docketeer.prompt"]
+agentskills = "docketeer_agentskills.prompt:provide_skill_catalog"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options.root = ".."
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docketeer_agentskills"]
+
+[tool.uv.sources]
+docketeer = { workspace = true }
+
+[tool.pytest_env]
+DOCKETEER_ANTHROPIC_API_KEY = "test-key"
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+addopts = [
+    "--import-mode=importlib",
+    "--cov=docketeer_agentskills",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+asyncio_mode = "auto"
+filterwarnings = [
+    "error",
+]

docketeer_agentskills-0.0.5/src/docketeer_agentskills/__init__.py

@@ -0,0 +1,3 @@
+"""Agent Skills plugin for Docketeer."""
+
+import docketeer_agentskills.tools as _tools  # noqa: F401

docketeer_agentskills-0.0.5/src/docketeer_agentskills/discovery.py

@@ -0,0 +1,95 @@
+"""Skill discovery: parse SKILL.md files and scan the skills directory."""
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+log = logging.getLogger(__name__)
+
+NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$|^[a-z0-9]$")
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    path: Path
+    body: str
+    license: str = ""
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+def parse_skill(skill_dir: Path) -> Skill:
+    """Parse a SKILL.md file from a skill directory."""
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        raise FileNotFoundError(f"No SKILL.md in {skill_dir}")
+
+    content = skill_md.read_text()
+    frontmatter, body = _split_frontmatter(content)
+
+    name = frontmatter.get("name", "")
+    if not name or not NAME_PATTERN.match(name):
+        raise ValueError(
+            f"Invalid skill name {name!r}: must be 1-64 lowercase"
+            " alphanumeric characters or hyphens"
+        )
+
+    if name != skill_dir.name:
+        raise ValueError(
+            f"Skill name {name!r} does not match directory name {skill_dir.name!r}"
+        )
+
+    description = frontmatter.get("description", "")
+    if not description:
+        raise ValueError(f"Skill {name!r} is missing a description")
+
+    return Skill(
+        name=name,
+        description=description,
+        path=skill_dir,
+        body=body.strip(),
+        license=frontmatter.get("license", ""),
+        metadata={
+            k: str(v)
+            for k, v in frontmatter.items()
+            if k not in {"name", "description", "license"}
+        },
+    )
+
+
+def discover_skills(skills_dir: Path) -> dict[str, Skill]:
+    """Scan a directory for skill subdirectories and return valid skills."""
+    if not skills_dir.is_dir():
+        return {}
+
+    skills: dict[str, Skill] = {}
+    for child in sorted(skills_dir.iterdir()):
+        if not child.is_dir():
+            continue
+        if not (child / "SKILL.md").exists():
+            continue
+        try:
+            skill = parse_skill(child)
+            skills[skill.name] = skill
+        except (ValueError, FileNotFoundError):
+            log.warning("Skipping invalid skill in %s", child.name, exc_info=True)
+
+    return skills
+
+
+def _split_frontmatter(content: str) -> tuple[dict, str]:
+    """Split YAML frontmatter from markdown body."""
+    if not content.startswith("---"):
+        return {}, content
+
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        return {}, content
+
+    raw = yaml.safe_load(parts[1])
+    frontmatter = raw if isinstance(raw, dict) else {}
+    return frontmatter, parts[2]

docketeer_agentskills-0.0.5/src/docketeer_agentskills/prompt.py

@@ -0,0 +1,25 @@
+"""System prompt provider for installed skills."""
+
+from pathlib import Path
+
+from docketeer.prompt import SystemBlock
+
+from .discovery import discover_skills
+
+
+def provide_skill_catalog(workspace: Path) -> list[SystemBlock]:
+    """Build a skill catalog block for the system prompt."""
+    skills = discover_skills(workspace / "skills")
+    if not skills:
+        return []
+
+    lines = [
+        "## Installed skills",
+        "",
+        "Use `activate_skill` to load a skill's full instructions when relevant.",
+        "",
+    ]
+    for skill in skills.values():
+        lines.append(f"- **{skill.name}**: {skill.description}")
+
+    return [SystemBlock(text="\n".join(lines))]

docketeer_agentskills-0.0.5/src/docketeer_agentskills/tools.py

@@ -0,0 +1,129 @@
+"""Skill management tools."""
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from docketeer.tools import ToolContext, _safe_path, registry
+
+from .discovery import discover_skills, parse_skill
+
+
+@registry.tool
+async def list_skills(ctx: ToolContext) -> str:
+    """List all installed skills with their descriptions."""
+    skills = discover_skills(ctx.workspace / "skills")
+    if not skills:
+        return "No skills installed."
+    lines = []
+    for skill in skills.values():
+        lines.append(f"- {skill.name}: {skill.description}")
+    return "\n".join(lines)
+
+
+@registry.tool
+async def activate_skill(ctx: ToolContext, name: str) -> str:
+    """Load the full instructions for an installed skill.
+
+    name: skill name to activate
+    """
+    skill_dir = _safe_path(ctx.workspace, f"skills/{name}")
+    if not skill_dir.is_dir():
+        return f"Skill not found: {name}"
+    try:
+        skill = parse_skill(skill_dir)
+    except (ValueError, FileNotFoundError) as e:
+        return f"Error loading skill {name}: {e}"
+    return skill.body
+
+
+@registry.tool
+async def read_skill_file(ctx: ToolContext, name: str, path: str) -> str:
+    """Read a file from an installed skill's directory.
+
+    name: skill name
+    path: relative path within the skill directory
+    """
+    skill_dir = _safe_path(ctx.workspace, f"skills/{name}")
+    if not skill_dir.is_dir():
+        return f"Skill not found: {name}"
+    target = (skill_dir / path).resolve()
+    if not str(target).startswith(str(skill_dir.resolve())):
+        return f"Path '{path}' is outside the skill directory"
+    if not target.exists():
+        return f"File not found: {path}"
+    if target.is_dir():
+        return "\n".join(
+            f"{e.name}/" if e.is_dir() else e.name for e in sorted(target.iterdir())
+        )
+    try:
+        return target.read_text()
+    except UnicodeDecodeError:
+        return f"Cannot read binary file: {path}"
+
+
+@registry.tool
+async def install_skill(
+    ctx: ToolContext, url: str, name: str = "", path: str = ""
+) -> str:
+    """Install a skill from a git repository.
+
+    url: git repository URL to clone
+    name: skill name (derived from URL or path if empty)
+    path: subdirectory within the repo containing SKILL.md
+    """
+    if not shutil.which("git"):
+        return "git is not installed — cannot clone skill repositories"
+
+    if not name:
+        source = path.rstrip("/") if path else url.rstrip("/")
+        name = source.rsplit("/", 1)[-1].removesuffix(".git")
+
+    skills_dir = ctx.workspace / "skills"
+    skills_dir.mkdir(exist_ok=True)
+    target = skills_dir / name
+
+    if target.exists():
+        return f"Skill {name!r} is already installed"
+
+    with tempfile.TemporaryDirectory() as tmp:
+        clone_dir = Path(tmp) / "repo"
+        result = subprocess.run(
+            ["git", "clone", "--depth", "1", url, str(clone_dir)],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            return f"Failed to clone: {result.stderr.strip()}"
+
+        source = clone_dir / path if path else clone_dir
+
+        if not source.is_dir():
+            return f"Path {path!r} not found in repository"
+
+        if not (source / "SKILL.md").exists():
+            return "Repository does not contain a SKILL.md file"
+
+        shutil.copytree(source, target)
+
+    try:
+        skill = parse_skill(target)
+    except (ValueError, FileNotFoundError) as e:
+        shutil.rmtree(target)
+        return f"Invalid skill: {e}"
+
+    return f"Installed skill {skill.name!r}: {skill.description}"
+
+
+@registry.tool
+async def uninstall_skill(ctx: ToolContext, name: str) -> str:
+    """Remove an installed skill.
+
+    name: skill name to remove
+    """
+    skill_dir = _safe_path(ctx.workspace, f"skills/{name}")
+    if not skill_dir.is_dir():
+        return f"Skill not found: {name}"
+    shutil.rmtree(skill_dir)
+    return f"Removed skill {name!r}"

docketeer_agentskills-0.0.5/tests/conftest.py

@@ -0,0 +1,42 @@
+"""Shared test fixtures for docketeer-agentskills."""
+
+from pathlib import Path
+
+import pytest
+
+from docketeer.tools import ToolContext
+
+
+@pytest.fixture()
+def workspace(tmp_path: Path) -> Path:
+    ws = tmp_path / "memory"
+    ws.mkdir()
+    return ws
+
+
+@pytest.fixture()
+def skills_dir(workspace: Path) -> Path:
+    d = workspace / "skills"
+    d.mkdir()
+    return d
+
+
+@pytest.fixture()
+def tool_context(workspace: Path) -> ToolContext:
+    return ToolContext(workspace=workspace, room_id="room1")
+
+
+def make_skill(
+    skills_dir: Path,
+    name: str = "test-skill",
+    description: str = "A test skill",
+    body: str = "## Instructions\n\nDo the thing.",
+    extra_frontmatter: str = "",
+) -> Path:
+    skill_dir = skills_dir / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    frontmatter = f"name: {name}\ndescription: {description}"
+    if extra_frontmatter:
+        frontmatter += f"\n{extra_frontmatter}"
+    (skill_dir / "SKILL.md").write_text(f"---\n{frontmatter}\n---\n{body}")
+    return skill_dir

docketeer_agentskills-0.0.5/tests/test_discovery.py

@@ -0,0 +1,138 @@
+"""Tests for skill discovery."""
+
+from pathlib import Path
+
+import pytest
+
+from docketeer_agentskills.discovery import (
+    _split_frontmatter,
+    discover_skills,
+    parse_skill,
+)
+
+from .conftest import make_skill
+
+
+def test_parse_skill(skills_dir: Path):
+    skill_dir = make_skill(skills_dir)
+    skill = parse_skill(skill_dir)
+    assert skill.name == "test-skill"
+    assert skill.description == "A test skill"
+    assert skill.path == skill_dir
+    assert "Instructions" in skill.body
+
+
+def test_parse_skill_with_license(skills_dir: Path):
+    skill_dir = make_skill(skills_dir, extra_frontmatter="license: MIT")
+    skill = parse_skill(skill_dir)
+    assert skill.license == "MIT"
+
+
+def test_parse_skill_extra_metadata(skills_dir: Path):
+    skill_dir = make_skill(skills_dir, extra_frontmatter="version: '1.0'\nauthor: me")
+    skill = parse_skill(skill_dir)
+    assert skill.metadata == {"version": "1.0", "author": "me"}
+
+
+def test_parse_skill_no_skill_md(skills_dir: Path):
+    skill_dir = skills_dir / "empty-skill"
+    skill_dir.mkdir()
+    with pytest.raises(FileNotFoundError, match="No SKILL.md"):
+        parse_skill(skill_dir)
+
+
+def test_parse_skill_invalid_name(skills_dir: Path):
+    skill_dir = skills_dir / "Bad_Name"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text(
+        "---\nname: Bad_Name\ndescription: bad\n---\nbody"
+    )
+    with pytest.raises(ValueError, match="Invalid skill name"):
+        parse_skill(skill_dir)
+
+
+def test_parse_skill_name_mismatch(skills_dir: Path):
+    skill_dir = skills_dir / "wrong-dir"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text(
+        "---\nname: correct-name\ndescription: test\n---\nbody"
+    )
+    with pytest.raises(ValueError, match="does not match directory name"):
+        parse_skill(skill_dir)
+
+
+def test_parse_skill_missing_description(skills_dir: Path):
+    skill_dir = skills_dir / "no-desc"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text("---\nname: no-desc\n---\nbody")
+    with pytest.raises(ValueError, match="missing a description"):
+        parse_skill(skill_dir)
+
+
+def test_parse_skill_missing_name(skills_dir: Path):
+    skill_dir = skills_dir / "no-name"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text("---\ndescription: test\n---\nbody")
+    with pytest.raises(ValueError, match="Invalid skill name"):
+        parse_skill(skill_dir)
+
+
+def test_parse_skill_single_char_name(skills_dir: Path):
+    skill_dir = skills_dir / "a"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text("---\nname: a\ndescription: one\n---\nbody")
+    skill = parse_skill(skill_dir)
+    assert skill.name == "a"
+
+
+def test_discover_skills(skills_dir: Path):
+    make_skill(skills_dir, name="skill-a", description="Alpha skill")
+    make_skill(skills_dir, name="skill-b", description="Beta skill")
+    skills = discover_skills(skills_dir)
+    assert set(skills.keys()) == {"skill-a", "skill-b"}
+
+
+def test_discover_skills_skips_invalid(skills_dir: Path):
+    make_skill(skills_dir, name="good-skill", description="Good")
+    bad_dir = skills_dir / "Bad_Skill"
+    bad_dir.mkdir()
+    (bad_dir / "SKILL.md").write_text("---\nname: Bad_Skill\ndescription: bad\n---\n")
+    skills = discover_skills(skills_dir)
+    assert list(skills.keys()) == ["good-skill"]
+
+
+def test_discover_skills_skips_dirs_without_skill_md(skills_dir: Path):
+    make_skill(skills_dir, name="real-skill", description="Real")
+    (skills_dir / "not-a-skill").mkdir()
+    skills = discover_skills(skills_dir)
+    assert list(skills.keys()) == ["real-skill"]
+
+
+def test_discover_skills_skips_files(skills_dir: Path):
+    make_skill(skills_dir, name="real-skill", description="Real")
+    (skills_dir / "random-file.txt").write_text("hi")
+    skills = discover_skills(skills_dir)
+    assert list(skills.keys()) == ["real-skill"]
+
+
+def test_discover_skills_nonexistent_dir(tmp_path: Path):
+    skills = discover_skills(tmp_path / "nope")
+    assert skills == {}
+
+
+def test_split_frontmatter_no_markers():
+    fm, body = _split_frontmatter("just markdown")
+    assert fm == {}
+    assert body == "just markdown"
+
+
+def test_split_frontmatter_incomplete_markers():
+    fm, body = _split_frontmatter("---\nname: test")
+    assert fm == {}
+    assert body == "---\nname: test"
+
+
+def test_split_frontmatter_non_dict_yaml():
+    fm, body = _split_frontmatter("---\n- list item\n---\nbody")
+    assert fm == {}
+    assert body == "\nbody"

docketeer_agentskills-0.0.5/tests/test_prompt.py

@@ -0,0 +1,29 @@
+"""Tests for the skill catalog prompt provider."""
+
+from pathlib import Path
+
+from docketeer_agentskills.prompt import provide_skill_catalog
+
+from .conftest import make_skill
+
+
+def test_provide_skill_catalog_no_skills_dir(workspace: Path):
+    blocks = provide_skill_catalog(workspace)
+    assert blocks == []
+
+
+def test_provide_skill_catalog_empty_skills_dir(skills_dir: Path, workspace: Path):
+    blocks = provide_skill_catalog(workspace)
+    assert blocks == []
+
+
+def test_provide_skill_catalog_with_skills(skills_dir: Path, workspace: Path):
+    make_skill(skills_dir, name="alpha", description="Alpha skill")
+    make_skill(skills_dir, name="beta", description="Beta skill")
+    blocks = provide_skill_catalog(workspace)
+    assert len(blocks) == 1
+    text = blocks[0].text
+    assert "## Installed skills" in text
+    assert "**alpha**: Alpha skill" in text
+    assert "**beta**: Beta skill" in text
+    assert "activate_skill" in text

docketeer_agentskills-0.0.5/tests/test_tools.py

@@ -0,0 +1,380 @@
+"""Tests for skill management tools."""
+
+from pathlib import Path
+from typing import Any
+from unittest.mock import patch
+
+from docketeer.tools import ToolContext, registry
+
+from .conftest import make_skill
+
+
+async def test_list_skills_none(tool_context: ToolContext):
+    result = await registry.execute("list_skills", {}, tool_context)
+    assert "No skills installed" in result
+
+
+async def test_list_skills(tool_context: ToolContext, skills_dir: Path):
+    make_skill(skills_dir, name="my-skill", description="Does things")
+    result = await registry.execute("list_skills", {}, tool_context)
+    assert "my-skill: Does things" in result
+
+
+async def test_activate_skill(tool_context: ToolContext, skills_dir: Path):
+    make_skill(skills_dir, name="my-skill", body="## Step 1\n\nDo the thing.")
+    result = await registry.execute(
+        "activate_skill", {"name": "my-skill"}, tool_context
+    )
+    assert "Step 1" in result
+    assert "Do the thing." in result
+
+
+async def test_activate_skill_not_found(tool_context: ToolContext, skills_dir: Path):
+    result = await registry.execute(
+        "activate_skill", {"name": "nonexistent"}, tool_context
+    )
+    assert "Skill not found" in result
+
+
+async def test_activate_skill_invalid(tool_context: ToolContext, skills_dir: Path):
+    bad_dir = skills_dir / "bad-skill"
+    bad_dir.mkdir()
+    (bad_dir / "SKILL.md").write_text("---\nname: bad-skill\n---\nbody")
+    result = await registry.execute(
+        "activate_skill", {"name": "bad-skill"}, tool_context
+    )
+    assert "Error loading skill" in result
+
+
+async def test_read_skill_file(tool_context: ToolContext, skills_dir: Path):
+    skill_dir = make_skill(skills_dir)
+    scripts = skill_dir / "scripts"
+    scripts.mkdir()
+    (scripts / "run.py").write_text("print('hello')")
+    result = await registry.execute(
+        "read_skill_file",
+        {"name": "test-skill", "path": "scripts/run.py"},
+        tool_context,
+    )
+    assert "print('hello')" in result
+
+
+async def test_read_skill_file_directory(tool_context: ToolContext, skills_dir: Path):
+    skill_dir = make_skill(skills_dir)
+    scripts = skill_dir / "scripts"
+    scripts.mkdir()
+    (scripts / "a.py").write_text("")
+    (scripts / "b.py").write_text("")
+    result = await registry.execute(
+        "read_skill_file",
+        {"name": "test-skill", "path": "scripts"},
+        tool_context,
+    )
+    assert "a.py" in result
+    assert "b.py" in result
+
+
+async def test_read_skill_file_not_found(tool_context: ToolContext, skills_dir: Path):
+    make_skill(skills_dir)
+    result = await registry.execute(
+        "read_skill_file",
+        {"name": "test-skill", "path": "nonexistent.txt"},
+        tool_context,
+    )
+    assert "File not found" in result
+
+
+async def test_read_skill_file_skill_not_found(
+    tool_context: ToolContext, skills_dir: Path
+):
+    result = await registry.execute(
+        "read_skill_file", {"name": "nope", "path": "file.txt"}, tool_context
+    )
+    assert "Skill not found" in result
+
+
+async def test_read_skill_file_path_traversal(
+    tool_context: ToolContext, skills_dir: Path
+):
+    make_skill(skills_dir)
+    result = await registry.execute(
+        "read_skill_file",
+        {"name": "test-skill", "path": "../../etc/passwd"},
+        tool_context,
+    )
+    assert "outside the skill directory" in result
+
+
+async def test_read_skill_file_binary(tool_context: ToolContext, skills_dir: Path):
+    skill_dir = make_skill(skills_dir)
+    (skill_dir / "data.bin").write_bytes(b"\x00\x01\x02\xff\xfe")
+    result = await registry.execute(
+        "read_skill_file",
+        {"name": "test-skill", "path": "data.bin"},
+        tool_context,
+    )
+    assert "Cannot read binary file" in result
+
+
+async def test_install_skill_no_git(tool_context: ToolContext):
+    with patch("docketeer_agentskills.tools.shutil.which", return_value=None):
+        result = await registry.execute(
+            "install_skill", {"url": "https://example.com/repo.git"}, tool_context
+        )
+    assert "git is not installed" in result
+
+
+async def test_install_skill_already_exists(
+    tool_context: ToolContext, skills_dir: Path
+):
+    make_skill(skills_dir, name="existing")
+    result = await registry.execute(
+        "install_skill",
+        {"url": "https://example.com/existing.git", "name": "existing"},
+        tool_context,
+    )
+    assert "already installed" in result
+
+
+async def test_install_skill_clone_failure(tool_context: ToolContext, skills_dir: Path):
+    with patch("docketeer_agentskills.tools.subprocess.run") as mock_run:
+        mock_run.return_value.returncode = 128
+        mock_run.return_value.stderr = "fatal: repo not found"
+        result = await registry.execute(
+            "install_skill",
+            {"url": "https://example.com/bad.git", "name": "bad"},
+            tool_context,
+        )
+    assert "Failed to clone" in result
+    assert not (skills_dir / "bad").exists()
+
+
+async def test_install_skill_no_skill_md(tool_context: ToolContext, skills_dir: Path):
+    def fake_clone(*args: Any, **_kwargs: Any) -> object:
+        clone_dir = Path(args[0][5])
+        clone_dir.mkdir(parents=True, exist_ok=True)
+        (clone_dir / "README.md").write_text("hi")
+
+        class FakeResult:
+            returncode = 0
+            stderr = ""
+
+        return FakeResult()
+
+    with patch("docketeer_agentskills.tools.subprocess.run", side_effect=fake_clone):
+        result = await registry.execute(
+            "install_skill",
+            {"url": "https://example.com/no-skill-md.git", "name": "no-skill-md"},
+            tool_context,
+        )
+    assert "does not contain a SKILL.md" in result
+    assert not (skills_dir / "no-skill-md").exists()
+
+
+async def test_install_skill_invalid_skill_md(
+    tool_context: ToolContext, skills_dir: Path
+):
+    def fake_clone(*args: Any, **_kwargs: Any) -> object:
+        clone_dir = Path(args[0][5])
+        clone_dir.mkdir(parents=True, exist_ok=True)
+        (clone_dir / "SKILL.md").write_text("---\nname: bad-meta\n---\nbody")
+
+        class FakeResult:
+            returncode = 0
+            stderr = ""
+
+        return FakeResult()
+
+    with patch("docketeer_agentskills.tools.subprocess.run", side_effect=fake_clone):
+        result = await registry.execute(
+            "install_skill",
+            {"url": "https://example.com/bad-meta.git", "name": "bad-meta"},
+            tool_context,
+        )
+    assert "Invalid skill" in result
+    assert not (skills_dir / "bad-meta").exists()
+
+
+async def test_install_skill_success(tool_context: ToolContext, skills_dir: Path):
+    def fake_clone(*args: Any, **_kwargs: Any) -> object:
+        clone_dir = Path(args[0][5])
+        clone_dir.mkdir(parents=True, exist_ok=True)
+        (clone_dir / "SKILL.md").write_text(
+            "---\nname: cool-skill\ndescription: Cool stuff\n---\nDo things"
+        )
+
+        class FakeResult:
+            returncode = 0
+            stderr = ""
+
+        return FakeResult()
+
+    with patch("docketeer_agentskills.tools.subprocess.run", side_effect=fake_clone):
+        result = await registry.execute(
+            "install_skill",
+            {"url": "https://example.com/cool-skill.git"},
+            tool_context,
+        )
+    assert "Installed skill 'cool-skill'" in result
+    assert "Cool stuff" in result
+
+
+async def test_install_skill_derives_name_from_url(
+    tool_context: ToolContext, skills_dir: Path
+):
+    def fake_clone(*args: Any, **_kwargs: Any) -> object:
+        clone_dir = Path(args[0][5])
+        clone_dir.mkdir(parents=True, exist_ok=True)
+        (clone_dir / "SKILL.md").write_text(
+            "---\nname: my-repo\ndescription: From URL\n---\nbody"
+        )
+
+        class FakeResult:
+            returncode = 0
+            stderr = ""
+
+        return FakeResult()
+
+    with patch("docketeer_agentskills.tools.subprocess.run", side_effect=fake_clone):
+        result = await registry.execute(
+            "install_skill",
+            {"url": "https://github.com/user/my-repo.git"},
+            tool_context,
+        )
+    assert "Installed skill 'my-repo'" in result
+
+
+async def test_install_skill_with_path(tool_context: ToolContext, skills_dir: Path):
+    def fake_clone(*args: Any, **_kwargs: Any) -> object:
+        clone_target = Path(args[0][5])  # git clone --depth 1 url TARGET
+        clone_target.mkdir(parents=True, exist_ok=True)
+        nested = clone_target / "deep" / "nested" / "humanizer"
+        nested.mkdir(parents=True)
+        (nested / "SKILL.md").write_text(
+            "---\nname: humanizer\ndescription: Humanize text\n---\nMake it human"
+        )
+        (nested / "extra.txt").write_text("bonus file")
+
+        class FakeResult:
+            returncode = 0
+            stderr = ""
+
+        return FakeResult()
+
+    with patch("docketeer_agentskills.tools.subprocess.run", side_effect=fake_clone):
+        result = await registry.execute(
+            "install_skill",
+            {
+                "url": "https://github.com/user/templates.git",
+                "name": "humanizer",
+                "path": "deep/nested/humanizer",
+            },
+            tool_context,
+        )
+    assert "Installed skill 'humanizer'" in result
+    assert "Humanize text" in result
+    assert (skills_dir / "humanizer" / "SKILL.md").exists()
+    assert (skills_dir / "humanizer" / "extra.txt").exists()
+
+
+async def test_install_skill_with_path_no_skill_md(
+    tool_context: ToolContext, skills_dir: Path
+):
+    def fake_clone(*args: Any, **_kwargs: Any) -> object:
+        clone_target = Path(args[0][5])
+        clone_target.mkdir(parents=True, exist_ok=True)
+        nested = clone_target / "some" / "dir"
+        nested.mkdir(parents=True)
+        (nested / "README.md").write_text("not a skill")
+
+        class FakeResult:
+            returncode = 0
+            stderr = ""
+
+        return FakeResult()
+
+    with patch("docketeer_agentskills.tools.subprocess.run", side_effect=fake_clone):
+        result = await registry.execute(
+            "install_skill",
+            {
+                "url": "https://github.com/user/templates.git",
+                "name": "bad",
+                "path": "some/dir",
+            },
+            tool_context,
+        )
+    assert "does not contain a SKILL.md" in result
+    assert not (skills_dir / "bad").exists()
+
+
+async def test_install_skill_with_path_not_found(
+    tool_context: ToolContext, skills_dir: Path
+):
+    def fake_clone(*args: Any, **_kwargs: Any) -> object:
+        clone_target = Path(args[0][5])
+        clone_target.mkdir(parents=True, exist_ok=True)
+
+        class FakeResult:
+            returncode = 0
+            stderr = ""
+
+        return FakeResult()
+
+    with patch("docketeer_agentskills.tools.subprocess.run", side_effect=fake_clone):
+        result = await registry.execute(
+            "install_skill",
+            {
+                "url": "https://github.com/user/templates.git",
+                "name": "missing",
+                "path": "nonexistent/subdir",
+            },
+            tool_context,
+        )
+    assert "not found in repository" in result
+    assert not (skills_dir / "missing").exists()
+
+
+async def test_install_skill_with_path_derives_name(
+    tool_context: ToolContext, skills_dir: Path
+):
+    def fake_clone(*args: Any, **_kwargs: Any) -> object:
+        clone_target = Path(args[0][5])
+        clone_target.mkdir(parents=True, exist_ok=True)
+        nested = clone_target / "skills" / "my-tool"
+        nested.mkdir(parents=True)
+        (nested / "SKILL.md").write_text(
+            "---\nname: my-tool\ndescription: A tool\n---\nbody"
+        )
+
+        class FakeResult:
+            returncode = 0
+            stderr = ""
+
+        return FakeResult()
+
+    with patch("docketeer_agentskills.tools.subprocess.run", side_effect=fake_clone):
+        result = await registry.execute(
+            "install_skill",
+            {
+                "url": "https://github.com/user/templates.git",
+                "path": "skills/my-tool",
+            },
+            tool_context,
+        )
+    assert "Installed skill 'my-tool'" in result
+    assert (skills_dir / "my-tool" / "SKILL.md").exists()
+
+
+async def test_uninstall_skill(tool_context: ToolContext, skills_dir: Path):
+    make_skill(skills_dir, name="doomed")
+    assert (skills_dir / "doomed").exists()
+    result = await registry.execute("uninstall_skill", {"name": "doomed"}, tool_context)
+    assert "Removed skill 'doomed'" in result
+    assert not (skills_dir / "doomed").exists()
+
+
+async def test_uninstall_skill_not_found(tool_context: ToolContext, skills_dir: Path):
+    result = await registry.execute(
+        "uninstall_skill", {"name": "nonexistent"}, tool_context
+    )
+    assert "Skill not found" in result