10xscale-agentflow-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.2}/10xscale_agentflow_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: 10xscale-agentflow-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: CLI and API for 10xscale AgentFlow
 Author-email: 10xscale <contact@10xscale.ai>
 Maintainer-email: Shudipto Trafder <shudiptotrafder@gmail.com>
@@ -31,8 +31,6 @@ Requires-Dist: pydantic-settings
 Requires-Dist: uvicorn
 Requires-Dist: typer
 Requires-Dist: python-dotenv
-Requires-Dist: PyJWT
-Requires-Dist: textxtract[docx,html,md,pdf,xml]>=0.2.0
 Provides-Extra: sentry
 Requires-Dist: sentry-sdk>=2.10.0; extra == "sentry"
 Provides-Extra: firebase
@@ -42,6 +40,10 @@ Provides-Extra: snowflakekit
 Requires-Dist: snowflakekit; extra == "snowflakekit"
 Provides-Extra: redis
 Requires-Dist: redis>=5.0.7; extra == "redis"
+Provides-Extra: jwt
+Requires-Dist: PyJWT; extra == "jwt"
+Provides-Extra: media
+Requires-Dist: textxtract[docx,html,md,pdf,xml]>=0.2.0; extra == "media"
 Provides-Extra: gcloud
 Requires-Dist: google-cloud-logging; extra == "gcloud"
 
@@ -55,6 +57,7 @@ A professional Python API framework for building agent-based applications with F
 - **[Configuration Guide](./docs/configuration.md)** - All configuration options explained
 - **[Deployment Guide](./docs/deployment.md)** - Docker, Kubernetes, and cloud deployment
 - **[Authentication Guide](./docs/authentication.md)** - JWT and custom authentication
+- **[Rate Limiting Guide](./docs/rate-limiting.md)** - Memory, Redis, and custom rate-limit backends
 - **[ID Generation Guide](./docs/id-generation.md)** - Snowflake ID generation
 - **[Thread Name Generator Guide](./docs/thread-name-generator.md)** - Thread naming strategies
 
@@ -66,6 +69,21 @@ A professional Python API framework for building agent-based applications with F
 pip install 10xscale-agentflow-cli
 ```
 
+Redis rate limiting is optional. Install the Redis extra only when you configure
+`rate_limit.backend` as `redis`:
+
+```bash
+pip install "10xscale-agentflow-cli[redis]"
+```
+
+JWT auth and document text extraction are optional too. Install only the extra
+you need:
+
+```bash
+pip install "10xscale-agentflow-cli[jwt]"
+pip install "10xscale-agentflow-cli[media]"
+```
+
 ### Initialize a New Project
 
 ```bash
@@ -100,6 +118,7 @@ agentflow build --docker-compose
 - ✅ **State Graph Orchestration** - Build complex agent workflows with LangGraph
 - ✅ **FastAPI Backend** - High-performance async web framework
 - ✅ **Authentication** - Built-in JWT auth and custom authentication support
+- ✅ **Rate Limiting** - Sliding-window limits with memory, Redis, and custom backends
 - ✅ **ID Generation** - Distributed Snowflake ID generation
 - ✅ **Thread Management** - Intelligent thread naming and conversation management
 - ✅ **Docker Ready** - Generate production-ready Docker files
@@ -221,6 +240,7 @@ The configuration file (`agentflow.json`) defines your agent, authentication, an
 | `injectq` | string\|null | Path to InjectQ container |
 | `store` | string\|null | Path to data store |
 | `redis` | string\|null | Redis connection URL |
+| `rate_limit` | object\|null | Sliding-window rate limiting configuration |
 | `thread_name_generator` | string\|null | Path to custom thread name generator |
 
 See the [Configuration Guide](./docs/configuration.md) for complete details.
@@ -591,4 +611,3 @@ Developed by [10xScale](https://10xscale.ai) and maintained by the community.
 ---
 
 **Made with ❤️ for the AI agent development community**
-

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.2}/10xscale_agentflow_cli.egg-info/SOURCES.txt

@@ -1,8 +1,6 @@
-ActionPlan.md
 MANIFEST.in
 README.md
 agentflow.json
-plan.md
 pyproject.toml
 requirements.txt
 10xscale_agentflow_cli.egg-info/PKG-INFO
@@ -22,6 +20,7 @@ agentflow_cli/cli/commands/__init__.py
 agentflow_cli/cli/commands/api.py
 agentflow_cli/cli/commands/build.py
 agentflow_cli/cli/commands/init.py
+agentflow_cli/cli/commands/skills.py
 agentflow_cli/cli/commands/version.py
 agentflow_cli/cli/core/__init__.py
 agentflow_cli/cli/core/config.py
@@ -29,6 +28,37 @@ agentflow_cli/cli/core/output.py
 agentflow_cli/cli/core/validation.py
 agentflow_cli/cli/templates/__init__.py
 agentflow_cli/cli/templates/defaults.py
+agentflow_cli/cli/templates/skills/agent-skills/SKILL.md
+agentflow_cli/cli/templates/skills/agent-skills/references/agents-and-tools.md
+agentflow_cli/cli/templates/skills/agent-skills/references/api-client.md
+agentflow_cli/cli/templates/skills/agent-skills/references/api-configuration.md
+agentflow_cli/cli/templates/skills/agent-skills/references/api-settings-and-middleware.md
+agentflow_cli/cli/templates/skills/agent-skills/references/architecture.md
+agentflow_cli/cli/templates/skills/agent-skills/references/auth-and-authorization.md
+agentflow_cli/cli/templates/skills/agent-skills/references/callbacks-and-command.md
+agentflow_cli/cli/templates/skills/agent-skills/references/checkpointing-and-threads.md
+agentflow_cli/cli/templates/skills/agent-skills/references/cli-commands.md
+agentflow_cli/cli/templates/skills/agent-skills/references/client-auth-and-errors.md
+agentflow_cli/cli/templates/skills/agent-skills/references/client-messages-invoke-stream.md
+agentflow_cli/cli/templates/skills/agent-skills/references/client-threads-memory-files.md
+agentflow_cli/cli/templates/skills/agent-skills/references/context-id-background.md
+agentflow_cli/cli/templates/skills/agent-skills/references/dependency-injection.md
+agentflow_cli/cli/templates/skills/agent-skills/references/id-and-thread-name-generators.md
+agentflow_cli/cli/templates/skills/agent-skills/references/media-and-files.md
+agentflow_cli/cli/templates/skills/agent-skills/references/memory-and-store.md
+agentflow_cli/cli/templates/skills/agent-skills/references/prebuilt-agents-and-tools.md
+agentflow_cli/cli/templates/skills/agent-skills/references/production-runtime.md
+agentflow_cli/cli/templates/skills/agent-skills/references/providers-and-adapters.md
+agentflow_cli/cli/templates/skills/agent-skills/references/publishers-and-runtime-protocols.md
+agentflow_cli/cli/templates/skills/agent-skills/references/rate-limiting.md
+agentflow_cli/cli/templates/skills/agent-skills/references/remote-tools.md
+agentflow_cli/cli/templates/skills/agent-skills/references/rest-api-and-errors.md
+agentflow_cli/cli/templates/skills/agent-skills/references/security-and-validators.md
+agentflow_cli/cli/templates/skills/agent-skills/references/state-and-messages.md
+agentflow_cli/cli/templates/skills/agent-skills/references/state-graph.md
+agentflow_cli/cli/templates/skills/agent-skills/references/streaming.md
+agentflow_cli/cli/templates/skills/agent-skills/references/testing-and-evaluation.md
+agentflow_cli/cli/templates/skills/copilot/agentflow.instructions.md
 agentflow_cli/src/__init__.py
 agentflow_cli/src/app/__init__.py
 agentflow_cli/src/app/loader.py
@@ -57,6 +87,12 @@ agentflow_cli/src/app/core/exceptions/user_exception.py
 agentflow_cli/src/app/core/middleware/__init__.py
 agentflow_cli/src/app/core/middleware/request_limits.py
 agentflow_cli/src/app/core/middleware/security_headers.py
+agentflow_cli/src/app/core/middleware/rate_limit/__init__.py
+agentflow_cli/src/app/core/middleware/rate_limit/base.py
+agentflow_cli/src/app/core/middleware/rate_limit/factory.py
+agentflow_cli/src/app/core/middleware/rate_limit/memory.py
+agentflow_cli/src/app/core/middleware/rate_limit/middleware.py
+agentflow_cli/src/app/core/middleware/rate_limit/redis.py
 agentflow_cli/src/app/core/utils/__init__.py
 agentflow_cli/src/app/core/utils/log_sanitizer.py
 agentflow_cli/src/app/routers/__init__.py

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.2}/10xscale_agentflow_cli.egg-info/requires.txt

@@ -8,8 +8,6 @@ pydantic-settings
 uvicorn
 typer
 python-dotenv
-PyJWT
-textxtract[docx,html,md,pdf,xml]>=0.2.0
 
 [firebase]
 firebase-admin>=6.5.0
@@ -18,6 +16,12 @@ oauth2client>=4.1.3
 [gcloud]
 google-cloud-logging
 
+[jwt]
+PyJWT
+
+[media]
+textxtract[docx,html,md,pdf,xml]>=0.2.0
+
 [redis]
 redis>=5.0.7
 

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.2}/MANIFEST.in

@@ -6,6 +6,7 @@ include example_weather_agent.py
 recursive-include agentflow_cli *.json
 recursive-include agentflow_cli *.yaml
 recursive-include agentflow_cli *.yml
+recursive-include agentflow_cli *.md
 recursive-include agentflow_cli *.py
 recursive-include src *.json
 recursive-include src *.yaml

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: 10xscale-agentflow-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: CLI and API for 10xscale AgentFlow
 Author-email: 10xscale <contact@10xscale.ai>
 Maintainer-email: Shudipto Trafder <shudiptotrafder@gmail.com>
@@ -31,8 +31,6 @@ Requires-Dist: pydantic-settings
 Requires-Dist: uvicorn
 Requires-Dist: typer
 Requires-Dist: python-dotenv
-Requires-Dist: PyJWT
-Requires-Dist: textxtract[docx,html,md,pdf,xml]>=0.2.0
 Provides-Extra: sentry
 Requires-Dist: sentry-sdk>=2.10.0; extra == "sentry"
 Provides-Extra: firebase
@@ -42,6 +40,10 @@ Provides-Extra: snowflakekit
 Requires-Dist: snowflakekit; extra == "snowflakekit"
 Provides-Extra: redis
 Requires-Dist: redis>=5.0.7; extra == "redis"
+Provides-Extra: jwt
+Requires-Dist: PyJWT; extra == "jwt"
+Provides-Extra: media
+Requires-Dist: textxtract[docx,html,md,pdf,xml]>=0.2.0; extra == "media"
 Provides-Extra: gcloud
 Requires-Dist: google-cloud-logging; extra == "gcloud"
 
@@ -55,6 +57,7 @@ A professional Python API framework for building agent-based applications with F
 - **[Configuration Guide](./docs/configuration.md)** - All configuration options explained
 - **[Deployment Guide](./docs/deployment.md)** - Docker, Kubernetes, and cloud deployment
 - **[Authentication Guide](./docs/authentication.md)** - JWT and custom authentication
+- **[Rate Limiting Guide](./docs/rate-limiting.md)** - Memory, Redis, and custom rate-limit backends
 - **[ID Generation Guide](./docs/id-generation.md)** - Snowflake ID generation
 - **[Thread Name Generator Guide](./docs/thread-name-generator.md)** - Thread naming strategies
 
@@ -66,6 +69,21 @@ A professional Python API framework for building agent-based applications with F
 pip install 10xscale-agentflow-cli
 ```
 
+Redis rate limiting is optional. Install the Redis extra only when you configure
+`rate_limit.backend` as `redis`:
+
+```bash
+pip install "10xscale-agentflow-cli[redis]"
+```
+
+JWT auth and document text extraction are optional too. Install only the extra
+you need:
+
+```bash
+pip install "10xscale-agentflow-cli[jwt]"
+pip install "10xscale-agentflow-cli[media]"
+```
+
 ### Initialize a New Project
 
 ```bash
@@ -100,6 +118,7 @@ agentflow build --docker-compose
 - ✅ **State Graph Orchestration** - Build complex agent workflows with LangGraph
 - ✅ **FastAPI Backend** - High-performance async web framework
 - ✅ **Authentication** - Built-in JWT auth and custom authentication support
+- ✅ **Rate Limiting** - Sliding-window limits with memory, Redis, and custom backends
 - ✅ **ID Generation** - Distributed Snowflake ID generation
 - ✅ **Thread Management** - Intelligent thread naming and conversation management
 - ✅ **Docker Ready** - Generate production-ready Docker files
@@ -221,6 +240,7 @@ The configuration file (`agentflow.json`) defines your agent, authentication, an
 | `injectq` | string\|null | Path to InjectQ container |
 | `store` | string\|null | Path to data store |
 | `redis` | string\|null | Redis connection URL |
+| `rate_limit` | object\|null | Sliding-window rate limiting configuration |
 | `thread_name_generator` | string\|null | Path to custom thread name generator |
 
 See the [Configuration Guide](./docs/configuration.md) for complete details.
@@ -591,4 +611,3 @@ Developed by [10xScale](https://10xscale.ai) and maintained by the community.
 ---
 
 **Made with ❤️ for the AI agent development community**
-

{10xscale_agentflow_cli-0.3.0 → 10xscale_agentflow_cli-0.3.2}/README.md

@@ -8,6 +8,7 @@ A professional Python API framework for building agent-based applications with F
 - **[Configuration Guide](./docs/configuration.md)** - All configuration options explained
 - **[Deployment Guide](./docs/deployment.md)** - Docker, Kubernetes, and cloud deployment
 - **[Authentication Guide](./docs/authentication.md)** - JWT and custom authentication
+- **[Rate Limiting Guide](./docs/rate-limiting.md)** - Memory, Redis, and custom rate-limit backends
 - **[ID Generation Guide](./docs/id-generation.md)** - Snowflake ID generation
 - **[Thread Name Generator Guide](./docs/thread-name-generator.md)** - Thread naming strategies
 
@@ -19,6 +20,21 @@ A professional Python API framework for building agent-based applications with F
 pip install 10xscale-agentflow-cli
 ```
 
+Redis rate limiting is optional. Install the Redis extra only when you configure
+`rate_limit.backend` as `redis`:
+
+```bash
+pip install "10xscale-agentflow-cli[redis]"
+```
+
+JWT auth and document text extraction are optional too. Install only the extra
+you need:
+
+```bash
+pip install "10xscale-agentflow-cli[jwt]"
+pip install "10xscale-agentflow-cli[media]"
+```
+
 ### Initialize a New Project
 
 ```bash
@@ -53,6 +69,7 @@ agentflow build --docker-compose
 - ✅ **State Graph Orchestration** - Build complex agent workflows with LangGraph
 - ✅ **FastAPI Backend** - High-performance async web framework
 - ✅ **Authentication** - Built-in JWT auth and custom authentication support
+- ✅ **Rate Limiting** - Sliding-window limits with memory, Redis, and custom backends
 - ✅ **ID Generation** - Distributed Snowflake ID generation
 - ✅ **Thread Management** - Intelligent thread naming and conversation management
 - ✅ **Docker Ready** - Generate production-ready Docker files
@@ -174,6 +191,7 @@ The configuration file (`agentflow.json`) defines your agent, authentication, an
 | `injectq` | string\|null | Path to InjectQ container |
 | `store` | string\|null | Path to data store |
 | `redis` | string\|null | Redis connection URL |
+| `rate_limit` | object\|null | Sliding-window rate limiting configuration |
 | `thread_name_generator` | string\|null | Path to custom thread name generator |
 
 See the [Configuration Guide](./docs/configuration.md) for complete details.
@@ -544,4 +562,3 @@ Developed by [10xScale](https://10xscale.ai) and maintained by the community.
 ---
 
 **Made with ❤️ for the AI agent development community**
-

10xscale_agentflow_cli-0.3.2/agentflow.json

@@ -0,0 +1,15 @@
+{
+  "agent": "graph.react:app",
+  "thread_name_generator": "graph.thread_name_generator:MyNameGenerator",
+  "env": ".env",
+  "auth": null,
+  "rate_limit": {
+    "enabled": true,
+    "backend": "memory",
+    "requests": 100,
+    "window": 60,
+    "by": "ip",
+    "trusted_proxy_headers": false,
+    "exclude_paths": ["/health", "/docs", "/redoc", "/openapi.json"]
+  }
+}

10xscale_agentflow_cli-0.3.2/agentflow_cli/cli/commands/skills.py

@@ -0,0 +1,306 @@
+"""Skills command implementation."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+import typer
+
+from agentflow_cli.cli.commands import BaseCommand
+from agentflow_cli.cli.constants import CLI_VERSION
+from agentflow_cli.cli.exceptions import FileOperationError, ValidationError
+
+
+_MANIFEST_FILENAME = ".agentflow-skill.json"
+
+
+@dataclass(frozen=True)
+class _InstallArtifact:
+    """Describes one file or folder installed for an agent."""
+
+    kind: Literal["folder", "file"]
+    install_relpath: str
+    source_relpath: str
+    manifest: bool = False
+
+
+@dataclass(frozen=True)
+class _AgentTarget:
+    """Describes how the bundled skill is materialised for one agent."""
+
+    name: str
+    artifacts: tuple[_InstallArtifact, ...]
+
+    @property
+    def kind(self) -> str:
+        kinds = {artifact.kind for artifact in self.artifacts}
+        if len(kinds) == 1:
+            return next(iter(kinds))
+        return "file+folder"
+
+
+_TARGETS: tuple[_AgentTarget, ...] = (
+    _AgentTarget(
+        name="Codex",
+        artifacts=(
+            _InstallArtifact(
+                kind="folder",
+                install_relpath=".agents/skills/agentflow",
+                source_relpath="agent-skills",
+                manifest=True,
+            ),
+        ),
+    ),
+    _AgentTarget(
+        name="Claude",
+        artifacts=(
+            _InstallArtifact(
+                kind="folder",
+                install_relpath=".claude/skills/agentflow",
+                source_relpath="agent-skills",
+                manifest=True,
+            ),
+        ),
+    ),
+    _AgentTarget(
+        name="GitHub",
+        artifacts=(
+            _InstallArtifact(
+                kind="file",
+                install_relpath=".github/instructions/agentflow.instructions.md",
+                source_relpath="copilot/agentflow.instructions.md",
+            ),
+            _InstallArtifact(
+                kind="folder",
+                install_relpath=".github/skills/agentflow",
+                source_relpath="agent-skills",
+                manifest=True,
+            ),
+        ),
+    ),
+)
+
+_AGENT_LOOKUP: dict[str, _AgentTarget] = {
+    **{t.name.lower(): t for t in _TARGETS},
+    "1": _TARGETS[0],
+    "2": _TARGETS[1],
+    "3": _TARGETS[2],
+}
+
+
+class SkillsCommand(BaseCommand):
+    """Command to install bundled Agentflow skills for supported agents."""
+
+    def execute(
+        self,
+        agent: str | None = None,
+        path: str = ".",
+        force: bool = False,
+        all_agents: bool = False,
+        list_agents: bool = False,
+        **kwargs: Any,
+    ) -> int:
+        """Execute the skills command.
+
+        Args:
+            agent: Target agent name or menu number.
+            path: Project directory where the agent skill should be installed.
+            force: Overwrite an existing installation.
+            all_agents: Install for every supported agent.
+            list_agents: Print supported agents and exit.
+            **kwargs: Additional arguments.
+
+        Returns:
+            Exit code.
+        """
+        try:
+            self.output.print_banner(
+                "Skills",
+                "Install bundled Agentflow skills for Codex, Claude, or GitHub Copilot.",
+                color="magenta",
+            )
+
+            if list_agents:
+                self._print_agents()
+                return 0
+
+            if all_agents and agent:
+                raise ValidationError("--all cannot be combined with --agent.", field="agent")
+
+            templates_root = self._templates_root()
+            project_root = self._safe_project_root(path)
+
+            if all_agents:
+                return self._install_all(templates_root, project_root, force=force)
+
+            target = self._select_agent(agent)
+            self._install_one(templates_root, project_root, target, force=force)
+            return 0
+
+        except (FileOperationError, ValidationError) as e:
+            return self.handle_error(e)
+        except OSError as e:
+            file_error = FileOperationError(f"Failed to install Agentflow skills: {e}")
+            file_error.__cause__ = e
+            return self.handle_error(file_error)
+
+    def _install_one(
+        self,
+        templates_root: Path,
+        project_root: Path,
+        target: _AgentTarget,
+        *,
+        force: bool,
+    ) -> None:
+        installs = [
+            (
+                artifact,
+                templates_root / artifact.source_relpath,
+                project_root / artifact.install_relpath,
+            )
+            for artifact in target.artifacts
+        ]
+        for _artifact, source, _dest in installs:
+            if not source.exists():
+                raise FileOperationError(
+                    f"Bundled skills template not found: {source}", file_path=str(source)
+                )
+
+        existing = [dest for _artifact, _source, dest in installs if dest.exists()]
+        if existing and not force:
+            paths = ", ".join(str(dest) for dest in existing)
+            raise FileOperationError(
+                f"Skill already installed at {paths}. Use --force to overwrite.",
+                file_path=str(existing[0]),
+            )
+
+        for _artifact, _source, dest in installs:
+            if dest.exists():
+                if dest.is_dir():
+                    shutil.rmtree(dest)
+                else:
+                    dest.unlink()
+
+        installed_paths: list[str] = []
+        for artifact, source, dest in installs:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+
+            if artifact.kind == "folder":
+                shutil.copytree(
+                    source,
+                    dest,
+                    ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store"),
+                )
+                if artifact.manifest:
+                    self._write_manifest(dest, target.name)
+            else:
+                shutil.copyfile(source, dest)
+            installed_paths.append(str(dest))
+
+        self.output.success(
+            f"Installed Agentflow skills for {target.name} at {', '.join(installed_paths)}"
+        )
+
+    def _install_all(self, templates_root: Path, project_root: Path, *, force: bool) -> int:
+        installed = 0
+        skipped: list[str] = []
+        failed: list[str] = []
+        for target in _TARGETS:
+            existing = [
+                project_root / artifact.install_relpath
+                for artifact in target.artifacts
+                if (project_root / artifact.install_relpath).exists()
+            ]
+            if existing and not force:
+                paths = ", ".join(str(dest) for dest in existing)
+                skipped.append(f"{target.name} ({paths})")
+                continue
+            try:
+                self._install_one(templates_root, project_root, target, force=force)
+                installed += 1
+            except (FileOperationError, OSError, UnicodeError) as e:
+                self.logger.error("Install failed for %s: %s", target.name, e)
+                failed.append(f"{target.name}: {e}")
+
+        if skipped:
+            self.output.warning(
+                "Skipped existing installs (use --force to overwrite): " + ", ".join(skipped)
+            )
+        if failed:
+            self.output.error("Failed installs: " + "; ".join(failed))
+
+        if failed and installed == 0:
+            return 1
+        return 0
+
+    def _write_manifest(self, target_dir: Path, agent_name: str) -> None:
+        manifest = {
+            "agent": agent_name,
+            "cli_version": CLI_VERSION,
+            "installed_at": datetime.now(UTC).isoformat(timespec="seconds"),
+        }
+        (target_dir / _MANIFEST_FILENAME).write_text(
+            json.dumps(manifest, indent=2) + "\n", encoding="utf-8"
+        )
+
+    def _print_agents(self) -> None:
+        rows = [
+            [t.name, t.kind, ", ".join(a.install_relpath for a in t.artifacts)] for t in _TARGETS
+        ]
+        self.output.print_table(
+            ["Agent", "Kind", "Install path (relative to --path)"],
+            rows,
+            title="Supported agents",
+        )
+
+    def _safe_project_root(self, path: str) -> Path:
+        project_root = Path(path).resolve()
+        if project_root.parent == project_root:
+            raise ValidationError(
+                f"Refusing to install skills at filesystem root: {project_root}",
+                field="path",
+            )
+        if project_root == Path.home().resolve():
+            raise ValidationError(
+                f"Refusing to install skills directly into the home directory: {project_root}. "
+                "Pass --path pointing at a project directory.",
+                field="path",
+            )
+        return project_root
+
+    def _select_agent(self, agent: str | None) -> _AgentTarget:
+        if agent:
+            return self._normalize_agent(agent)
+
+        if not sys.stdin.isatty():
+            raise ValidationError(
+                "No --agent provided and stdin is not interactive. "
+                "Pass --agent codex|claude|github or --all.",
+                field="agent",
+            )
+
+        self.output.print_list(
+            [f"{i}. {t.name}" for i, t in enumerate(_TARGETS, 1)],
+            title="Which agent?",
+            bullet="-",
+        )
+        selected = typer.prompt("Select an agent", default="1")
+        return self._normalize_agent(selected)
+
+    def _normalize_agent(self, value: str) -> _AgentTarget:
+        key = value.strip().lower()
+        if key in _AGENT_LOOKUP:
+            return _AGENT_LOOKUP[key]
+
+        valid = "Codex, Claude, GitHub, or 1, 2, 3"
+        raise ValidationError(f"Invalid agent '{value}'. Choose {valid}.", field="agent")
+
+    def _templates_root(self) -> Path:
+        cli_dir = Path(__file__).resolve().parents[1]
+        return cli_dir / "templates" / "skills"