skill-seekers 2.7.3__py3-none-any.whl

skill_seekers/cli/install_agent.py

@@ -0,0 +1,461 @@
+#!/usr/bin/env python3
+"""
+Install skills to AI coding agent directories.
+
+This module provides functionality to install Skill Seekers-generated skills
+to various AI coding agents (Claude Code, Cursor, VS Code, Amp, Goose, etc.)
+by copying skill directories to agent-specific installation paths.
+
+Usage:
+    skill-seekers install-agent <skill_directory> --agent <agent_name> [--force] [--dry-run]
+
+Examples:
+    # Install to specific agent
+    skill-seekers install-agent output/react/ --agent cursor
+
+    # Install to all agents at once
+    skill-seekers install-agent output/react/ --agent all
+
+    # Force overwrite existing installation
+    skill-seekers install-agent output/react/ --agent claude --force
+
+    # Preview installation without making changes
+    skill-seekers install-agent output/react/ --agent cursor --dry-run
+"""
+
+import argparse
+import shutil
+import sys
+from difflib import get_close_matches
+from pathlib import Path
+
+# Agent installation paths
+# Global paths (install to home directory): Use ~/.{agent}/skills/
+# Project paths (install to current directory): Use .{agent}/skills/
+AGENT_PATHS = {
+    "claude": "~/.claude/skills/",  # Global (home)
+    "cursor": ".cursor/skills/",  # Project-relative
+    "vscode": ".github/skills/",  # Project-relative
+    "copilot": ".github/skills/",  # Same as VSCode
+    "amp": "~/.amp/skills/",  # Global
+    "goose": "~/.config/goose/skills/",  # Global
+    "opencode": "~/.opencode/skills/",  # Global
+    "letta": "~/.letta/skills/",  # Global
+    "aide": "~/.aide/skills/",  # Global
+    "windsurf": "~/.windsurf/skills/",  # Global
+    "neovate": "~/.neovate/skills/",  # Global
+}
+
+
+def get_agent_path(agent_name: str, project_root: Path | None = None) -> Path:
+    """
+    Resolve the installation path for a given agent.
+
+    Handles both global paths (~/.<agent>/skills/) and project-relative paths
+    (.cursor/skills/, .github/skills/).
+
+    Args:
+        agent_name: Name of the agent (e.g., 'claude', 'cursor')
+        project_root: Optional project root directory for project-relative paths
+                     (defaults to current working directory)
+
+    Returns:
+        Absolute path to the agent's skill installation directory
+
+    Raises:
+        ValueError: If agent_name is not recognized
+    """
+    agent_name = agent_name.lower()
+
+    if agent_name not in AGENT_PATHS:
+        raise ValueError(f"Unknown agent: {agent_name}")
+
+    path_template = AGENT_PATHS[agent_name]
+
+    # Handle home directory expansion (~)
+    if path_template.startswith("~"):
+        return Path(path_template).expanduser()
+
+    # Handle project-relative paths
+    if project_root is None:
+        project_root = Path.cwd()
+
+    return project_root / path_template
+
+
+def get_available_agents() -> list:
+    """
+    Get list of all supported agent names.
+
+    Returns:
+        List of agent names (lowercase)
+    """
+    return sorted(AGENT_PATHS.keys())
+
+
+def validate_agent_name(agent_name: str) -> tuple[bool, str | None]:
+    """
+    Validate an agent name and provide suggestions if invalid.
+
+    Performs case-insensitive matching and fuzzy matching to suggest
+    similar agent names if the provided name is invalid.
+
+    Args:
+        agent_name: Agent name to validate
+
+    Returns:
+        Tuple of (is_valid, error_message)
+        - is_valid: True if agent name is valid, False otherwise
+        - error_message: None if valid, error message with suggestions if invalid
+    """
+    # Special case: 'all' is valid for installing to all agents
+    if agent_name.lower() == "all":
+        return True, None
+
+    # Case-insensitive check
+    if agent_name.lower() in AGENT_PATHS:
+        return True, None
+
+    # Agent not found - provide suggestions
+    available = get_available_agents()
+
+    # Try fuzzy matching (find similar names)
+    suggestions = get_close_matches(agent_name.lower(), available, n=1, cutoff=0.6)
+
+    error_msg = f"Unknown agent '{agent_name}'\n\n"
+
+    if suggestions:
+        error_msg += f"Did you mean: {suggestions[0]}?\n\n"
+
+    error_msg += "Available agents:\n  "
+    error_msg += ", ".join(available + ["all"])
+    error_msg += f"\n\nUsage:\n  skill-seekers install-agent <skill_directory> --agent {suggestions[0] if suggestions else 'claude'}"
+
+    return False, error_msg
+
+
+def validate_skill_directory(skill_dir: Path) -> tuple[bool, str | None]:
+    """
+    Validate that a directory is a valid skill directory.
+
+    A valid skill directory must:
+    - Exist
+    - Be a directory
+    - Contain a SKILL.md file
+
+    Args:
+        skill_dir: Path to skill directory
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if not skill_dir.exists():
+        return False, f"Skill directory does not exist: {skill_dir}"
+
+    if not skill_dir.is_dir():
+        return False, f"Path is not a directory: {skill_dir}"
+
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        return False, f"SKILL.md not found in {skill_dir}"
+
+    return True, None
+
+
+def install_to_agent(
+    skill_dir: str | Path, agent_name: str, force: bool = False, dry_run: bool = False
+) -> tuple[bool, str]:
+    """
+    Install a skill to a specific agent's directory.
+
+    Copies the skill directory to the agent's installation path, excluding
+    backup files and temporary files.
+
+    Args:
+        skill_dir: Path to skill directory
+        agent_name: Name of agent to install to
+        force: If True, overwrite existing installation without asking
+        dry_run: If True, preview installation without making changes
+
+    Returns:
+        Tuple of (success, message)
+        - success: True if installation succeeded, False otherwise
+        - message: Success message or error description
+    """
+    # Convert to Path
+    skill_dir = Path(skill_dir).resolve()
+    skill_name = skill_dir.name
+
+    # Validate skill directory
+    is_valid, error_msg = validate_skill_directory(skill_dir)
+    if not is_valid:
+        return False, f"❌ {error_msg}"
+
+    # Validate agent name
+    is_valid, error_msg = validate_agent_name(agent_name)
+    if not is_valid:
+        return False, f"❌ {error_msg}"
+
+    # Get agent installation path
+    try:
+        agent_base_path = get_agent_path(agent_name.lower())
+    except ValueError as e:
+        return False, f"❌ {str(e)}"
+
+    # Target path: {agent_base_path}/{skill_name}/
+    target_path = agent_base_path / skill_name
+
+    # Check if already exists
+    if target_path.exists() and not force:
+        error_msg = "❌ Skill already installed\n\n"
+        error_msg += f"Location: {target_path}\n\n"
+        error_msg += "Options:\n"
+        error_msg += f"  1. Overwrite: skill-seekers install-agent {skill_dir} --agent {agent_name} --force\n"
+        error_msg += f"  2. Remove:    rm -rf {target_path}\n"
+        error_msg += f"  3. Rename:    mv {skill_dir} {skill_dir.parent / (skill_name + '-v2')}"
+        return False, error_msg
+
+    # Dry run mode - just preview
+    if dry_run:
+        msg = "🔍 DRY RUN - No changes will be made\n\n"
+        msg += f"Would install skill: {skill_name}\n"
+        msg += f"   Source: {skill_dir}\n"
+        msg += f"   Target: {target_path}\n\n"
+
+        # Calculate total size
+        total_size = sum(f.stat().st_size for f in skill_dir.rglob("*") if f.is_file())
+
+        msg += "Files to copy:\n"
+        msg += f"   SKILL.md ({(skill_dir / 'SKILL.md').stat().st_size / 1024:.1f} KB)\n"
+
+        references_dir = skill_dir / "references"
+        if references_dir.exists():
+            ref_files = list(references_dir.rglob("*.md"))
+            ref_size = sum(f.stat().st_size for f in ref_files)
+            msg += f"   references/ ({len(ref_files)} files, {ref_size / 1024:.1f} KB)\n"
+
+        for subdir in ["scripts", "assets"]:
+            subdir_path = skill_dir / subdir
+            if subdir_path.exists():
+                files = list(subdir_path.rglob("*"))
+                if files:
+                    msg += f"   {subdir}/ ({len(files)} files)\n"
+                else:
+                    msg += f"   {subdir}/ (empty)\n"
+
+        msg += f"\nTotal size: {total_size / 1024:.1f} KB\n\n"
+        msg += "To actually install, run:\n"
+        msg += f"  skill-seekers install-agent {skill_dir} --agent {agent_name}"
+
+        return True, msg
+
+    # Create parent directories if needed
+    try:
+        agent_base_path.mkdir(parents=True, exist_ok=True)
+    except PermissionError:
+        return (
+            False,
+            f"❌ Permission denied: {agent_base_path}\n\nTry: sudo mkdir -p {agent_base_path} && sudo chown -R $USER {agent_base_path}",
+        )
+
+    # Copy skill directory
+    def ignore_files(_directory, files):
+        """Filter function for shutil.copytree to exclude unwanted files."""
+        ignored = []
+        for f in files:
+            # Exclude backup files
+            if (
+                f.endswith(".backup")
+                or f == "__pycache__"
+                or f == ".DS_Store"
+                or f.startswith(".")
+                and f not in [".github", ".cursor"]
+            ):
+                ignored.append(f)
+        return ignored
+
+    try:
+        # Remove existing if force mode
+        if target_path.exists() and force:
+            shutil.rmtree(target_path)
+
+        # Copy directory
+        shutil.copytree(skill_dir, target_path, ignore=ignore_files)
+
+        # Success message
+        msg = "✅ Installation complete!\n\n"
+        msg += f"Skill '{skill_name}' installed to {agent_name}\n"
+        msg += f"Location: {target_path}\n\n"
+
+        # Agent-specific restart instructions
+        if agent_name.lower() == "claude":
+            msg += "Restart Claude Code to load the new skill."
+        elif agent_name.lower() == "cursor":
+            msg += "Restart Cursor to load the new skill."
+        elif agent_name.lower() in ["vscode", "copilot"]:
+            msg += "Restart VS Code to load the new skill."
+        else:
+            msg += f"Restart {agent_name.capitalize()} to load the new skill."
+
+        return True, msg
+
+    except PermissionError as e:
+        return (
+            False,
+            f"❌ Permission denied: {e}\n\nTry: sudo mkdir -p {agent_base_path} && sudo chown -R $USER {agent_base_path}",
+        )
+    except Exception as e:
+        return False, f"❌ Installation failed: {e}"
+
+
+def install_to_all_agents(
+    skill_dir: str | Path, force: bool = False, dry_run: bool = False
+) -> dict[str, tuple[bool, str]]:
+    """
+    Install a skill to all available agents.
+
+    Attempts to install the skill to all agents in AGENT_PATHS,
+    collecting results for each agent.
+
+    Args:
+        skill_dir: Path to skill directory
+        force: If True, overwrite existing installations
+        dry_run: If True, preview installations without making changes
+
+    Returns:
+        Dictionary mapping agent names to (success, message) tuples
+    """
+    results = {}
+
+    for agent_name in get_available_agents():
+        success, message = install_to_agent(skill_dir, agent_name, force=force, dry_run=dry_run)
+        results[agent_name] = (success, message)
+
+    return results
+
+
+def main() -> int:
+    """
+    Main entry point for install-agent CLI.
+
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    parser = argparse.ArgumentParser(
+        prog="skill-seekers-install-agent",
+        description="Install skills to AI coding agent directories",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Install to specific agent
+  skill-seekers install-agent output/react/ --agent cursor
+
+  # Install to all agents
+  skill-seekers install-agent output/react/ --agent all
+
+  # Force overwrite
+  skill-seekers install-agent output/react/ --agent claude --force
+
+  # Preview installation
+  skill-seekers install-agent output/react/ --agent cursor --dry-run
+
+Supported agents:
+  claude, cursor, vscode, copilot, amp, goose, opencode, letta, aide, windsurf, neovate, all
+        """,
+    )
+
+    parser.add_argument("skill_directory", help="Path to skill directory (e.g., output/react/)")
+
+    parser.add_argument(
+        "--agent", required=True, help="Agent name (use 'all' to install to all agents)"
+    )
+
+    parser.add_argument(
+        "--force", action="store_true", help="Overwrite existing installation without asking"
+    )
+
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Preview installation without making changes"
+    )
+
+    args = parser.parse_args()
+
+    # Convert skill directory to Path
+    skill_dir = Path(args.skill_directory)
+    skill_name = skill_dir.name
+
+    # Handle 'all' agent
+    if args.agent.lower() == "all":
+        print(f"\n📋 Installing skill to all agents: {skill_name}\n")
+
+        if args.dry_run:
+            print("🔍 DRY RUN MODE - No changes will be made\n")
+
+        results = install_to_all_agents(skill_dir, force=args.force, dry_run=args.dry_run)
+
+        # Print results
+        installed_count = 0
+        failed_count = 0
+        skipped_count = 0
+
+        for agent_name, (success, message) in results.items():
+            if success:
+                if args.dry_run:
+                    print(f"⏳ Would install to {agent_name}...")
+                else:
+                    agent_path = get_agent_path(agent_name)
+                    print(f"⏳ Installing to {agent_name}...   ✅ {agent_path / skill_name}")
+                installed_count += 1
+            else:
+                # Check if it's a permission error or skip
+                if "Permission denied" in message:
+                    print(f"⏳ Installing to {agent_name}...   ❌ Permission denied")
+                    failed_count += 1
+                elif "does not exist" in message or "SKILL.md not found" in message:
+                    # Validation error - only show once
+                    print(message)
+                    return 1
+                else:
+                    print(f"⏳ Installing to {agent_name}...   ⚠️  Skipped (not installed)")
+                    skipped_count += 1
+
+        # Summary
+        print("\n📊 Summary:")
+        if args.dry_run:
+            print(f"   Would install: {installed_count} agents")
+        else:
+            print(f"   ✅ Installed: {installed_count} agents")
+        if failed_count > 0:
+            print(f"   ❌ Failed:    {failed_count} agent(s) (permission denied)")
+        if skipped_count > 0:
+            print(f"   ⚠️  Skipped:  {skipped_count} agent(s) (not installed)")
+
+        if not args.dry_run:
+            print("\nRestart your agents to load the skill.")
+
+        if failed_count > 0:
+            print("\nFix permission errors:")
+            print("   sudo mkdir -p ~/.amp && sudo chown -R $USER ~/.amp")
+
+        return 0 if installed_count > 0 else 1
+
+    # Single agent installation
+    agent_name = args.agent
+
+    print(f"\n📋 Installing skill: {skill_name}")
+    print(f"   Agent:  {agent_name}")
+
+    if args.dry_run:
+        print("\n🔍 DRY RUN MODE - No changes will be made\n")
+
+    success, message = install_to_agent(
+        skill_dir, agent_name, force=args.force, dry_run=args.dry_run
+    )
+
+    print(message)
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skill_seekers/cli/install_skill.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+Complete Skill Installation Workflow
+One-command installation: fetch → scrape → enhance → package → upload
+
+This CLI tool orchestrates the complete skill installation workflow by calling
+the install_skill MCP tool.
+
+Usage:
+    skill-seekers install --config react
+    skill-seekers install --config configs/custom.json --no-upload
+    skill-seekers install --config django --unlimited
+    skill-seekers install --config react --dry-run
+
+Examples:
+    # Install React skill from official configs
+    skill-seekers install --config react
+
+    # Install from local config file
+    skill-seekers install --config configs/custom.json
+
+    # Install without uploading
+    skill-seekers install --config django --no-upload
+
+    # Preview workflow without executing
+    skill-seekers install --config react --dry-run
+"""
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+# Add parent directory to path to import MCP server
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+# Import the MCP tool function (with lazy loading)
+try:
+    from skill_seekers.mcp.server import install_skill_tool
+
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+    install_skill_tool = None
+
+
+def main():
+    """Main entry point for CLI"""
+    # Check MCP availability first
+    if not MCP_AVAILABLE:
+        print("\n❌ Error: MCP package not installed")
+        print("\nThe 'install' command requires MCP support.")
+        print("Install with:")
+        print("  pip install skill-seekers[mcp]")
+        print("\nOr use these alternatives:")
+        print("  skill-seekers scrape --config react")
+        print("  skill-seekers package output/react/")
+        print()
+        sys.exit(1)
+
+    parser = argparse.ArgumentParser(
+        description="Complete skill installation workflow (fetch → scrape → enhance → package → upload)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Install React skill from official API
+  skill-seekers install --config react
+
+  # Install from local config file
+  skill-seekers install --config configs/custom.json
+
+  # Install without uploading
+  skill-seekers install --config django --no-upload
+
+  # Unlimited scraping (no page limits)
+  skill-seekers install --config godot --unlimited
+
+  # Preview workflow (dry run)
+  skill-seekers install --config react --dry-run
+
+  # Install for Gemini instead of Claude
+  skill-seekers install --config react --target gemini
+
+  # Install for OpenAI ChatGPT
+  skill-seekers install --config fastapi --target openai
+
+Important:
+  - Enhancement is MANDATORY (30-60 sec) for quality (3/10→9/10)
+  - Total time: 20-45 minutes (mostly scraping)
+  - Multi-platform support: claude (default), gemini, openai, markdown
+  - Auto-uploads if API key is set (ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY)
+
+Phases:
+  1. Fetch config (if config name provided)
+  2. Scrape documentation
+  3. AI Enhancement (MANDATORY - no skip option)
+  4. Package for target platform (ZIP or tar.gz)
+  5. Upload to target platform (optional)
+""",
+    )
+
+    parser.add_argument(
+        "--config",
+        required=True,
+        help="Config name (e.g., 'react') or path (e.g., 'configs/custom.json')",
+    )
+
+    parser.add_argument(
+        "--destination",
+        default="output",
+        help="Output directory for skill files (default: output/)",
+    )
+
+    parser.add_argument("--no-upload", action="store_true", help="Skip automatic upload to Claude")
+
+    parser.add_argument(
+        "--unlimited",
+        action="store_true",
+        help="Remove page limits during scraping (WARNING: Can take hours)",
+    )
+
+    parser.add_argument("--dry-run", action="store_true", help="Preview workflow without executing")
+
+    parser.add_argument(
+        "--target",
+        choices=["claude", "gemini", "openai", "markdown"],
+        default="claude",
+        help="Target LLM platform (default: claude)",
+    )
+
+    args = parser.parse_args()
+
+    # Determine if config is a name or path
+    config_arg = args.config
+    if config_arg.endswith(".json") or "/" in config_arg or "\\" in config_arg:
+        # It's a path
+        config_path = config_arg
+        config_name = None
+    else:
+        # It's a name
+        config_name = config_arg
+        config_path = None
+
+    # Build arguments for install_skill_tool
+    tool_args = {
+        "config_name": config_name,
+        "config_path": config_path,
+        "destination": args.destination,
+        "auto_upload": not args.no_upload,
+        "unlimited": args.unlimited,
+        "dry_run": args.dry_run,
+        "target": args.target,
+    }
+
+    # Run async tool
+    try:
+        result = asyncio.run(install_skill_tool(tool_args))
+
+        # Print output
+        for content in result:
+            print(content.text)
+
+        # Return success/failure based on output
+        output_text = result[0].text
+        if "❌" in output_text and "WORKFLOW COMPLETE" not in output_text:
+            return 1
+        return 0
+
+    except KeyboardInterrupt:
+        print("\n\n⚠️  Workflow interrupted by user")
+        return 130  # Standard exit code for SIGINT
+    except Exception as e:
+        print(f"\n\n❌ Unexpected error: {str(e)}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())