codymaster 4.1.3 → 4.3.0

package/skills/skill-creator-ultra/resources/versioning_guide.md

@@ -0,0 +1,193 @@
+# 🔄 Versioning Guide — Hướng Dẫn Nâng Cấp Skill Theo Thời Gian
+
+---
+
+## Tại sao cần Versioning?
+
+Skill không phải "tạo xong là xong". Theo thời gian:
+
+- 🔧 Tool/API thay đổi → Skill lỗi thời
+- 📈 Quy trình cải tiến → Cần cập nhật
+- 🐛 Phát hiện bugs → Cần fix
+- 💡 Có ý tưởng mới → Cần mở rộng
+
+---
+
+## Quy tắc Versioning
+
+### Semantic Versioning cho Skill: `vX.Y.Z`
+
+| Thay đổi | Version | Ví dụ |
+|---|---|---|
+| **MAJOR (X)** — Breaking change, thay đổi lớn | v1.0 → v**2**.0 | Viết lại Instructions, đổi pattern |
+| **MINOR (Y)** — Thêm tính năng, không phá cũ | v1.0 → v1.**1** | Thêm ví dụ, thêm constraint |
+| **PATCH (Z)** — Sửa lỗi nhỏ | v1.0.0 → v1.0.**1** | Fix typo, chỉnh wording |
+
+---
+
+## Cách ghi Version trong SKILL.md
+
+### Thêm vào cuối YAML frontmatter
+
+```markdown
+---
+name: my-skill
+description: ...
+version: 2.1.0
+last_updated: 2026-06-15
+---
+```
+
+### Thêm Changelog section
+
+```markdown
+# Changelog
+
+## v2.1.0 (2026-06-15)
+### Added
+- Thêm ví dụ edge case cho input Unicode
+- Thêm constraint: Không xóa file gốc
+
+### Changed
+- Cải thiện Step 3: Thêm validation sau transform
+
+## v2.0.0 (2026-04-01) — BREAKING
+### Changed
+- Viết lại Instructions theo chuỗi pipeline
+- Đổi từ Pattern Basic → Pattern Pipeline
+
+### Removed
+- Bỏ Step cũ "Xử lý thủ công"
+
+## v1.0.0 (2026-03-03)
+- Initial release
+```
+
+---
+
+## Quy trình nâng cấp Skill
+
+### Step 1: Đánh giá (khi nào cần upgrade?)
+
+Checklist review hàng quý:
+
+- [ ] Skill có hoạt động đúng không? (Test với input mới)
+- [ ] Tool/API skill dùng có thay đổi không?
+- [ ] User phản hồi gì? Có pain point nào?
+- [ ] Có anti-pattern nào trong skill hiện tại không? (Xem `anti_patterns.md`)
+- [ ] Complexity có tăng không? Cần tách skill?
+
+### Step 2: Lên kế hoạch
+
+```markdown
+## Upgrade Plan: [tên-skill] v1.0 → v2.0
+
+### Mục tiêu:
+- [Gì cần thay đổi]
+
+### Thay đổi cụ thể:
+- [ ] Instructions bước X: Thêm validation
+- [ ] Examples: Thêm 1 edge case mới
+- [ ] Constraints: Thêm quy tắc bảo mật
+
+### Backward Compatibility:
+- Có phá gì không? [CÓ/KHÔNG]
+- Nếu CÓ → MAJOR version bump (v2.0)
+```
+
+### Step 3: Thực hiện
+
+1. Sửa SKILL.md
+2. Cập nhật version trong frontmatter
+3. Thêm entry vào Changelog
+4. Chạy validate_skill.py
+5. Test với input mẫu
+
+### Step 4: Deploy
+
+1. Copy file mới vào đúng vị trí (global/workspace)
+2. Mở chat mới để AI reload skill
+3. Test lại 1 lần
+
+---
+
+## Template Changelog Entry
+
+```markdown
+## vX.Y.Z (YYYY-MM-DD)
+
+### Added
+- [Tính năng mới / Ví dụ mới / Constraint mới]
+
+### Changed
+- [Thay đổi behavior / Cải thiện instruction]
+
+### Fixed
+- [Bug fix / Typo fix]
+
+### Removed
+- [Chức năng bị bỏ]
+
+### Deprecated
+- [Chức năng sẽ bỏ trong tương lai]
+
+### Security
+- [Cải thiện bảo mật]
+```
+
+---
+
+## Branching Strategy (Cho team dùng Git)
+
+```
+main branch:     Skill production (đang dùng)
+develop branch:  Skill đang phát triển
+feature/xxx:     Tính năng mới cho skill
+```
+
+### Workflow
+
+```mermaid
+gitgraph
+    commit id:"v1.0.0 release"
+    branch develop
+    commit id:"Thêm ví dụ mới"
+    commit id:"Fix constraint"
+    checkout main
+    merge develop id:"v1.1.0 release"
+    branch feature/safety
+    commit id:"Thêm Safety Check"
+    checkout develop
+    merge feature/safety
+    checkout main  
+    merge develop id:"v2.0.0 release"
+```
+
+---
+
+## Quy tắc Deprecation
+
+Khi cần bỏ tính năng:
+
+1. **Ghi chú Deprecated** trong MINOR version (v1.2)
+
+```markdown
+# Instructions
+## Step 3: [DEPRECATED — Sẽ bỏ ở v2.0]
+Dùng Step 3b thay thế.
+
+## Step 3b: (Mới)
+...
+```
+
+1. **Xóa thực sự** trong MAJOR version (v2.0)
+
+2. **Ghi vào Changelog:**
+
+```markdown
+### Deprecated (v1.2.0)
+- Step 3 "Xử lý thủ công" — Dùng Step 3b "Xử lý tự động" thay thế
+
+### Removed (v2.0.0)
+- Step 3 "Xử lý thủ công" — Đã bỏ hoàn toàn
+```

package/skills/skill-creator-ultra/scripts/ci_eval.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""
+ci_eval.py — Chạy skill eval trong CI/CD pipeline.
+
+Đọc eval_results.json, kiểm tra pass/fail, return exit code phù hợp.
+Dùng trong GitHub Actions, GitLab CI, hoặc bất kỳ CI system nào.
+
+Usage:
+    python ci_eval.py <path/to/eval_results.json> [--min-score 80] [--strict]
+
+Options:
+    --min-score N     Minimum overall score % to pass (default: 80)
+    --strict          Fail on any security warning (not just critical fails)
+    --format text|json    Output format (default: text)
+    --badge           Generate badge-compatible output
+
+Examples:
+    # Basic: pass if score >= 80%
+    python ci_eval.py evals/eval_results.json
+
+    # Strict: pass if score >= 90% and zero security issues
+    python ci_eval.py evals/eval_results.json --min-score 90 --strict
+
+    # In GitHub Actions:
+    # - name: Eval skill
+    #   run: python scripts/ci_eval.py evals/eval_results.json --min-score 85
+"""
+
+import json
+import sys
+import argparse
+from pathlib import Path
+
+
+def grade_from_score(score):
+    """Convert percentage score to letter grade."""
+    if score >= 95:
+        return "S"
+    elif score >= 90:
+        return "A"
+    elif score >= 80:
+        return "B"
+    elif score >= 70:
+        return "C"
+    elif score >= 60:
+        return "D"
+    else:
+        return "F"
+
+
+def check_security(security, strict=False):
+    """Check security results. Returns (passed, issues)."""
+    issues = []
+    critical_checks = ["prompt_injection", "pii_exposure", "secret_leakage"]
+    warning_checks = ["scope_escape", "destructive_commands"]
+
+    for check in critical_checks:
+        result = security.get(check, "unknown")
+        if result not in ("pass", "PASS"):
+            issues.append(f"🔴 CRITICAL: {check} = {result}")
+
+    for check in warning_checks:
+        result = security.get(check, "unknown")
+        if result not in ("pass", "PASS"):
+            issues.append(f"🟡 WARNING: {check} = {result}")
+
+    if strict:
+        return len(issues) == 0, issues
+
+    # Non-strict: only fail on critical
+    critical_issues = [i for i in issues if "CRITICAL" in i]
+    return len(critical_issues) == 0, issues
+
+
+def format_text(data, score, grade, security_passed, security_issues, min_score, verdict):
+    """Format output as human-readable text."""
+    lines = []
+    lines.append("=" * 50)
+    lines.append(f"📊 CI EVAL REPORT — {data.get('skill', 'unknown')}")
+    lines.append("=" * 50)
+    lines.append("")
+
+    # Test results
+    tests = data.get("tests", [])
+    if tests:
+        lines.append("📋 Test Results:")
+        for t in tests:
+            name = t.get("name", "?")
+            ws = t.get("weighted_score", 0)
+            pr = t.get("pass_rate", 0)
+            lines.append(f"  {name}: {ws*100:.0f}% (pass rate: {pr*100:.0f}%)")
+        lines.append("")
+
+    # Dimensions (average across tests)
+    if tests and tests[0].get("dimensions"):
+        lines.append("📊 Dimension Averages:")
+        dim_keys = ["correctness", "completeness", "format", "adherence",
+                     "safety", "efficiency", "robustness"]
+        for dk in dim_keys:
+            vals = [t["dimensions"].get(dk, 0) for t in tests if "dimensions" in t]
+            avg = sum(vals) / len(vals) if vals else 0
+            bar = "█" * int(avg) + "░" * (5 - int(avg))
+            lines.append(f"  {dk:20s}  {avg:.1f}/5  {bar}")
+        lines.append("")
+
+    # Security
+    lines.append(f"🔐 Security: {'PASS ✅' if security_passed else 'FAIL ❌'}")
+    for issue in security_issues:
+        lines.append(f"  {issue}")
+    lines.append("")
+
+    # Overall
+    lines.append(f"📈 Overall Score: {score:.0f}% ({grade})")
+    lines.append(f"🎯 Minimum: {min_score}%")
+    lines.append(f"🏁 Verdict: {verdict}")
+    lines.append("=" * 50)
+
+    return "\n".join(lines)
+
+
+def format_json_output(data, score, grade, security_passed, security_issues, verdict):
+    """Format output as JSON for downstream tools."""
+    return json.dumps({
+        "skill": data.get("skill", "unknown"),
+        "score": round(score, 1),
+        "grade": grade,
+        "security_passed": security_passed,
+        "security_issues": security_issues,
+        "verdict": verdict
+    }, indent=2)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="CI/CD Skill Eval Checker — validate eval_results.json"
+    )
+    parser.add_argument("eval_file", help="Path to eval_results.json")
+    parser.add_argument("--min-score", type=float, default=80,
+                        help="Minimum overall score %% to pass (default: 80)")
+    parser.add_argument("--strict", action="store_true",
+                        help="Fail on any security warning (not just criticals)")
+    parser.add_argument("--format", choices=["text", "json"], default="text",
+                        help="Output format")
+    parser.add_argument("--badge", action="store_true",
+                        help="Print badge-compatible single line")
+    args = parser.parse_args()
+
+    # Read eval results
+    eval_path = Path(args.eval_file)
+    if not eval_path.exists():
+        print(f"❌ File not found: {eval_path}")
+        sys.exit(2)
+
+    try:
+        data = json.loads(eval_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        print(f"❌ Invalid JSON: {e}")
+        sys.exit(2)
+
+    # Extract score
+    score = data.get("overall_score", 0)
+    if isinstance(score, float) and score <= 1.0:
+        score *= 100  # Convert 0-1 to 0-100
+
+    grade = grade_from_score(score)
+
+    # Check security
+    security = data.get("security", {})
+    security_passed, security_issues = check_security(security, args.strict)
+
+    # Determine verdict
+    if not security_passed:
+        verdict = "BLOCKED_SECURITY"
+    elif score >= args.min_score:
+        verdict = "DEPLOY_OK"
+    else:
+        verdict = "NEEDS_ITERATION"
+
+    # Output
+    if args.badge:
+        emoji = "✅" if verdict == "DEPLOY_OK" else "❌"
+        print(f"{emoji} {grade} ({score:.0f}%) | Security: {'✅' if security_passed else '❌'}")
+    elif args.format == "json":
+        print(format_json_output(data, score, grade, security_passed,
+                                  security_issues, verdict))
+    else:
+        print(format_text(data, score, grade, security_passed,
+                          security_issues, args.min_score, verdict))
+
+    # Exit code
+    if verdict == "DEPLOY_OK":
+        sys.exit(0)
+    elif verdict == "BLOCKED_SECURITY":
+        sys.exit(3)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/skill-creator-ultra/scripts/package_skill.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+package_skill.py — Đóng gói skill thành file .skill (zip) để phân phối.
+
+Adapted from Anthropic's skill-creator package_skill.py.
+Standalone version — không dependency ngoài Python stdlib.
+
+Usage:
+    python package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python package_skill.py ~/.gemini/antigravity/skills/my-skill
+    python package_skill.py ~/.gemini/antigravity/skills/my-skill ./dist
+"""
+
+import fnmatch
+import sys
+import zipfile
+import yaml
+from pathlib import Path
+
+# Patterns to exclude when packaging
+EXCLUDE_DIRS = {"__pycache__", "node_modules", ".git", "evals"}
+EXCLUDE_GLOBS = {"*.pyc", "*.pyo"}
+EXCLUDE_FILES = {".DS_Store", "Thumbs.db"}
+
+
+def should_exclude(rel_path: Path) -> bool:
+    """Check if a path should be excluded from packaging."""
+    parts = rel_path.parts
+    if any(part in EXCLUDE_DIRS for part in parts):
+        return True
+    name = rel_path.name
+    if name in EXCLUDE_FILES:
+        return True
+    return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS)
+
+
+def validate_skill(skill_path: Path) -> tuple:
+    """
+    Validate skill structure — standalone version.
+    Returns (is_valid: bool, message: str).
+    """
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    content = skill_md.read_text(encoding="utf-8")
+
+    # Check YAML frontmatter
+    if not content.startswith("---"):
+        return False, "SKILL.md missing YAML frontmatter (---)"
+
+    try:
+        end = content.index("---", 3)
+        frontmatter = content[3:end].strip()
+        meta = yaml.safe_load(frontmatter)
+    except (ValueError, yaml.YAMLError) as e:
+        return False, f"Invalid YAML frontmatter: {e}"
+
+    if not meta or not isinstance(meta, dict):
+        return False, "YAML frontmatter is empty"
+
+    if "name" not in meta:
+        return False, "Missing 'name' in frontmatter"
+
+    if "description" not in meta:
+        return False, "Missing 'description' in frontmatter"
+
+    desc = str(meta.get("description", ""))
+    if len(desc) < 20:
+        return False, f"Description too short ({len(desc)} chars) — minimum 20"
+
+    return True, f"Valid skill: {meta['name']}"
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a .skill file (zip format).
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory (defaults to cwd)
+
+    Returns:
+        Path to created .skill file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    if not skill_path.exists():
+        print(f"❌ Error: Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"❌ Error: Not a directory: {skill_path}")
+        return None
+
+    # Validate before packaging
+    print("🔍 Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"❌ Validation failed: {message}")
+        return None
+    print(f"✅ {message}\n")
+
+    # Output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    skill_filename = output_path / f"{skill_name}.skill"
+
+    # Create .skill file (zip)
+    try:
+        file_count = 0
+        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            for file_path in sorted(skill_path.rglob('*')):
+                if not file_path.is_file():
+                    continue
+                arcname = file_path.relative_to(skill_path.parent)
+                if should_exclude(arcname):
+                    print(f"  ⏭ Skipped: {arcname}")
+                    continue
+                zipf.write(file_path, arcname)
+                print(f"  📄 Added: {arcname}")
+                file_count += 1
+
+        size_kb = skill_filename.stat().st_size / 1024
+        print(f"\n✅ Packaged {file_count} files → {skill_filename}")
+        print(f"📦 Size: {size_kb:.1f} KB")
+        return skill_filename
+
+    except Exception as e:
+        print(f"❌ Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("📦 Skill Packager — Đóng gói skill thành .skill file")
+        print()
+        print("Usage: python package_skill.py <path/to/skill> [output-dir]")
+        print()
+        print("Example:")
+        print("  python package_skill.py ~/.gemini/antigravity/skills/my-skill")
+        print("  python package_skill.py ./my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"📦 Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+    sys.exit(0 if result else 1)
+
+
+if __name__ == '__main__':
+    main()