agent-skill-manager 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

skill_manager/deployment.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
 """
 Skill deployment functionality.
-Handles copying skills to agent directories.
+Handles copying skills to agent directories with optional symlink support.
 """
 
+import os
 import shutil
 from collections.abc import Callable
 from pathlib import Path
@@ -17,6 +18,102 @@ from .metadata import (
 )
 
 
+def is_symlink_supported() -> bool:
+    """
+    Check if the current system supports symlinks.
+
+    On Windows, symlinks require admin privileges or developer mode.
+
+    Returns:
+        True if symlinks are supported, False otherwise
+    """
+    if os.name == "nt":
+        # Windows: test by trying to create a symlink
+        import tempfile
+
+        test_dir = Path(tempfile.gettempdir()) / ".symlink_test"
+        test_link = Path(tempfile.gettempdir()) / ".symlink_test_link"
+        try:
+            test_dir.mkdir(exist_ok=True)
+            if test_link.exists() or test_link.is_symlink():
+                test_link.unlink()
+            test_link.symlink_to(test_dir, target_is_directory=True)
+            test_link.unlink()
+            test_dir.rmdir()
+            return True
+        except OSError:
+            if test_dir.exists():
+                test_dir.rmdir()
+            return False
+    return True
+
+
+def create_symlink(source: Path, target: Path) -> bool:
+    """
+    Create a symlink from target to source.
+
+    Args:
+        source: The source directory (the actual skill)
+        target: The target path where the symlink will be created
+
+    Returns:
+        True if symlink was created successfully, False otherwise
+    """
+    try:
+        # Ensure target parent directory exists
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        # Remove existing target if present
+        if target.exists() or target.is_symlink():
+            if target.is_symlink():
+                target.unlink()
+            elif target.is_dir():
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+
+        # Create symlink
+        target.symlink_to(source, target_is_directory=True)
+        return True
+    except OSError:
+        return False
+
+
+def remove_symlink(target: Path) -> bool:
+    """
+    Remove a symlink (or regular directory).
+
+    Args:
+        target: The symlink/directory to remove
+
+    Returns:
+        True if removed successfully, False otherwise
+    """
+    try:
+        if target.is_symlink():
+            target.unlink()
+        elif target.is_dir():
+            shutil.rmtree(target)
+        elif target.exists():
+            target.unlink()
+        return True
+    except OSError:
+        return False
+
+
+def is_skill_symlink(skill_path: Path) -> bool:
+    """
+    Check if a skill is deployed as a symlink.
+
+    Args:
+        skill_path: Path to the skill directory
+
+    Returns:
+        True if the skill is a symlink, False otherwise
+    """
+    return skill_path.is_symlink()
+
+
 def deploy_skill(
     skill_path: Path,
     skills_dir: Path,
@@ -61,6 +158,7 @@ def deploy_skill_to_agents(
     agents: list[str],
     deployment_type: str = "global",
     project_root: Path | None = None,
+    use_symlink: bool = False,
 ) -> tuple[int, int]:
     """
     Deploy a skill directory to multiple agents.
@@ -72,6 +170,7 @@ def deploy_skill_to_agents(
         agents: List of agent IDs to deploy to
         deployment_type: Either "global" or "project"
         project_root: Project root directory (required for project deployment)
+        use_symlink: If True, create symlinks instead of copying
 
     Returns:
         Tuple of (success_count, failure_count)
@@ -89,12 +188,24 @@ def deploy_skill_to_agents(
             target_base.mkdir(parents=True, exist_ok=True)
 
             # Remove existing skill if present
-            if target_dir.exists():
-                shutil.rmtree(target_dir)
-
-            # Copy the skill directory
-            shutil.copytree(skill_dir, target_dir)
-            success_count += 1
+            if target_dir.exists() or target_dir.is_symlink():
+                if target_dir.is_symlink():
+                    target_dir.unlink()
+                else:
+                    shutil.rmtree(target_dir)
+
+            if use_symlink:
+                # Create symlink
+                if create_symlink(skill_dir.resolve(), target_dir):
+                    success_count += 1
+                else:
+                    # Fallback to copy if symlink fails
+                    shutil.copytree(skill_dir, target_dir)
+                    success_count += 1
+            else:
+                # Copy the skill directory
+                shutil.copytree(skill_dir, target_dir)
+                success_count += 1
         except Exception:
             fail_count += 1
 

skill_manager/github.py

@@ -4,6 +4,7 @@ GitHub download functionality for skills.
 Handles URL parsing and downloading files/directories from GitHub.
 """
 
+import tempfile
 from collections.abc import Callable
 from pathlib import Path
 from urllib.parse import urlparse
@@ -11,6 +12,16 @@ from urllib.parse import urlparse
 import httpx
 
 
+def get_system_temp_dir() -> Path:
+    """
+    Get the system temporary directory (cross-platform).
+
+    Returns:
+        Path to the system temp directory
+    """
+    return Path(tempfile.gettempdir()) / "skill-manager"
+
+
 def parse_github_url(url: str) -> tuple[str, str, str, str]:
     """
     Parse GitHub URL to extract repository information.
@@ -92,9 +103,7 @@ def download_file(url: str, dest_path: Path) -> None:
         dest_path.write_bytes(response.content)
 
 
-def download_directory(
-    owner: str, repo: str, path: str, dest_dir: Path, branch: str = "main"
-) -> None:
+def download_directory(owner: str, repo: str, path: str, dest_dir: Path, branch: str = "main") -> None:
     """
     Recursively download an entire directory from GitHub.
 
@@ -124,9 +133,7 @@ def download_directory(
             download_directory(owner, repo, item_path, subdir_dest, branch)
 
 
-def download_skill_from_github(
-    url: str, dest_dir: Path, progress_callback: Callable | None = None
-) -> tuple[Path, dict]:
+def download_skill_from_github(url: str, dest_dir: Path, progress_callback: Callable | None = None) -> tuple[Path, dict]:
     """
     Download a skill from GitHub to a local directory.
 
@@ -175,3 +182,145 @@ def download_skill_from_github(
     }
 
     return skill_dest, metadata
+
+
+def discover_skills_in_repo(url: str, progress_callback: Callable | None = None) -> list[dict]:
+    """
+    Discover all SKILL.md files in a GitHub repository or directory.
+
+    This function scans a GitHub URL to find all directories containing SKILL.md files,
+    which conform to the skill specification.
+
+    Args:
+        url: GitHub URL (can be repo root or a subdirectory)
+        progress_callback: Optional callback for progress updates
+
+    Returns:
+        List of dictionaries containing skill information:
+        - name: skill directory name
+        - path: path within the repository
+        - url: full GitHub URL to the skill directory
+
+    Raises:
+        httpx.HTTPStatusError: If the API request fails
+    """
+    owner, repo, branch, path = parse_github_url(url)
+
+    if progress_callback:
+        progress_callback(f"Scanning {owner}/{repo}...")
+
+    skills = []
+    _scan_for_skills(owner, repo, branch, path, skills, progress_callback)
+    return skills
+
+
+def _scan_for_skills(
+    owner: str,
+    repo: str,
+    branch: str,
+    path: str,
+    skills: list[dict],
+    progress_callback: Callable | None = None,
+) -> None:
+    """
+    Recursively scan a directory for SKILL.md files.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+        branch: Branch name
+        path: Current path being scanned
+        skills: List to append found skills to
+        progress_callback: Optional callback for progress updates
+    """
+    try:
+        content = get_github_content(owner, repo, path, branch)
+    except httpx.HTTPStatusError:
+        return
+
+    if not isinstance(content, list):
+        return
+
+    has_skill_md = False
+    subdirs = []
+
+    for item in content:
+        item_name = item["name"]
+        item_path = item["path"]
+        item_type = item["type"]
+
+        if item_type == "file" and item_name == "SKILL.md":
+            has_skill_md = True
+        elif item_type == "dir":
+            subdirs.append(item_path)
+
+    if has_skill_md:
+        skill_name = path.split("/")[-1] if path else repo
+        skill_url = f"https://github.com/{owner}/{repo}/tree/{branch}/{path}" if path else f"https://github.com/{owner}/{repo}"
+        skills.append(
+            {
+                "name": skill_name,
+                "path": path,
+                "url": skill_url,
+                "owner": owner,
+                "repo": repo,
+                "branch": branch,
+            }
+        )
+        if progress_callback:
+            progress_callback(f"Found skill: {skill_name}")
+
+    # Recursively scan subdirectories
+    for subdir in subdirs:
+        _scan_for_skills(owner, repo, branch, subdir, skills, progress_callback)
+
+
+def download_multiple_skills(
+    skill_infos: list[dict],
+    dest_dir: Path,
+    progress_callback: Callable | None = None,
+) -> list[tuple[Path, dict]]:
+    """
+    Download multiple skills from GitHub.
+
+    Args:
+        skill_infos: List of skill info dictionaries (from discover_skills_in_repo)
+        dest_dir: Destination directory
+        progress_callback: Optional callback for progress updates
+
+    Returns:
+        List of tuples (skill_path, metadata)
+    """
+    results = []
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    for skill_info in skill_infos:
+        owner = skill_info["owner"]
+        repo = skill_info["repo"]
+        branch = skill_info["branch"]
+        path = skill_info["path"]
+        skill_name = skill_info["name"]
+
+        if progress_callback:
+            progress_callback(f"Downloading {skill_name}...")
+
+        skill_dest = dest_dir / skill_name
+        skill_dest.mkdir(parents=True, exist_ok=True)
+
+        try:
+            download_directory(owner, repo, path, skill_dest, branch)
+
+            metadata = {
+                "owner": owner,
+                "repo": repo,
+                "branch": branch,
+                "path": path,
+                "url": skill_info["url"],
+            }
+            results.append((skill_dest, metadata))
+        except Exception:
+            # Skip failed downloads
+            if progress_callback:
+                progress_callback(f"Failed to download {skill_name}")
+
+    return results

skill_manager/metadata.py

@@ -117,11 +117,13 @@ def list_updatable_skills(
         # Check for metadata
         metadata = read_skill_metadata(skill_dir)
         if metadata and metadata.get("source") == "github":
-            updatable_skills.append({
-                "skill_name": skill_dir.name,
-                "skill_path": skill_dir,
-                "metadata": metadata,
-            })
+            updatable_skills.append(
+                {
+                    "skill_name": skill_dir.name,
+                    "skill_path": skill_dir,
+                    "metadata": metadata,
+                }
+            )
 
     return sorted(updatable_skills, key=lambda x: x["skill_name"])
 

skill_manager/removal.py

@@ -65,10 +65,7 @@ def soft_delete_skill(
         # Create metadata file
         metadata_file = trash_dest / ".trash_metadata"
         metadata_file.write_text(
-            f"deleted_at: {timestamp}\n"
-            f"original_path: {skill_dir}\n"
-            f"agent_id: {agent_id}\n"
-            f"deployment_type: {deployment_type}\n"
+            f"deleted_at: {timestamp}\noriginal_path: {skill_dir}\nagent_id: {agent_id}\ndeployment_type: {deployment_type}\n"
         )
 
         return True
@@ -149,12 +146,14 @@ def list_trashed_skills(
                     if line.startswith("deleted_at:"):
                         deleted_at = line.split(":", 1)[1].strip()
 
-            trashed_skills.append({
-                "skill_name": skill_dir.name,
-                "deleted_at": deleted_at,
-                "trash_path": skill_dir,
-                "timestamp_dir": timestamp_dir.name,
-            })
+            trashed_skills.append(
+                {
+                    "skill_name": skill_dir.name,
+                    "deleted_at": deleted_at,
+                    "trash_path": skill_dir,
+                    "timestamp_dir": timestamp_dir.name,
+                }
+            )
 
     return trashed_skills
 

agent_skill_manager-0.1.2.dist-info/METADATA

@@ -1,271 +0,0 @@
-Metadata-Version: 2.4
-Name: agent-skill-manager
-Version: 0.1.2
-Summary: CLI tool for managing AI agent skills across multiple platforms
-Project-URL: Homepage, https://github.com/ackness/skill-manager
-Project-URL: Repository, https://github.com/ackness/skill-manager
-Project-URL: Issues, https://github.com/ackness/skill-manager/issues
-Project-URL: Documentation, https://github.com/ackness/skill-manager#readme
-Author-email: ackness <ackness8@gmail.com>
-License: MIT
-Keywords: agents,ai,claude,cli,cursor,skills,windsurf
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: Utilities
-Requires-Python: >=3.13
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: inquirerpy>=0.3.4
-Requires-Dist: loguru>=0.7.3
-Requires-Dist: rich>=14.2.0
-Description-Content-Type: text/markdown
-
-# Agent Skill Manager
-
-A comprehensive CLI tool for managing AI agent skills across multiple platforms. Download, deploy, update, and manage skills for AI coding assistants like Claude Code, Cursor, Windsurf, and more.
-
-[![PyPI version](https://badge.fury.io/py/agent-skill-manager.svg)](https://pypi.org/project/agent-skill-manager/)
-[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## Features
-
-- 📥 **Download** skills from GitHub with metadata tracking
-- 🚀 **Deploy** skills to multiple AI agents (global or project-level)
-- 🔄 **Update** skills automatically from GitHub sources
-- 🗑️ **Uninstall** with safe deletion (move to trash) or hard delete
-- ♻️ **Restore** deleted skills from trash
-- 📋 **List** all installed skills with version information
-
-## Supported AI Agents
-
-- Claude Code
-- Cursor
-- Windsurf
-- OpenCode
-- GitHub Copilot
-- Goose
-- Gemini CLI
-- Roo Code
-- Kilo Code
-- Amp
-- Codex
-- Antigravity
-- Clawdbot
-- Droid
-
-## Installation
-
-### Quick Run with uvx (No Installation Required)
-
-Run directly without installing (recommended for trying it out):
-
-```bash
-uv tool install agent-skill-manager
-sm
-```
-
-### Permanent Installation
-
-```bash
-# Using uv (recommended)
-uv tool install agent-skill-manager
-
-# Using pip
-pip install agent-skill-manager
-
-# Using pipx (isolated installation)
-pipx install agent-skill-manager
-```
-
-### From Source
-
-```bash
-git clone https://github.com/ackness/skill-manager.git
-cd skill-manager
-uv sync
-uv pip install -e .
-```
-
-## Usage Methods Comparison
-
-| Method | Command | Use Case |
-|--------|---------|----------|
-| **uvx (no install)** | `uvx --from agent-skill-manager sm install` | One-time use, testing, CI/CD |
-| **uv tool install** | `uv tool install agent-skill-manager` then `sm install` | Regular use, isolated |
-| **pip install** | `pip install agent-skill-manager` then `sm install` | Traditional installation |
-| **From source** | `git clone ...` then `uv pip install -e .` | Development |
-
-## Quick Start
-
-```bash
-# Run without installing (using uvx)
-uvx --from agent-skill-manager sm install
-uvx --from agent-skill-manager sm list
-
-# Or after installation, use sm command directly:
-sm install          # Install a skill from GitHub
-sm list            # List installed skills
-sm update --all    # Update all skills
-sm deploy          # Deploy local skills to agents
-sm uninstall       # Uninstall a skill (safe delete)
-```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `sm download` | Download a skill from GitHub |
-| `sm deploy` | Deploy local skills to agents |
-| `sm install` | Download and deploy in one step |
-| `sm uninstall` | Remove skills (safe delete/hard delete) |
-| `sm restore` | Restore deleted skills from trash |
-| `sm update` | Update selected skills from GitHub |
-| `sm update --all` | Update all GitHub-sourced skills |
-| `sm list` | Show installed skills with versions |
-
-## Usage Examples
-
-### Install a skill from GitHub
-
-```bash
-sm install
-# Enter URL: https://github.com/user/repo/tree/main/skills/example-skill
-# Follow the prompts to save locally and deploy
-```
-
-### Update all skills
-
-```bash
-sm update --all
-# Automatically updates all skills installed from GitHub
-```
-
-### List installed skills with versions
-
-```bash
-sm list
-# Shows a table for each agent with:
-# - Skill Name
-# - Version/Updated timestamp
-# - Source (GitHub/Local)
-# - GitHub URL (for updatable skills)
-```
-
-### Safe delete and restore
-
-```bash
-# Uninstall with safe delete (default)
-sm uninstall
-
-# Restore if needed
-sm restore
-```
-
-## Version Tracking
-
-The tool uses two methods for version identification:
-
-1. **GitHub Metadata** (for installed skills)
-   - Tracks installation and update timestamps
-   - Stores repository information
-   - Enables automatic updates
-
-2. **File Modification Time** (for local skills)
-   - Uses SKILL.md modification time as fallback
-   - For skills without metadata
-
-## Directory Structure
-
-### Global Installation
-Skills are available to all projects:
-```
-~/.claude/skills/           # Claude Code
-~/.cursor/skills/           # Cursor
-~/.codeium/windsurf/skills/ # Windsurf
-# ... other agents
-```
-
-### Project Installation
-Skills are only available in the current project:
-```
-project-root/
-  .claude/skills/
-  .cursor/skills/
-  # ... other agents
-```
-
-## Configuration
-
-Each skill installed from GitHub includes metadata in `.skill_metadata.json`:
-
-```json
-{
-  "source": "github",
-  "github_url": "https://github.com/...",
-  "owner": "user",
-  "repo": "repo-name",
-  "branch": "main",
-  "path": "skills/skill-name",
-  "installed_at": "2026-01-20T14:30:52+00:00",
-  "updated_at": "2026-01-20T14:30:52+00:00"
-}
-```
-
-## Development
-
-### Adding Support for New Agents
-
-Edit `src/skill_manager/agents.py` and add the agent configuration:
-
-```python
-"agent-id": {
-    "name": "Agent Name",
-    "project": ".agent/skills/",
-    "global": "~/.agent/skills/",
-}
-```
-
-### Running Tests
-
-```bash
-uv run pytest
-```
-
-### Code Formatting
-
-```bash
-uv run ruff format .
-uv run ruff check . --fix
-```
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## Related Projects
-
-- [Agent Skills Specification](https://agentskills.io/specification)
-- [Agent Skills Registry](https://agentskills.io)
-
-## License
-
-MIT License - See [LICENSE](LICENSE) file for details
-
-## Author
-
-**ackness** - [ackness8@gmail.com](mailto:ackness8@gmail.com)
-
-## Acknowledgments
-
-- Built following the [Agent Skills specification](https://agentskills.io/specification)
-- Supports all major AI coding assistants

agent_skill_manager-0.1.2.dist-info/RECORD

@@ -1,12 +0,0 @@
-skill_manager/__init__.py,sha256=0XIUCOGXT7Emm8ZLJ9YbNM-4Dv2v-m4Fkavq5onzwrY,1717
-skill_manager/agents.py,sha256=1sqdXQwoZCXhedyfo608crZp3rjPX6-LpFU9WsK45sU,3590
-skill_manager/cli.py,sha256=l5F_RDC7GFbsQZMRZhQ4GMPhiVAzyi8-hCB6sEy7OSc,36277
-skill_manager/deployment.py,sha256=EVA-HdBcqcqz6IAZLoGU-BWEw0tOz_kjkRRxD_4ZC5Q,7672
-skill_manager/github.py,sha256=WIju94QHVcJnCprwHujticgkeWs0Z07AXOJ6a39wKTg,4841
-skill_manager/metadata.py,sha256=YF3vBxeujnbMwOJCM8G_zGBD6ZH5ZDMIBOpcKepBwAo,3457
-skill_manager/removal.py,sha256=3yAn0Fd92_X40Z_SmxELHKKrWxew0vUGS8WO6Uq3730,8040
-skill_manager/validation.py,sha256=fRUJDs4TiuKlH3doey31SPJfe671JJQcBFSAhJwoSIE,1970
-agent_skill_manager-0.1.2.dist-info/METADATA,sha256=j3lF_fih1qOVaapFZql8WqgwCFg_EMv4rbsTUvmIDyM,6990
-agent_skill_manager-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-agent_skill_manager-0.1.2.dist-info/entry_points.txt,sha256=ac3L07OC98p1llk259d9PUhDp-cl3ifV2nmYHGb3WO8,85
-agent_skill_manager-0.1.2.dist-info/RECORD,,