Merge pull request #4 from shinpr/fix/skillshield-security-findings

Fix path traversal, Python 3.9 compat, and SKILL.md refinement

Author: shinpr

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.9', '3.10', '3.11', '3.12']
 
     steps:
       - uses: actions/checkout@v4

README.md

@@ -23,7 +23,7 @@ Most major AI coding agents now have built-in sub-agents — but only for their
 This skill removes that restriction:
 
 - **Cross-LLM orchestration** — Use Claude for long-chain reasoning, Codex for fast refactors, and Gemini for large-context analysis, all from the same parent session.
-- **No vendor lock-in** — Your agent definitions are plain markdown files that work across any Agent Skills-compatible tool, so switching IDEs or LLM providers doesn't mean rewriting your workflow.
+- **No vendor lock-in** — Your agent definitions are plain markdown files that work with Codex, Claude Code, Cursor, Gemini CLI, VS Code, and [30+ other tools](https://agentskills.io) that support the Agent Skills format, so switching IDEs or LLM providers doesn't mean rewriting your workflow.
 - **Bring Your Own Model** — Choose which model handles each task and pay each provider directly at their API rates.
 - **Team portability** — Share agent definitions across your team regardless of IDE or preferred LLM.
 
@@ -48,7 +48,7 @@ You only need to install the backends you plan to use.
 
 ## Quick Start
 
-**Requirements:** Python 3.10+ and at least one [supported backend](#supported-backends) installed.
+**Requirements:** Python 3.9+ and at least one [supported backend](#supported-backends) installed.
 
 ### 1. Install the Skill
 
@@ -317,7 +317,7 @@ The main agent stays lightweight too. It coordinates work without accumulating a
 
 ### Agent Skills as an Open Standard
 
-This skill uses the [Agent Skills](https://github.com/anthropics/skills) format—a convention for packaging reusable AI agent capabilities as portable files. The format is supported by Claude Code, Codex, and other Agent Skills-compatible tools, so the same skill works across environments without modification.
+This skill uses the [Agent Skills](https://agentskills.io) format—a convention for packaging reusable AI agent capabilities as portable files. The format is supported by Codex, Claude Code, Cursor, Gemini CLI, and [30+ other tools](https://agentskills.io), so the same skill works across environments without modification.
 
 ## How It Works
 
@@ -329,7 +329,7 @@ skills/sub-agents/
 ├── scripts/
 │   └── run_subagent.py   # Calls external CLIs
 └── references/
-    └── cli-formats.md    # CLI output format docs
+    └── codex.md          # Codex-specific setup docs
 ```
 
 ## License

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "sub-agents-skills"
 version = "0.1.0"
-requires-python = ">=3.11"
+requires-python = ">=3.9"
 dependencies = []
 
 [project.optional-dependencies]
@@ -11,7 +11,7 @@ dev = [
 ]
 
 [tool.ruff]
-target-version = "py311"
+target-version = "py39"
 line-length = 100
 
 [tool.ruff.lint]
@@ -27,6 +27,7 @@ select = [
 ]
 ignore = [
     "E501",   # line too long (handled by formatter)
+    "SIM117", # nested with — combining requires parenthesized syntax (3.10+)
 ]
 
 [tool.ruff.format]

skills/sub-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sub-agents
-description: Execute external CLI AIs as isolated sub-agents for task delegation, parallel processing, and context separation. Use when delegating complex multi-step tasks, running parallel investigations, needing fresh context without current conversation history, or leveraging specialized agent definitions. Returns structured JSON with agent output, exit code, and execution status.
+description: Run agent definitions as sub-agents. Use when the user names an agent or sub-agent to run, references an agent definition, or delegates a task to an agent.
 allowed-tools: Bash Read
 ---
 
@@ -40,14 +40,6 @@ Extract parameters from user's natural language request:
 "Run code-reviewer on src/"
 → `--agent code-reviewer --prompt "Review src/" --cwd $(pwd)`
 
-## When to Use This Skill
-
-**Use sub-agent when ANY of these apply:**
-- Complex multi-step task (isolated context prevents interference)
-- Parallel investigation (multiple agents can run simultaneously)
-- Task needs fresh context (sub-agent starts without conversation history)
-- Specialized agent definition exists (leverage pre-defined expert prompts)
-
 ## Important: Permission and Timeout
 
 This script executes external CLIs that require elevated permissions.
@@ -158,7 +150,7 @@ What this agent does.
 How results should be structured.
 ```
 
-**Critical**: The `run-agent` frontmatter determines which CLI executes the agent. See [cli-formats.md](references/cli-formats.md) for CLI-specific behaviors.
+**Critical**: The `run-agent` frontmatter determines which CLI executes the agent.
 
 ## CLI Selection Priority
 

skills/sub-agents/scripts/run_subagent.py

@@ -12,6 +12,8 @@
     SUB_AGENTS_DIR: Override default agents directory ({cwd}/.agents/)
 """
 
+from __future__ import annotations
+
 import argparse
 import json
 import os
@@ -59,18 +61,36 @@ def extract_description(body: str) -> str:
     return ""
 
 
+_AGENT_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]*$")
+
+
+def validate_agent_name(agent_name: str) -> str:
+    """
+    Validate agent name to prevent path traversal.
+    Returns the name if valid, raises ValueError otherwise.
+    """
+    if not agent_name or not _AGENT_NAME_PATTERN.match(agent_name):
+        raise ValueError(f"Invalid agent name: {agent_name!r}")
+    return agent_name
+
+
 def load_agent(agents_dir: str, agent_name: str) -> tuple[str | None, str, str]:
     """
     Load agent definition file and extract run-agent setting.
     Returns (run_agent_cli, system_context, description)
     """
+    validate_agent_name(agent_name)
     agents_path = Path(agents_dir)
 
     # Try .md first, then .txt
     for ext in [".md", ".txt"]:
         agent_file = agents_path / f"{agent_name}{ext}"
-        if agent_file.exists():
-            content = agent_file.read_text(encoding="utf-8")
+        # Defense in depth: verify resolved path stays within agents_dir
+        resolved = agent_file.resolve()
+        if not str(resolved).startswith(str(agents_path.resolve())):
+            raise ValueError(f"Invalid agent name: {agent_name!r}")
+        if resolved.exists():
+            content = resolved.read_text(encoding="utf-8")
             frontmatter, body = parse_frontmatter(content)
 
             run_agent = frontmatter.get("run-agent")

tests/test_run_subagent.py

@@ -50,6 +50,74 @@ def test_without_frontmatter(self):
         assert body == content
 
 
+class TestLoadAgentRejectsInvalidNames:
+    """load_agent should reject names that could escape the agents directory."""
+
+    def _make_agents_dir(self, tmpdir):
+        agents_dir = Path(tmpdir) / "agents"
+        agents_dir.mkdir()
+        (agents_dir / "valid-agent.md").write_text("# Valid\n\nA valid agent.")
+        return str(agents_dir)
+
+    # --- Valid names load successfully ---
+
+    def test_loads_simple_hyphenated_name(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            agents_dir = self._make_agents_dir(tmpdir)
+            _, context, _ = load_agent(agents_dir, "valid-agent")
+            assert "Valid" in context
+
+    # --- Path traversal attempts are rejected ---
+
+    def test_rejects_parent_directory_traversal(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            agents_dir = self._make_agents_dir(tmpdir)
+            with pytest.raises(ValueError, match="Invalid agent name"):
+                load_agent(agents_dir, "../etc/passwd")
+
+    def test_rejects_nested_traversal(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            agents_dir = self._make_agents_dir(tmpdir)
+            with pytest.raises(ValueError, match="Invalid agent name"):
+                load_agent(agents_dir, "../../secret")
+
+    def test_rejects_absolute_path(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            agents_dir = self._make_agents_dir(tmpdir)
+            with pytest.raises(ValueError, match="Invalid agent name"):
+                load_agent(agents_dir, "/etc/passwd")
+
+    def test_rejects_forward_slash(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            agents_dir = self._make_agents_dir(tmpdir)
+            with pytest.raises(ValueError, match="Invalid agent name"):
+                load_agent(agents_dir, "sub/agent")
+
+    def test_rejects_backslash(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            agents_dir = self._make_agents_dir(tmpdir)
+            with pytest.raises(ValueError, match="Invalid agent name"):
+                load_agent(agents_dir, "sub\\agent")
+
+    def test_rejects_empty_string(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            agents_dir = self._make_agents_dir(tmpdir)
+            with pytest.raises(ValueError, match="Invalid agent name"):
+                load_agent(agents_dir, "")
+
+    def test_rejects_shell_metacharacters(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            agents_dir = self._make_agents_dir(tmpdir)
+            with pytest.raises(ValueError, match="Invalid agent name"):
+                load_agent(agents_dir, "agent;rm -rf")
+
+    def test_rejects_leading_dot(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            agents_dir = self._make_agents_dir(tmpdir)
+            with pytest.raises(ValueError, match="Invalid agent name"):
+                load_agent(agents_dir, ".hidden")
+
+
 class TestLoadAgent:
     def test_load_agent_md(self):
         with tempfile.TemporaryDirectory() as tmpdir: