skillchef 0.2.0__tar.gz

skillchef-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env

skillchef-0.2.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: skillchef
+Version: 0.2.0
+Summary: pyenv + git for agent skills. Cook, flavor, and sync skills from any source.
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.3.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: litellm>=1.81.11
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=14.3.2
+Requires-Dist: tomli-w>=1.2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.3.0; extra == 'test'

skillchef-0.2.0/README.md

@@ -0,0 +1,56 @@
+# skillchef
+
+Cook, flavor & sync agent skills from any source.
+
+## Install
+
+```
+uvx skillchef
+uv tool install skillchef
+```
+
+## Usage
+
+```
+skillchef init                    # configure platforms, editor, AI model
+skillchef cook <source>           # import a skill (GitHub URL, HTTP URL, local path)
+skillchef sync [skill-name]       # pull upstream changes, merge with your flavor
+skillchef flavor [skill-name]     # edit local customizations in $EDITOR
+skillchef list                    # show all managed skills
+skillchef remove <skill-name>     # remove a skill and its symlinks
+```
+
+## How it works
+
+Skills are stored in `~/.skillchef/store/<name>/` with three layers:
+
+```
+base/       ← pristine copy from remote
+flavor.md   ← your local additions (optional)
+live/       ← merged result (base + flavor), symlinked into platform dirs
+```
+
+`cook` fetches a skill and symlinks it into your configured platform directories (`~/.codex/skills/`, `~/.cursor/skills/`, etc).
+
+`sync` checks the remote for changes. If your skill has a flavor, it shows the upstream diff and proposes a semantic merge via LLM (auto-detected from env API keys).
+
+`flavor` opens your editor to add local customizations that persist across syncs.
+
+## Remote sources
+
+- **GitHub**: `https://github.com/user/repo/tree/main/path/to/skill`
+- **HTTP**: any direct URL to a SKILL.md file
+- **Local**: path to a skill directory or file on disk
+
+## Testing
+
+```
+python -m pip install -e ".[test]"
+pytest -q
+```
+
+The suite lives in `tests/` and focuses on:
+- storage lifecycle (`cook`, `rebuild_live`, `remove`)
+- remote source classification/fetch behavior
+- merge semantics and flavor application
+- key sync command branches (no-flavor update and AI-merge path)

skillchef-0.2.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skillchef"
+version = "0.2.0"
+description = "pyenv + git for agent skills. Cook, flavor, and sync skills from any source."
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+    "click>=8.3.1",
+    "rich>=14.3.2",
+    "httpx>=0.28.1",
+    "tomli-w>=1.2.0",
+    "litellm>=1.81.11",
+    "questionary>=2.1.0",
+]
+
+[project.scripts]
+skillchef = "skillchef.cli:main"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.3.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skillchef"]

skillchef-0.2.0/src/skillchef/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

skillchef-0.2.0/src/skillchef/cli.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import click
+
+from skillchef.commands import (
+    cook_cmd,
+    flavor_cmd,
+    init_cmd,
+    list_cmd as list_command,
+    remove_cmd,
+    sync_cmd,
+)
+
+
+@click.group()
+def main() -> None:
+    """skillchef — cook, flavor & sync your agent skills."""
+    pass
+
+
+@main.command()
+def init() -> None:
+    """First-time setup: platforms, editor, model."""
+    init_cmd.run()
+
+
+@main.command()
+@click.argument("source")
+def cook(source: str) -> None:
+    """Import a skill from a remote source or local path."""
+    cook_cmd.run(source)
+
+
+@main.command()
+@click.argument("skill_name", required=False)
+@click.option("--no-ai", is_flag=True, help="Disable automatic AI merge proposals.")
+def sync(skill_name: str | None, no_ai: bool) -> None:
+    """Check remotes for updates and merge."""
+    sync_cmd.run(skill_name, no_ai)
+
+
+@main.command()
+@click.argument("skill_name", required=False)
+def flavor(skill_name: str | None) -> None:
+    """Add or edit a local flavor for a skill."""
+    flavor_cmd.run(skill_name)
+
+
+@main.command(name="list")
+def list_cmd() -> None:
+    """List all managed skills."""
+    list_command.run()
+
+
+@main.command()
+@click.argument("skill_name")
+def remove(skill_name: str) -> None:
+    """Remove a managed skill."""
+    remove_cmd.run(skill_name)
+
+
+if __name__ == "__main__":
+    main()

skillchef-0.2.0/src/skillchef/commands/__init__.py

@@ -0,0 +1 @@
+"""Namespaced command implementations for the Skillchef CLI."""

skillchef-0.2.0/src/skillchef/commands/common.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from skillchef import config, ui
+
+
+def ensure_config() -> dict[str, Any]:
+    cfg = config.load()
+    if not cfg.get("platforms"):
+        ui.warn("No config found. Run [bold]skillchef init[/bold] first.")
+        raise SystemExit(1)
+    return cfg
+
+
+def open_editor(path: Path) -> None:
+    cfg = config.load()
+    ed = config.editor(cfg)
+    subprocess.call([ed, str(path)])
+
+
+def cleanup_fetched(fetched_dir: Path) -> None:
+    root = fetched_dir.parent if fetched_dir.name == "skill" else fetched_dir
+    shutil.rmtree(root, ignore_errors=True)

skillchef-0.2.0/src/skillchef/commands/cook_cmd.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from skillchef import config, merge, remote, store, ui
+
+from .common import cleanup_fetched, ensure_config
+
+
+def run(source: str) -> None:
+    ui.banner()
+    cfg = ensure_config()
+
+    ui.info(f"Fetching from {source}...")
+    try:
+        fetched_dir, remote_type = remote.fetch(source)
+    except Exception as e:
+        ui.error(f"Failed to fetch: {e}")
+        raise SystemExit(1)
+
+    skill_md = fetched_dir / "SKILL.md"
+    default_name = fetched_dir.name
+    if skill_md.exists():
+        front, _ = merge.split_frontmatter(skill_md.read_text())
+        if "name:" in front:
+            for line in front.splitlines():
+                if line.strip().startswith("name:"):
+                    default_name = line.split(":", 1)[1].strip().strip('"').strip("'")
+                    break
+
+    name = ui.ask("Skill name", default=default_name)
+    platforms = ui.multi_choose("Target platforms", cfg.get("platforms", list(config.PLATFORMS.keys())))
+
+    store.cook(name, fetched_dir, source, remote_type, platforms)
+    cleanup_fetched(fetched_dir)
+
+    ui.success(f"Cooked [bold]{name}[/bold]!")
+    for p in platforms:
+        ui.info(f"Symlinked → {config.platform_skill_dir(p) / name}")

skillchef-0.2.0/src/skillchef/commands/flavor_cmd.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from skillchef import merge, store, ui
+
+from .common import ensure_config, open_editor
+
+
+def run(skill_name: str | None) -> None:
+    ui.banner()
+    ensure_config()
+
+    skills = store.list_skills()
+    if not skills:
+        ui.info("No skills cooked yet.")
+        return
+
+    if not skill_name:
+        names = [s["name"] for s in skills]
+        skill_name = ui.choose("Which skill?", names)
+
+    fp = store.flavor_path(skill_name)
+    if not fp.exists():
+        fp.write_text("# Add your local flavor below\n\n")
+
+    old_live = store.live_skill_text(skill_name)
+    open_editor(fp)
+    store.rebuild_live(skill_name)
+    new_live = store.live_skill_text(skill_name)
+
+    diff_lines = merge.diff_texts(old_live, new_live, "before", "after")
+    ui.show_diff(diff_lines)
+    ui.success(f"Flavor saved for [bold]{skill_name}[/bold]")

skillchef-0.2.0/src/skillchef/commands/init_cmd.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import os
+
+from skillchef import config, ui
+from skillchef.llm import detect_keys
+
+
+def run() -> None:
+    ui.banner()
+    ui.console.print()
+
+    ui.info("Scanning for agent platforms...\n")
+    ui.show_platforms(config.PLATFORMS)
+    ui.console.print()
+
+    detected = detect_keys()
+    ui.show_detected_keys(detected)
+    ui.console.print()
+
+    platforms = ui.multi_choose(
+        "Which platforms do you use?",
+        list(config.PLATFORMS.keys()),
+    )
+
+    editor = ui.ask("Preferred editor", default=os.environ.get("EDITOR", "vim"))
+
+    default_model = "anthropic/claude-sonnet-4-20250514"
+    selected_key_env = ""
+    if detected:
+        if len(detected) == 1:
+            selected_key_env, provider = detected[0]
+        else:
+            label_to_env = {f"{provider} ({env_var})": env_var for env_var, provider in detected}
+            key_choices = list(label_to_env.keys())
+            selected_label = ui.choose("Multiple LLM keys found. Which key should AI merge use?", key_choices)
+            selected_key_env = label_to_env[selected_label]
+            provider = next(p for env_var, p in detected if env_var == selected_key_env)
+        ui.info(f"AI merge will use [bold]{selected_key_env}[/bold] ({provider})")
+    model = ui.ask("AI model for semantic merge", default=default_model)
+
+    cfg = {"platforms": platforms, "editor": editor, "model": model, "llm_api_key_env": selected_key_env}
+    config.save(cfg)
+
+    ui.console.print()
+    ui.show_config_summary(cfg)
+    ui.console.print()
+    ui.success(f"Config saved to [bold]{config.CONFIG_PATH}[/bold]")

skillchef-0.2.0/src/skillchef/commands/list_cmd.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from skillchef import store, ui
+
+
+def run() -> None:
+    ui.banner()
+    ui.skill_table(store.list_skills(), has_flavor_fn=store.has_flavor)

skillchef-0.2.0/src/skillchef/commands/remove_cmd.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from skillchef import store, ui
+
+
+def run(skill_name: str) -> None:
+    ui.banner()
+    try:
+        store.load_meta(skill_name)
+    except FileNotFoundError:
+        ui.error(f"Skill '{skill_name}' not found.")
+        raise SystemExit(1)
+
+    if ui.confirm(f"Remove [bold]{skill_name}[/bold]?", default=False):
+        store.remove(skill_name)
+        ui.success(f"Removed {skill_name}")

skillchef-0.2.0/src/skillchef/commands/sync_cmd.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from concurrent.futures import Future, ThreadPoolExecutor
+from typing import Any
+
+from skillchef import config, merge, remote, store, ui
+from skillchef.llm import selected_key, semantic_merge
+
+from .common import cleanup_fetched, ensure_config, open_editor
+
+
+def run(skill_name: str | None, no_ai: bool) -> None:
+    ui.banner()
+    ensure_config()
+
+    cfg = config.load()
+    key = selected_key(cfg.get("llm_api_key_env", ""))
+    ai_available = key is not None and not no_ai
+    if ai_available and key:
+        ui.info(f"Using [bold]{key[0]}[/bold] ({key[1]}) for semantic merge")
+
+    skills = store.list_skills()
+    if not skills:
+        ui.info("No skills to sync.")
+        return
+
+    if skill_name:
+        skills = [s for s in skills if s["name"] == skill_name]
+        if not skills:
+            ui.error(f"Skill '{skill_name}' not found.")
+            raise SystemExit(1)
+
+    for meta in skills:
+        _sync_one(meta, ai_available=ai_available)
+
+
+def _sync_one(meta: dict[str, Any], ai_available: bool = False) -> None:
+    name = meta["name"]
+    ui.info(f"Syncing [bold]{name}[/bold]...")
+
+    try:
+        fetched_dir, _ = remote.fetch(meta["remote_url"])
+    except Exception as e:
+        ui.warn(f"  Could not fetch {name}: {e}")
+        return
+
+    new_hash = store.hash_dir(fetched_dir)
+    if new_hash == meta.get("base_sha256"):
+        ui.success(f"  {name}: up to date")
+        cleanup_fetched(fetched_dir)
+        return
+
+    old_base = store.base_skill_text(name)
+    new_remote = (fetched_dir / "SKILL.md").read_text() if (fetched_dir / "SKILL.md").exists() else ""
+    diff_lines = merge.diff_texts(old_base, new_remote, "base (current)", "remote (new)")
+
+    ai_future: Future[str] | None = None
+    flavor_text = ""
+    if store.has_flavor(name) and ai_available:
+        flavor_text = store.flavor_path(name).read_text()
+        executor = ThreadPoolExecutor(max_workers=1)
+        ai_future = executor.submit(semantic_merge, old_base, new_remote, flavor_text)
+
+    ui.show_diff(diff_lines)
+
+    if not store.has_flavor(name):
+        if ui.confirm("Accept update?"):
+            store.update_base(name, fetched_dir)
+            store.rebuild_live(name)
+            ui.success(f"  {name}: updated")
+        else:
+            ui.info(f"  {name}: skipped")
+    else:
+        if not flavor_text:
+            flavor_text = store.flavor_path(name).read_text()
+
+        ai_result = _resolve_ai_future(ai_future)
+        choices = ["accept + re-apply flavor", "keep current", "manual edit"]
+        if ai_result:
+            choices.insert(0, "accept ai merge")
+            ui.info("AI proposed a semantic merge:")
+            ai_diff = merge.diff_texts(store.live_skill_text(name), ai_result, "current", "ai proposed")
+            ui.show_diff(ai_diff)
+
+        action = ui.choose("How to handle?", choices)
+
+        if action == "accept ai merge" and ai_result:
+            store.update_base(name, fetched_dir)
+            live_md = store.skill_dir(name) / "live" / "SKILL.md"
+            live_md.write_text(ai_result)
+            ui.success(f"  {name}: AI merged")
+        elif action == "accept + re-apply flavor":
+            store.update_base(name, fetched_dir)
+            store.rebuild_live(name)
+            ui.success(f"  {name}: rebased with flavor")
+        elif action == "keep current":
+            ui.info(f"  {name}: skipped")
+        elif action == "manual edit":
+            store.update_base(name, fetched_dir)
+            store.rebuild_live(name)
+            open_editor(store.skill_dir(name) / "live" / "SKILL.md")
+            ui.success(f"  {name}: manually merged")
+
+    cleanup_fetched(fetched_dir)
+
+
+def _resolve_ai_future(future: Future[str] | None) -> str | None:
+    if future is None:
+        return None
+    try:
+        with ui.spinner("Waiting for AI merge proposal..."):
+            return future.result(timeout=60)
+    except Exception as e:
+        ui.warn(f"  AI merge failed: {e}")
+        return None

skillchef-0.2.0/src/skillchef/config.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+
+SKILLCHEF_HOME = Path.home() / ".skillchef"
+CONFIG_PATH = SKILLCHEF_HOME / "config.toml"
+STORE_DIR = SKILLCHEF_HOME / "store"
+
+PLATFORMS: dict[str, Path] = {
+    "codex": Path.home() / ".codex" / "skills",
+    "cursor": Path.home() / ".cursor" / "skills",
+    "claude-code": Path.home() / ".claude" / "skills",
+}
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "platforms": [],
+    "editor": "",
+    "model": "anthropic/claude-sonnet-4-20250514",
+    "llm_api_key_env": "",
+}
+
+
+def load() -> dict[str, Any]:
+    if not CONFIG_PATH.exists():
+        return dict(DEFAULT_CONFIG)
+    return tomllib.loads(CONFIG_PATH.read_text())
+
+
+def save(cfg: dict[str, Any]) -> None:
+    SKILLCHEF_HOME.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_bytes(tomli_w.dumps(cfg).encode())
+
+
+def editor(cfg: dict[str, Any] | None = None) -> str:
+    cfg = cfg or load()
+    return cfg.get("editor") or os.environ.get("EDITOR", "vim")
+
+
+def platform_skill_dir(platform: str) -> Path:
+    return PLATFORMS[platform]
+
+
+def ensure_store() -> Path:
+    STORE_DIR.mkdir(parents=True, exist_ok=True)
+    return STORE_DIR

skillchef-0.2.0/src/skillchef/llm.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import os
+
+from litellm import completion
+
+from skillchef import config
+
+LLM_KEY_MAP = [
+    ("ANTHROPIC_API_KEY", "Anthropic"),
+    ("OPENAI_API_KEY", "OpenAI"),
+    ("GEMINI_API_KEY", "Google Gemini"),
+    ("MISTRAL_API_KEY", "Mistral"),
+    ("COHERE_API_KEY", "Cohere"),
+    ("OLLAMA_API_BASE", "Ollama (local)"),
+]
+
+MERGE_PROMPT = """You are merging an agent skill file. The upstream base has changed.
+The user has a local "flavor" (customization) applied on top of the old base.
+
+Your job: produce a single merged SKILL.md that incorporates BOTH the new upstream
+changes AND the user's local flavor. Preserve the intent of both sides.
+
+Return ONLY the merged file content, no explanation.
+
+=== OLD BASE ===
+{old_base}
+
+=== NEW REMOTE (upstream update) ===
+{new_remote}
+
+=== USER'S LOCAL FLAVOR ===
+{flavor}
+
+=== MERGED RESULT ==="""
+
+
+def detect_keys() -> list[tuple[str, str]]:
+    return [(k, v) for k, v in LLM_KEY_MAP if os.environ.get(k)]
+
+
+def selected_key(preferred_env_var: str | None = None) -> tuple[str, str] | None:
+    keys = detect_keys()
+    if not keys:
+        return None
+    if preferred_env_var:
+        for env_var, provider in keys:
+            if env_var == preferred_env_var:
+                return env_var, provider
+    return keys[0]
+
+
+def has_llm() -> bool:
+    return len(detect_keys()) > 0
+
+
+def semantic_merge(old_base: str, new_remote: str, flavor: str, model: str | None = None) -> str:
+    cfg = config.load()
+    model = model or cfg.get("model", "anthropic/claude-sonnet-4-20250514")
+    configured_env = cfg.get("llm_api_key_env", "")
+    key = selected_key(configured_env)
+
+    completion_kwargs: dict[str, str | int | list[dict[str, str]]] = {}
+    if key:
+        env_var, _provider = key
+        value = os.environ.get(env_var, "")
+        if value:
+            if env_var == "OLLAMA_API_BASE":
+                completion_kwargs["api_base"] = value
+            else:
+                completion_kwargs["api_key"] = value
+
+    prompt = MERGE_PROMPT.format(old_base=old_base, new_remote=new_remote, flavor=flavor)
+    resp = completion(
+        model=model,
+        messages=[{"role": "user", "content": prompt}],
+        temperature=0,
+        **completion_kwargs,
+    )
+    return resp.choices[0].message.content.strip()

skillchef-0.2.0/src/skillchef/merge.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import difflib
+import re
+from pathlib import Path
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?\n)---\s*\n", re.DOTALL)
+FLAVOR_HEADER = "\n\n## Local Flavor\n\n"
+
+
+def split_frontmatter(text: str) -> tuple[str, str]:
+    m = FRONTMATTER_RE.match(text)
+    if m:
+        return text[: m.end()], text[m.end() :]
+    return "", text
+
+
+def merge_skill(live_skill_path: Path, flavor_path: Path) -> None:
+    base_text = live_skill_path.read_text()
+    flavor_text = flavor_path.read_text().strip()
+    if not flavor_text:
+        return
+    front, body = split_frontmatter(base_text)
+    body = body.rstrip()
+    merged = front + body + FLAVOR_HEADER + flavor_text + "\n"
+    live_skill_path.write_text(merged)
+
+
+def diff_texts(old: str, new: str, label_old: str = "old", label_new: str = "new") -> list[str]:
+    return list(difflib.unified_diff(
+        old.splitlines(keepends=True),
+        new.splitlines(keepends=True),
+        fromfile=label_old,
+        tofile=label_new,
+    ))
+
+
+def three_way_summary(old_base: str, new_remote: str, flavor: str) -> str:
+    lines = []
+    base_diff = diff_texts(old_base, new_remote, "base (old)", "remote (new)")
+    if base_diff:
+        lines.append("=== Upstream changes ===")
+        lines.extend(base_diff)
+    if flavor.strip():
+        lines.append("\n=== Your flavor ===")
+        lines.append(flavor)
+    return "".join(lines)