skillup 0.3.2__tar.gz

skillup-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install
+      - name: Install dependencies
+        run: uv sync
+      - name: Type check
+        run: uv run pyright skillup
+      - name: Run tests
+        run: uv run pytest

skillup-0.3.2/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

skillup-0.3.2/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

skillup-0.3.2/.python-version

@@ -0,0 +1 @@
+3.11

skillup-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skillup-0.3.2/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: skillup
+Version: 0.3.2
+Summary: A minimal CLI to manage agent skills from GitHub releases.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: questionary
+Requires-Dist: requests
+Requires-Dist: rich
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# skillup
+
+A minimal, user-friendly Python CLI to manage agent skills from GitHub releases or branches. It installs skills to both `~/.agents/skills` and `~/.claude/skills` for seamless integration across platforms.
+
+## Features
+
+-   **Interactive Installation:** Select specific skills to add from any GitHub repository.
+-   **Multi-Repo Support:** Manage skills from multiple repositories independently.
+-   **Lock File State:** Tracks installed sources (release tags or branches), pinned commit SHAs, and skills in `~/.agents/skills.lock.json` for reproducibility.
+-   **Automated Updates:** Easily upgrade all or specific repositories to their latest GitHub release or tracked branch head.
+-   **Smart Caching:** Downloads are cached in a temporary directory (`TEMP` or `/tmp`) to avoid redundant network usage. Can be overridden with `SKILLUP_CACHE_DIR`.
+-   **GitHub CLI Integration:** Uses the `gh` tool for fast downloads if available, with a reliable `requests` fallback.
+
+## Installation
+
+Install using `pip` or `uv`:
+
+```bash
+pip install skillup
+# or
+uv tool install skillup
+```
+
+## Usage
+
+### 1. Add Skills
+Interactively select skills to add from a GitHub repository's latest release:
+
+```bash
+skillup add google/gemini-cli-skills
+```
+
+If a repository has no releases, the CLI automatically falls back to the `main` branch. You can also install directly from a branch:
+
+```bash
+skillup add anthropics/skills --branch main --skill pdf
+```
+
+### 2. Remove Skills
+Interactively select installed skills to remove from your system:
+
+```bash
+skillup remove
+```
+
+### 3. Update Skills
+Update all installed skills to their latest tracked versions:
+
+```bash
+skillup update
+```
+
+Or update a specific repository:
+
+```bash
+skillup update --repo google/gemini-cli-skills
+```
+
+### 4. Sync Skills
+Install all skills as defined in the lock file using the pinned commit SHAs (useful for setting up a new machine):
+
+```bash
+skillup sync
+```
+
+### 5. Migrate from NPX Skills CLI
+If you already have a `skills-lock.json` in your repository root, you can import it into the skillup lock format. The latest release or branch commit is resolved from GitHub at migration time.
+
+```bash
+skillup migrate
+```
+
+A custom path can be provided if the file is elsewhere:
+
+```bash
+skillup migrate path/to/skills-lock.json
+```
+
+## Skill Definition
+A folder is recognized as a valid skill if it resides within a `skills/` directory at the repository root and contains a `SKILL.md` file.
+
+## Development
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management.
+
+```bash
+# Install dependencies
+uv sync
+
+# Run locally
+uv run skillup --help
+
+# Run tests
+uv run pytest
+
+# Type check
+uv run pyright skillup
+```
+
+## License
+MIT

skillup-0.3.2/README.md

@@ -0,0 +1,101 @@
+# skillup
+
+A minimal, user-friendly Python CLI to manage agent skills from GitHub releases or branches. It installs skills to both `~/.agents/skills` and `~/.claude/skills` for seamless integration across platforms.
+
+## Features
+
+-   **Interactive Installation:** Select specific skills to add from any GitHub repository.
+-   **Multi-Repo Support:** Manage skills from multiple repositories independently.
+-   **Lock File State:** Tracks installed sources (release tags or branches), pinned commit SHAs, and skills in `~/.agents/skills.lock.json` for reproducibility.
+-   **Automated Updates:** Easily upgrade all or specific repositories to their latest GitHub release or tracked branch head.
+-   **Smart Caching:** Downloads are cached in a temporary directory (`TEMP` or `/tmp`) to avoid redundant network usage. Can be overridden with `SKILLUP_CACHE_DIR`.
+-   **GitHub CLI Integration:** Uses the `gh` tool for fast downloads if available, with a reliable `requests` fallback.
+
+## Installation
+
+Install using `pip` or `uv`:
+
+```bash
+pip install skillup
+# or
+uv tool install skillup
+```
+
+## Usage
+
+### 1. Add Skills
+Interactively select skills to add from a GitHub repository's latest release:
+
+```bash
+skillup add google/gemini-cli-skills
+```
+
+If a repository has no releases, the CLI automatically falls back to the `main` branch. You can also install directly from a branch:
+
+```bash
+skillup add anthropics/skills --branch main --skill pdf
+```
+
+### 2. Remove Skills
+Interactively select installed skills to remove from your system:
+
+```bash
+skillup remove
+```
+
+### 3. Update Skills
+Update all installed skills to their latest tracked versions:
+
+```bash
+skillup update
+```
+
+Or update a specific repository:
+
+```bash
+skillup update --repo google/gemini-cli-skills
+```
+
+### 4. Sync Skills
+Install all skills as defined in the lock file using the pinned commit SHAs (useful for setting up a new machine):
+
+```bash
+skillup sync
+```
+
+### 5. Migrate from NPX Skills CLI
+If you already have a `skills-lock.json` in your repository root, you can import it into the skillup lock format. The latest release or branch commit is resolved from GitHub at migration time.
+
+```bash
+skillup migrate
+```
+
+A custom path can be provided if the file is elsewhere:
+
+```bash
+skillup migrate path/to/skills-lock.json
+```
+
+## Skill Definition
+A folder is recognized as a valid skill if it resides within a `skills/` directory at the repository root and contains a `SKILL.md` file.
+
+## Development
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management.
+
+```bash
+# Install dependencies
+uv sync
+
+# Run locally
+uv run skillup --help
+
+# Run tests
+uv run pytest
+
+# Type check
+uv run pyright skillup
+```
+
+## License
+MIT

skillup-0.3.2/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skillup"
+version = "0.3.2"
+description = "A minimal CLI to manage agent skills from GitHub releases."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer",
+    "rich",
+    "questionary",
+    "requests",
+]
+
+[dependency-groups]
+dev = [
+    "pyright",
+    "pytest",
+]
+
+[project.scripts]
+skillup = "skillup.cli:app"
+
+[tool.uv]
+package = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["skillup"]

skillup-0.3.2/skillup/cli.py

@@ -0,0 +1,260 @@
+import json
+import shutil
+from pathlib import Path
+from typing import Any, List, Optional
+
+import questionary
+import typer
+from rich.console import Console
+
+from .github import get_repo_source
+from .install import download_release, ensure_dirs, get_skills_in_zip, install_skill
+from .lock import apply_source, get_sync_source, load_lock, normalize_repo_data, save_lock
+from .settings import format_source_label, settings
+
+app = typer.Typer(help="Minimal CLI to manage agent skills from GitHub releases or branches.")
+console = Console()
+
+
+@app.callback()
+def main(
+    is_global: bool = typer.Option(False, "--global", "-g", help="Use home directory instead of current directory"),
+):
+    """Minimal CLI to manage agent skills from GitHub releases or branches."""
+    settings.is_global = is_global
+
+
+@app.command()
+def add(
+    repo: str = typer.Argument(..., help="GitHub repository (owner/repo)"),
+    skills: Optional[List[str]] = typer.Option(None, "--skill", "-s", help="Specific skill(s) to add (non-interactive)"),
+    branch: Optional[str] = typer.Option(None, "--branch", "-b", help="Branch to install from instead of the latest release"),
+):
+    """Add skills from a GitHub release or branch."""
+    ensure_dirs()
+    lock = load_lock()
+
+    try:
+        source = get_repo_source(repo, branch)
+    except Exception as e:
+        console.print(f"[red]Error fetching source info for {repo}:[/red] {e}")
+        raise typer.Exit(1)
+
+    zip_path = download_release(repo, source.cache_key, source.zip_url)
+    available_skills = get_skills_in_zip(zip_path)
+
+    repo_data = normalize_repo_data(lock["repos"].get(repo, {"skills": []}))
+    installed_skills = set(repo_data["skills"])
+
+    if skills:
+        selected = [s for s in skills if s in available_skills and s not in installed_skills]
+        invalid = [s for s in skills if s not in available_skills]
+        already_installed = [s for s in skills if s in installed_skills]
+
+        if invalid:
+            console.print(f"[yellow]Warning: Skills not found in {repo}: {', '.join(invalid)}[/yellow]")
+        if already_installed:
+            console.print(f"[blue]Note: Skills already installed from {repo}: {', '.join(already_installed)}[/blue]")
+    else:
+        to_show = [s for s in available_skills if s not in installed_skills]
+
+        if not to_show:
+            console.print(f"[yellow]No new skills available to add from {repo}.[/yellow]")
+            return
+
+        selected = questionary.checkbox(
+            f"Select skills to add from {repo}:",
+            choices=to_show,
+        ).ask()
+
+    if not selected:
+        console.print("No skills selected or available for installation.")
+        return
+
+    for skill in selected:
+        console.print(f"Installing [cyan]{skill}[/cyan]...")
+        install_skill(skill, zip_path)
+        if skill not in repo_data["skills"]:
+            repo_data["skills"].append(skill)
+
+    repo_data = apply_source(repo_data, source)
+    lock["repos"][repo] = repo_data
+    save_lock(lock)
+    console.print(f"[green]Skills from {repo} installed successfully![/green]")
+
+
+@app.command()
+def remove():
+    """Interactively remove installed skills across all repositories."""
+    lock = load_lock()
+
+    all_installed = []
+    for repo, data in lock["repos"].items():
+        for skill in data["skills"]:
+            all_installed.append(f"{repo}: {skill}")
+
+    if not all_installed:
+        console.print("[yellow]No skills installed.[/yellow]")
+        return
+
+    selected = questionary.checkbox(
+        "Select skills to remove:",
+        choices=all_installed,
+    ).ask()
+
+    if not selected:
+        console.print("No skills selected.")
+        return
+
+    for item in selected:
+        repo, skill = item.split(": ", 1)
+        console.print(f"Removing [red]{skill}[/red] from {repo}...")
+        for target_dir in [settings.skills_dir_agents, settings.skills_dir_claude]:
+            dest = target_dir / skill
+            if dest.exists():
+                import shutil
+                shutil.rmtree(dest)
+
+        lock["repos"][repo]["skills"].remove(skill)
+        if not lock["repos"][repo]["skills"]:
+            del lock["repos"][repo]
+
+    save_lock(lock)
+    console.print("[green]Skills removed successfully![/green]")
+
+
+@app.command()
+def update(repo: Optional[str] = typer.Option(None, "--repo", help="Specific repository to update")):
+    """Update installed skills to the latest tracked release or branch commit."""
+    lock = load_lock()
+    repos_to_update = [repo] if repo else list(lock["repos"].keys())
+
+    if not repos_to_update:
+        console.print("[yellow]No skills installed to update.[/yellow]")
+        return
+
+    for r in repos_to_update:
+        if r not in lock["repos"]:
+            if repo:
+                console.print(f"[red]Repository {r} is not tracked.[/red]")
+            continue
+
+        repo_data = normalize_repo_data(lock["repos"][r])
+        console.print(f"Checking updates for [cyan]{r}[/cyan]...")
+
+        try:
+            tracked_branch = repo_data.get("branch") if repo_data.get("source") == "branch" else None
+            source = get_repo_source(r, tracked_branch)
+        except Exception as e:
+            console.print(f"[red]Error fetching source info for {r}:[/red] {e}")
+            continue
+
+        current_version = repo_data.get("commit") or repo_data.get("tag") or repo_data.get("branch")
+        new_version = source.commit or source.ref
+        if current_version == new_version:
+            console.print(f"  [green]{r} is already up-to-date ({format_source_label(source)}).[/green]")
+            continue
+
+        previous_label = repo_data.get("tag") or repo_data.get("branch") or repo_data.get("commit", "unknown")
+        next_label = format_source_label(source)
+        console.print(f"  Updating from {previous_label} to [cyan]{next_label}[/cyan]...", highlight=False)
+        zip_path = download_release(r, source.cache_key, source.zip_url)
+
+        for skill in repo_data["skills"]:
+            console.print(f"  Updating [cyan]{skill}[/cyan]...")
+            install_skill(skill, zip_path)
+
+        repo_data = apply_source(repo_data, source)
+        lock["repos"][r] = repo_data
+        save_lock(lock)
+        console.print(f"  [green]Successfully updated {r} to {next_label}![/green]")
+
+
+@app.command()
+def sync():
+    """Install all skills as defined in the lock file."""
+    ensure_dirs()
+    lock = load_lock()
+
+    if not lock["repos"]:
+        console.print("[yellow]No skills defined in lock file. Use 'add' to add skills.[/yellow]")
+        return
+
+    for repo, repo_data in lock["repos"].items():
+        source = get_sync_source(repo, repo_data)
+        skills = repo_data["skills"]
+        console.print(f"Syncing [cyan]{repo}[/cyan] at [green]{format_source_label(source)}[/green]...")
+
+        try:
+            zip_path = download_release(repo, source.cache_key, source.zip_url)
+            for skill in skills:
+                console.print(f"  Installing [cyan]{skill}[/cyan]...")
+                install_skill(skill, zip_path)
+        except Exception as e:
+            console.print(f"[red]Error syncing {repo}:[/red] {e}")
+            continue
+
+    console.print("[green]Synchronization complete![/green]")
+
+
+@app.command()
+def migrate(
+    input_file: Optional[Path] = typer.Argument(None, help="Path to skills-lock.json (defaults to .claude/skills-lock.json)"),
+):
+    """Migrate a Claude Code skills-lock.json to the skillup lock format."""
+    resolved = input_file if input_file is not None else settings.base_dir / "skills-lock.json"
+
+    if not resolved.exists():
+        console.print(f"[red]File not found: {resolved}[/red]")
+        raise typer.Exit(1)
+
+    try:
+        data = json.loads(resolved.read_text())
+    except Exception as e:
+        console.print(f"[red]Failed to parse {resolved}:[/red] {e}")
+        raise typer.Exit(1)
+
+    skills_map: dict[str, Any] = data.get("skills", {})
+    if not skills_map:
+        console.print("[yellow]No skills found in the input file.[/yellow]")
+        return
+
+    repos: dict[str, list[str]] = {}
+    for skill_name, skill_data in skills_map.items():
+        if skill_data.get("sourceType") != "github":
+            console.print(f"[yellow]Skipping {skill_name}: unsupported sourceType '{skill_data.get('sourceType')}'[/yellow]")
+            continue
+        repo = skill_data["source"]
+        repos.setdefault(repo, []).append(skill_name)
+
+    if not repos:
+        console.print("[yellow]No GitHub skills found to migrate.[/yellow]")
+        return
+
+    lock = load_lock()
+
+    for repo, skill_names in repos.items():
+        console.print(f"Resolving [cyan]{repo}[/cyan]...")
+        try:
+            source = get_repo_source(repo)
+        except Exception as e:
+            console.print(f"[red]Error fetching source info for {repo}:[/red] {e}")
+            continue
+
+        repo_data = lock["repos"].get(repo, {"skills": []})
+        existing = set(repo_data.get("skills", []))
+        for skill in skill_names:
+            if skill not in existing:
+                repo_data.setdefault("skills", []).append(skill)
+
+        repo_data = apply_source(repo_data, source)
+        lock["repos"][repo] = repo_data
+        console.print(f"  [green]Migrated {len(skill_names)} skill(s) at {format_source_label(source)}[/green]")
+
+    ensure_dirs()
+    save_lock(lock)
+    console.print(f"[green]Migration complete! Lock file saved to {settings.lock_file}[/green]")
+
+
+if __name__ == "__main__":
+    app()

skillup-0.3.2/skillup/github.py

@@ -0,0 +1,89 @@
+import os
+import shutil
+import subprocess
+from typing import Optional
+
+import requests
+from rich.console import Console
+
+from .settings import RepoSource, settings
+
+console = Console()
+
+
+def get_github_token() -> Optional[str]:
+    token = os.getenv("GITHUB_TOKEN") or os.getenv("GH_TOKEN")
+    if token:
+        return token
+
+    gh_path = shutil.which("gh")
+    if gh_path:
+        try:
+            result = subprocess.run(
+                [gh_path, "auth", "token"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            token = result.stdout.strip()
+            if token:
+                return token
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+    console.print("[yellow]Warning: GitHub authentication not found. API rate limits may apply.[/yellow]")
+    return None
+
+
+def get_github_headers() -> dict[str, str]:
+    headers: dict[str, str] = {}
+    token = get_github_token()
+    if token:
+        headers["Authorization"] = f"token {token}"
+    return headers
+
+
+def get_latest_release(repo: str) -> tuple[str, str]:
+    url = f"https://api.github.com/repos/{repo}/releases/latest"
+    response = requests.get(url, headers=get_github_headers())
+    response.raise_for_status()
+    data = response.json()
+    return data["tag_name"], data["zipball_url"]
+
+
+def get_commit_sha(repo: str, ref: str) -> str:
+    url = f"https://api.github.com/repos/{repo}/commits/{ref}"
+    response = requests.get(url, headers=get_github_headers())
+    response.raise_for_status()
+    data = response.json()
+    return data["sha"]
+
+
+def get_repo_source(repo: str, branch: Optional[str] = None) -> RepoSource:
+    if branch:
+        commit = get_commit_sha(repo, branch)
+        return RepoSource(
+            kind="branch",
+            ref=branch,
+            commit=commit,
+            zip_url=f"https://api.github.com/repos/{repo}/zipball/{commit}",
+        )
+
+    try:
+        tag, zip_url = get_latest_release(repo)
+        return RepoSource(
+            kind="release",
+            ref=tag,
+            commit=get_commit_sha(repo, tag),
+            zip_url=zip_url,
+        )
+    except requests.HTTPError as exc:
+        if exc.response is not None and exc.response.status_code == 404:
+            commit = get_commit_sha(repo, "main")
+            return RepoSource(
+                kind="branch",
+                ref="main",
+                commit=commit,
+                zip_url=f"https://api.github.com/repos/{repo}/zipball/{commit}",
+            )
+        raise