1#!/usr/bin/env python3
2"""
3Skill Packager - Creates a distributable .skill file of a skill folder
4 
5Usage:
6    python utils/package_skill.py <path/to/skill-folder> [output-directory]
7 
8Example:
9    python utils/package_skill.py skills/public/my-skill
10    python utils/package_skill.py skills/public/my-skill ./dist
11"""
12 
13import fnmatch
14import sys
15import zipfile
16from pathlib import Path
17from scripts.quick_validate import validate_skill
18 
19# Patterns to exclude when packaging skills.
20EXCLUDE_DIRS = {"__pycache__", "node_modules"}
21EXCLUDE_GLOBS = {"*.pyc"}
22EXCLUDE_FILES = {".DS_Store"}
23# Directories excluded only at the skill root (not when nested deeper).
24ROOT_EXCLUDE_DIRS = {"evals"}
25 
26 
27def should_exclude(rel_path: Path) -> bool:
28    """Check if a path should be excluded from packaging."""
29    parts = rel_path.parts
30    if any(part in EXCLUDE_DIRS for part in parts):
31        return True
32    # rel_path is relative to skill_path.parent, so parts[0] is the skill
33    # folder name and parts[1] (if present) is the first subdir.
34    if len(parts) > 1 and parts[1] in ROOT_EXCLUDE_DIRS:
35        return True
36    name = rel_path.name
37    if name in EXCLUDE_FILES:
38        return True
39    return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS)
40 
41 
42def package_skill(skill_path, output_dir=None):
43    """
44    Package a skill folder into a .skill file.
45 
46    Args:
47        skill_path: Path to the skill folder
48        output_dir: Optional output directory for the .skill file (defaults to current directory)
49 
50    Returns:
51        Path to the created .skill file, or None if error
52    """
53    skill_path = Path(skill_path).resolve()
54 
55    # Validate skill folder exists
56    if not skill_path.exists():
57        print(f"❌ Error: Skill folder not found: {skill_path}")
58        return None
59 
60    if not skill_path.is_dir():
61        print(f"❌ Error: Path is not a directory: {skill_path}")
62        return None
63 
64    # Validate SKILL.md exists
65    skill_md = skill_path / "SKILL.md"
66    if not skill_md.exists():
67        print(f"❌ Error: SKILL.md not found in {skill_path}")
68        return None
69 
70    # Run validation before packaging
71    print("🔍 Validating skill...")
72    valid, message = validate_skill(skill_path)
73    if not valid:
74        print(f"❌ Validation failed: {message}")
75        print("   Please fix the validation errors before packaging.")
76        return None
77    print(f"✅ {message}\n")
78 
79    # Determine output location
80    skill_name = skill_path.name
81    if output_dir:
82        output_path = Path(output_dir).resolve()
83        output_path.mkdir(parents=True, exist_ok=True)
84    else:
85        output_path = Path.cwd()
86 
87    skill_filename = output_path / f"{skill_name}.skill"
88 
89    # Create the .skill file (zip format)
90    try:
91        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
92            # Walk through the skill directory, excluding build artifacts
93            for file_path in skill_path.rglob('*'):
94                if not file_path.is_file():
95                    continue
96                arcname = file_path.relative_to(skill_path.parent)
97                if should_exclude(arcname):
98                    print(f"  Skipped: {arcname}")
99                    continue
100                zipf.write(file_path, arcname)
101                print(f"  Added: {arcname}")
102 
103        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
104        return skill_filename
105 
106    except Exception as e:
107        print(f"❌ Error creating .skill file: {e}")
108        return None
109 
110 
111def main():
112    if len(sys.argv) < 2:
113        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
114        print("\nExample:")
115        print("  python utils/package_skill.py skills/public/my-skill")
116        print("  python utils/package_skill.py skills/public/my-skill ./dist")
117        sys.exit(1)
118 
119    skill_path = sys.argv[1]
120    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
121 
122    print(f"📦 Packaging skill: {skill_path}")
123    if output_dir:
124        print(f"   Output directory: {output_dir}")
125    print()
126 
127    result = package_skill(skill_path, output_dir)
128 
129    if result:
130        sys.exit(0)
131    else:
132        sys.exit(1)
133 
134 
135if __name__ == "__main__":
136    main()
137