Skip to content

Create, Evaluate, and Connect AI Skills

update downloader

Jiang Chen9843758cf825
diff --git a/README.md b/README.md
index 6373dc6..1dc75d0 100644
--- a/README.md
+++ b/README.md
@@ -266,6 +266,9 @@ skillnet search "visualization" --category "Development" --sort-by stars --limit
skillnet download https://github.com/anthropics/skills/tree/main/skills/algorithmic-art
skillnet download <url> -d ./my_agent/skills
skillnet download <private_url> --token <your_github_token>
+
+# Use a mirror for faster downloads in China
+skillnet download <url> --mirror https://ghfast.top/
```
### Create
@@ -306,11 +309,12 @@ skillnet analyze ./my_agent_skills --model gpt-4o
### Environment Variables
-| Variable | Required For | Default |
-| :------------- | :--------------------------------- | :-------------------------- |
-| `API_KEY` | `create` · `evaluate` · `analyze` | — |
-| `BASE_URL` | Custom LLM endpoint | `https://api.openai.com/v1` |
-| `GITHUB_TOKEN` | Private repos / higher rate limits | — |
+| Variable | Required For | Default |
+| :--------------- | :--------------------------------- | :-------------------------- |
+| `API_KEY` | `create` · `evaluate` · `analyze` | — |
+| `BASE_URL` | Custom LLM endpoint | `https://api.openai.com/v1` |
+| `GITHUB_TOKEN` | Private repos / higher rate limits | — |
+| `GITHUB_MIRROR` | Faster downloads in restricted networks | — |
> `search` and `download` (public repos) work without any credentials.
diff --git a/skillnet-ai/README.md b/skillnet-ai/README.md
index 2a0c33f..a481e82 100644
--- a/skillnet-ai/README.md
+++ b/skillnet-ai/README.md
@@ -194,6 +194,9 @@ skillnet search "visualization" --category "Development" --sort-by stars --limit
skillnet download https://github.com/anthropics/skills/tree/main/skills/algorithmic-art
skillnet download <url> -d ./my_agent/skills
skillnet download <private_url> --token <your_github_token>
+
+# Use a mirror for faster downloads in China
+skillnet download <url> --mirror https://ghfast.top/
```
### Create
@@ -228,11 +231,12 @@ skillnet analyze ./my_skills --model gpt-4o
### Environment Variables
-| Variable | Required For | Default |
-| :------------- | :--------------------------------- | :-------------------------- |
-| `API_KEY` | `create` · `evaluate` · `analyze` | — |
-| `BASE_URL` | Custom LLM endpoint | `https://api.openai.com/v1` |
-| `GITHUB_TOKEN` | Private repos / higher rate limits | — |
+| Variable | Required For | Default |
+| :--------------- | :--------------------------------- | :-------------------------- |
+| `API_KEY` | `create` · `evaluate` · `analyze` | — |
+| `BASE_URL` | Custom LLM endpoint | `https://api.openai.com/v1` |
+| `GITHUB_TOKEN` | Private repos / higher rate limits | — |
+| `GITHUB_MIRROR` | Faster downloads in restricted networks | — |
> `search` and `download` (public repos) require **no credentials at all**.
diff --git a/skillnet-ai/src/skillnet_ai/cli.py b/skillnet-ai/src/skillnet_ai/cli.py
index 38e7f26..c3e4c05 100644
--- a/skillnet-ai/src/skillnet_ai/cli.py
+++ b/skillnet-ai/src/skillnet_ai/cli.py
@@ -121,13 +121,14 @@ def download(
url: str = typer.Argument(..., help="The GitHub URL of the specific skill folder (e.g., https://github.com/owner/repo/tree/main/skills/math_solver)."),
target_dir: str = typer.Option(".", "--target-dir", "-d", help="Local directory to install the skill into."),
token: str = typer.Option(None, "--token", "-t", envvar="GITHUB_TOKEN", help="GitHub Personal Access Token (for private repos or higher rate limits)."),
+ mirror: str = typer.Option(None, "--mirror", "-m", help="Mirror URL for fallback when GitHub is slow/unavailable (e.g. https://ghfast.top/). Also reads GITHUB_MIRROR env var."),
):
"""
Download and install a specific skill directly from a GitHub repository subdirectory.
"""
# 1. Initialize Downloader
# Checks CLI option first, then environment variable GITHUB_TOKEN
- downloader = SkillDownloader(api_token=token)
+ downloader = SkillDownloader(api_token=token, mirror_url=mirror)
try:
# 2. Visual Feedback
diff --git a/skillnet-ai/src/skillnet_ai/client.py b/skillnet-ai/src/skillnet_ai/client.py
index ccc7651..c2b87a3 100644
--- a/skillnet-ai/src/skillnet_ai/client.py
+++ b/skillnet-ai/src/skillnet_ai/client.py
@@ -86,7 +86,8 @@ class SkillNetClient:
self,
url: str,
target_dir: str = ".",
- token: Optional[str] = None
+ token: Optional[str] = None,
+ mirror_url: Optional[str] = None,
) -> str:
"""
Download a skill from a GitHub URL.
@@ -95,6 +96,9 @@ class SkillNetClient:
url: The GitHub URL of the specific skill folder.
target_dir: Local directory to install into.
token: Optional override for GitHub token.
+ mirror_url: Mirror URL for fallback when GitHub is slow/unavailable.
+ Configure via GITHUB_MIRROR env var or pass explicitly.
+ Example mirrors: https://ghfast.top/, https://ghproxy.com/
Returns:
str: The absolute path to the installed skill folder.
@@ -104,7 +108,7 @@ class SkillNetClient:
"""
# Use instance token if specific token not provided
use_token = token if token else self.github_token
- downloader = SkillDownloader(api_token=use_token)
+ downloader = SkillDownloader(api_token=use_token, mirror_url=mirror_url)
try:
installed_path = downloader.download(folder_url=url, target_dir=target_dir)
diff --git a/skillnet-ai/src/skillnet_ai/downloader.py b/skillnet-ai/src/skillnet_ai/downloader.py
index 46f61b2..7db7ed9 100644
--- a/skillnet-ai/src/skillnet_ai/downloader.py
+++ b/skillnet-ai/src/skillnet_ai/downloader.py
@@ -1,4 +1,5 @@
import os
+import time
import logging
import requests
from typing import Optional, List, Dict, Tuple
@@ -20,17 +21,42 @@ class SkillDownloader:
"""
A class to handle downloading specific subdirectories from GitHub repositories
and installing them as local skills.
+
+ Supports configurable timeout, retry with exponential backoff, and automatic
+ fallback to a mirror when the primary GitHub source is slow or unavailable.
"""
- def __init__(self, api_token: Optional[str] = None):
+ def __init__(
+ self,
+ api_token: Optional[str] = None,
+ mirror_url: Optional[str] = None,
+ timeout: int = 15,
+ max_retries: int = 3,
+ ):
"""
Initializes the SkillDownloader.
Args:
- api_token (Optional[str]): GitHub Personal Access Token to increase
- rate limits and access private repositories.
+ api_token: GitHub Personal Access Token to increase rate limits
+ and access private repositories.
+ mirror_url: Mirror URL for fallback when GitHub is slow/unavailable.
+ Priority: explicit parameter > GITHUB_MIRROR env var.
+ Not set by default; users in China can configure via
+ GITHUB_MIRROR env var or --mirror CLI flag.
+ Example mirrors: https://ghfast.top/, https://ghproxy.com/
+ timeout: Request timeout in seconds (default 15).
+ max_retries: Maximum retry attempts per request (default 3).
"""
self.api_token = api_token
+ self.timeout = timeout
+ self.max_retries = max_retries
+
+ # Mirror resolution: explicit param > env var > None (no mirror)
+ if mirror_url is not None:
+ self.mirror_url = mirror_url
+ else:
+ self.mirror_url = os.getenv("GITHUB_MIRROR", "")
+
self.session = requests.Session()
self.session.headers.update({
"Accept": "application/vnd.github.v3+json"
@@ -39,6 +65,9 @@ class SkillDownloader:
if self.api_token:
self.session.headers.update({"Authorization": f"token {self.api_token}"})
+ if self.mirror_url:
+ logger.info(f"Mirror fallback enabled: {self.mirror_url}")
+
def download(self, folder_url: str, target_dir: str = ".") -> Optional[str]:
"""
Downloads a specific GitHub subdirectory or file to the target directory.
@@ -107,6 +136,71 @@ class SkillDownloader:
logger.error(f"Critical error during skill installation: {e}")
return None
+ def _request_with_retry(
+ self,
+ url: str,
+ timeout: Optional[int] = None,
+ max_retries: Optional[int] = None,
+ base_delay: float = 1.0,
+ ) -> Optional[requests.Response]:
+ """HTTP GET with configurable timeout and exponential-backoff retry."""
+ timeout = timeout if timeout is not None else self.timeout
+ max_retries = max_retries if max_retries is not None else self.max_retries
+
+ for attempt in range(1, max_retries + 1):
+ try:
+ response = self.session.get(url, timeout=timeout)
+
+ # Handle GitHub rate-limit (403 with remaining == 0)
+ if response.status_code == 403:
+ remaining = response.headers.get("X-RateLimit-Remaining", "?")
+ if remaining == "0":
+ reset_time = int(response.headers.get("X-RateLimit-Reset", 0))
+ wait_seconds = max(0, reset_time - int(time.time()))
+ logger.warning(f"GitHub rate limit exceeded. Resets in {wait_seconds}s")
+ if wait_seconds < 60:
+ time.sleep(wait_seconds + 1)
+ continue
+
+ return response
+
+ except requests.exceptions.Timeout:
+ if attempt < max_retries:
+ delay = base_delay * (2 ** (attempt - 1))
+ logger.warning(f"Timeout (attempt {attempt}/{max_retries}), retry in {delay:.1f}s: {url}")
+ time.sleep(delay)
+ else:
+ logger.error(f"Request timed out after {max_retries} attempts: {url}")
+ return None
+
+ except requests.exceptions.ConnectionError:
+ if attempt < max_retries:
+ delay = base_delay * (2 ** (attempt - 1))
+ logger.warning(f"Connection error (attempt {attempt}/{max_retries}), retry in {delay:.1f}s: {url}")
+ time.sleep(delay)
+ else:
+ logger.error(f"Connection failed after {max_retries} attempts: {url}")
+ return None
+
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ return None
+
+ return None
+
+ def _build_mirror_url(self, original_url: str) -> Optional[str]:
+ """
+ Build a mirror URL by prepending the configured mirror prefix.
+ Returns None if no mirror is configured or the URL is not a raw GitHub URL.
+ """
+ if not self.mirror_url:
+ return None
+ if "raw.githubusercontent.com" not in original_url:
+ return None
+
+ mirror = self.mirror_url.rstrip("/")
+ return f"{mirror}/{original_url}"
+
def _parse_github_url(self, url: str) -> Optional[Tuple[str, str, str, str, str]]:
"""
Parses a standard GitHub tree or blob URL into its constituent components.
@@ -150,7 +244,11 @@ class SkillDownloader:
api_url = f"https://api.github.com/repos/{owner}/{repo}/contents/{dir_path}?ref={ref}"
try:
- response = self.session.get(api_url)
+ response = self._request_with_retry(api_url)
+
+ if response is None:
+ logger.error(f"GitHub API request failed after retries: {api_url}")
+ raise GitHubAPIError(0, "Request failed after retries (timeout or connection error)")
if response.status_code != 200:
error_msg = response.text
@@ -239,18 +337,17 @@ class SkillDownloader:
# Ensure parent directories exist
os.makedirs(os.path.dirname(local_file_path), exist_ok=True)
-
- try:
- response = self.session.get(raw_url)
-
- if response.status_code == 200:
- with open(local_file_path, "wb") as f:
- f.write(response.content)
- return True
- else:
- logger.warning(f"Failed to download {raw_url} - HTTP Status: {response.status_code}")
- return False
-
- except Exception as e:
- logger.error(f"Network or file system exception while processing {raw_url}: {e}")
- return False
\ No newline at end of file
+
+ # If mirror is configured, use it directly; otherwise use GitHub
+ mirror_url = self._build_mirror_url(raw_url)
+ download_url = mirror_url if mirror_url else raw_url
+
+ response = self._request_with_retry(download_url)
+ if response is not None and response.status_code == 200:
+ with open(local_file_path, "wb") as f:
+ f.write(response.content)
+ return True
+
+ status = response.status_code if response else "no response"
+ logger.warning(f"Failed to download {file_path} (status: {status})")
+ return False
\ No newline at end of file