agentskill-toolkit 0.1.0__py3-none-any.whl

agentskill_kit/forge.py

@@ -0,0 +1,346 @@
+"""Turn a task description into a tested skill with a language model.
+
+The loop is driven by this module, not by the model, so it works with small
+local models that cannot call tools reliably:
+
+    draft -> lint + scan + run tests -> score -> (feedback -> redraft) -> write
+
+Every candidate is judged by the same checks used by ``askit lint``, ``scan``
+and ``test``, so the score reflects real results, not the model's opinion.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from .config import memory_path
+from .providers import LLM
+from .scoring import Quality, evaluate_skill
+from .skillfile import discover_skills, load_skill, parse_skill_text, slugify, SkillError
+
+ALLOWED_TOP = {"SKILL.md"}
+ALLOWED_DIRS = {"scripts", "references", "assets", "tests", "evals"}
+MAX_FILES = 12
+MAX_FILE_BYTES = 120_000
+
+SYSTEM_PROMPT = """You write agent skills. A skill is a directory with a SKILL.md file that an AI coding agent reads when a task matches. You are precise, concise and you only write things that work.
+
+SKILL.md format:
+- It starts with YAML frontmatter between --- lines.
+- Required: name (lowercase letters, digits and single hyphens, max 64 characters, same as the directory name) and description (max 1024 characters).
+- The description is written in the third person. It states what the skill does AND when an agent should use it ("Use when the user asks to ...").
+- Optional: license, compatibility, metadata (version, author, tags as a list).
+- After the frontmatter: short markdown instructions with headings (when to use, how to run, output, examples, error handling). Keep it under 150 lines.
+
+If the task is best served by code, add scripts:
+- Python 3 standard library only, no network access, no file writes outside the working directory.
+- The script reads arguments or stdin and prints a result (JSON when the output is structured).
+- Add tests/cases.json so the skill can be verified. Schema:
+{
+  "entry": "scripts/tool.py",
+  "cases": [
+    {"name": "short name", "kind": "happy|edge|error", "args": ["--flag"], "stdin": "text",
+     "files": {"input.txt": "file content"}, "expect_exit": 0,
+     "stdout_contains": ["text"], "stdout_regex": "pattern", "stdout_json": {"key": "value"},
+     "stderr_contains": ["text"]}
+  ]
+}
+- Include at least three cases: one happy path, one edge case, one error case.
+- Only assert on output you are certain the script produces.
+If the task is only about process or judgment (for example writing commit messages), write instructions only: no scripts, no tests.
+
+Output format. Return every file in exactly this form and nothing else outside the blocks:
+=== FILE: SKILL.md ===
+(file content)
+=== END FILE ===
+=== FILE: scripts/tool.py ===
+(file content)
+=== END FILE ===
+Do not wrap file content in code fences. Allowed paths: SKILL.md, scripts/, references/, assets/, tests/, evals/."""
+
+
+class ForgeError(Exception):
+    pass
+
+
+@dataclass
+class Candidate:
+    round: int
+    files: Dict[str, str]
+    name: str
+    quality: Optional[Quality] = None
+    notes: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ForgeResult:
+    name: str = ""
+    path: Optional[Path] = None
+    quality: Optional[Quality] = None
+    rounds: int = 0
+    accepted: bool = False
+    written: bool = False
+    files: Dict[str, str] = field(default_factory=dict)
+    provider: str = ""
+    model: str = ""
+    notes: List[str] = field(default_factory=list)
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Parsing model output
+# ---------------------------------------------------------------------------
+
+_BLOCK_RE = re.compile(r"^=== FILE:\s*(.+?)\s*===[ \t]*\r?\n(.*?)\r?\n=== END FILE ===", re.S | re.M)
+_FENCE_RE = re.compile(r"```[ \t]*(?:file:|path:)?[ \t]*([\w./-]+\.[A-Za-z0-9]+|SKILL\.md)[ \t]*\r?\n(.*?)\r?\n```", re.S)
+
+
+def _unwrap_fence(content: str) -> str:
+    m = re.match(r"^\s*```[\w-]*[ \t]*\r?\n(.*?)\r?\n```\s*$", content, re.S)
+    return m.group(1) if m else content
+
+
+def _safe_path(path: str) -> Optional[str]:
+    p = path.strip().strip("`").replace("\\", "/").lstrip("./")
+    if not p or p.startswith("/") or ".." in p.split("/") or re.match(r"^[A-Za-z]:", p):
+        return None
+    if p in ALLOWED_TOP:
+        return p
+    parts = p.split("/")
+    if parts[0] in ALLOWED_DIRS and len(parts) >= 2 and len(parts) <= 4:
+        return p
+    return None
+
+
+def parse_files(reply: str) -> Tuple[Dict[str, str], List[str]]:
+    """Extract files from a model reply. Returns (files, notes)."""
+    notes: List[str] = []
+    raw: List[Tuple[str, str]] = [(m.group(1), m.group(2)) for m in _BLOCK_RE.finditer(reply)]
+    if not raw:
+        raw = [(m.group(1), m.group(2)) for m in _FENCE_RE.finditer(reply)]
+    if not raw:
+        stripped = reply.strip()
+        fence = re.search(r"```(?:markdown|md)?\s*\r?\n(---\r?\n.*?)\r?\n```", stripped, re.S)
+        if fence:
+            raw = [("SKILL.md", fence.group(1))]
+        elif stripped.startswith("---"):
+            raw = [("SKILL.md", stripped)]
+    if not raw:
+        return {}, ["no files found in the reply"]
+    prefix = ""
+    for path, _ in raw:
+        norm = path.strip().strip("`").replace("\\", "/")
+        if norm.endswith("/SKILL.md"):
+            prefix = norm[: -len("SKILL.md")]
+            break
+    files: Dict[str, str] = {}
+    for path, content in raw:
+        norm = path.strip().strip("`").replace("\\", "/")
+        if prefix and norm.startswith(prefix):
+            norm = norm[len(prefix):]
+        safe = _safe_path(norm)
+        if not safe:
+            notes.append("ignored file with unsupported path: %s" % path.strip())
+            continue
+        body = _unwrap_fence(content)
+        if len(body.encode("utf-8")) > MAX_FILE_BYTES:
+            notes.append("ignored oversized file: %s" % safe)
+            continue
+        files[safe] = body.rstrip("\n") + "\n"
+        if len(files) >= MAX_FILES:
+            notes.append("too many files; extra files ignored")
+            break
+    return files, notes
+
+
+# ---------------------------------------------------------------------------
+# Prompts
+# ---------------------------------------------------------------------------
+
+def build_task_prompt(task: str, context: str = "", name_hint: str = "", similar: Optional[List[str]] = None) -> str:
+    parts = ["Create a skill for this task:\n%s" % task.strip()]
+    if name_hint:
+        parts.append("Use this skill name: %s" % name_hint)
+    if context.strip():
+        parts.append("Source material to learn from (notes, transcript or runbook):\n---\n%s\n---" % context.strip()[:12000])
+    if similar:
+        parts.append("Skills that already exist locally (do not duplicate them, be clearly different):\n- "
+                     + "\n- ".join(similar))
+    parts.append("Return the files now, using the exact === FILE: path === format.")
+    return "\n\n".join(parts)
+
+
+def build_feedback(candidate: Candidate, threshold: float) -> str:
+    q = candidate.quality
+    lines = ["The skill scored %.2f; the required score is %.2f. Fix these problems and return ALL files again "
+             "in the same === FILE: path === format." % (q.score if q else 0.0, threshold)]
+    if candidate.notes:
+        lines.append("Format notes: " + "; ".join(candidate.notes))
+    if q and q.lint:
+        issues = [i for i in q.lint.issues if i.severity in ("error", "warning")]
+        if issues:
+            lines.append("Lint issues:")
+            lines.extend("- [%s] %s (line %d)" % (i.code, i.message, i.line) for i in issues[:12])
+    if q and q.scan and q.scan.findings:
+        lines.append("Security findings (remove these patterns):")
+        lines.extend("- [%s] %s in %s line %d" % (f.rule, f.message, f.file, f.line)
+                     for f in q.scan.findings[:8] if f.severity in ("high", "medium"))
+    if q and q.tests:
+        if q.tests.refused:
+            lines.append("Tests were not run: " + q.tests.refused)
+        failed = [c for c in q.tests.cases if not c.passed]
+        if failed:
+            lines.append("Failing tests:")
+            lines.extend("- %s: %s" % (c.name, c.detail) for c in failed[:8])
+        elif not q.tests.has_tests and any(p.startswith("scripts/") for p in candidate.files):
+            lines.append("The skill has scripts but no tests/cases.json. Add at least three cases.")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Writing candidates
+# ---------------------------------------------------------------------------
+
+def _skill_name(files: Dict[str, str], fallback: str) -> str:
+    if "SKILL.md" in files:
+        parsed = parse_skill_text(files["SKILL.md"])
+        n = parsed.meta.get("name")
+        if isinstance(n, str) and n.strip():
+            return n.strip()
+    return slugify(fallback)
+
+
+def write_files(base: Path, files: Dict[str, str]) -> None:
+    for rel, content in files.items():
+        target = base / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+
+
+def _similar_local(task: str, dirs: List[Path]) -> List[str]:
+    words = {w for w in re.findall(r"[a-z]{4,}", task.lower())}
+    hits: List[Tuple[int, str]] = []
+    for d in dirs:
+        for sd in discover_skills(d, max_depth=3):
+            try:
+                s = load_skill(sd)
+            except SkillError:
+                continue
+            blob = (s.name + " " + s.description).lower()
+            overlap = sum(1 for w in words if w in blob)
+            if overlap >= 2:
+                hits.append((overlap, "%s: %s" % (s.name, s.description[:100])))
+    hits.sort(reverse=True)
+    return [h[1] for h in hits[:5]]
+
+
+def remember(entry: Dict[str, Any]) -> None:
+    try:
+        with open(memory_path(), "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except OSError:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+def forge(task: str, llm: LLM, out_dir: Any, threshold: float = 0.8, max_rounds: int = 3,
+          force: bool = False, dry_run: bool = False, context: str = "", name_hint: str = "",
+          check_duplicates: bool = True, log: Optional[Callable[[str], None]] = None,
+          work_dir: Optional[Path] = None) -> ForgeResult:
+    import tempfile
+
+    say = log or (lambda msg: None)
+    if not task.strip() and not context.strip():
+        raise ForgeError("describe the task with --task or provide --from-file")
+    out = Path(out_dir).expanduser()
+    similar = _similar_local(task + " " + context[:400], [out]) if check_duplicates else []
+    if similar:
+        say("Similar skills already exist: " + "; ".join(s.split(":")[0] for s in similar))
+
+    messages: List[Dict[str, str]] = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": build_task_prompt(task, context, name_hint, similar)},
+    ]
+    result = ForgeResult(provider=llm.name, model=llm.model)
+    best: Optional[Candidate] = None
+    tmp_root = Path(tempfile.mkdtemp(prefix="askit-forge-")) if work_dir is None else Path(work_dir)
+
+    try:
+        for rnd in range(1, max(1, max_rounds) + 1):
+            say("round %d/%d: asking %s" % (rnd, max_rounds, llm.describe()))
+            reply = llm.chat(messages)
+            result.prompt_tokens += reply.prompt_tokens
+            result.completion_tokens += reply.completion_tokens
+            files, notes = parse_files(reply.content)
+            messages.append({"role": "assistant", "content": reply.content})
+            if "SKILL.md" not in files:
+                cand = Candidate(rnd, files, name_hint or slugify(task[:40]), None, notes + ["SKILL.md is missing"])
+                messages.append({"role": "user", "content":
+                                 "Your reply did not contain a SKILL.md file in the required format. "
+                                 "Return all files using === FILE: path === and === END FILE === markers."})
+                say("round %d: no SKILL.md in the reply" % rnd)
+                result.rounds = rnd
+                continue
+            name = _skill_name(files, name_hint or task[:40])
+            cdir = tmp_root / ("r%d" % rnd) / name
+            if cdir.exists():
+                shutil.rmtree(cdir)
+            cdir.mkdir(parents=True)
+            write_files(cdir, files)
+            quality = evaluate_skill(cdir)
+            cand = Candidate(rnd, files, name, quality, notes)
+            result.rounds = rnd
+            say("round %d: %s score %.2f (%s), lint %d errors %d warnings, safety %d, tests %s" % (
+                rnd, name, quality.score, quality.grade, len(quality.lint.errors), len(quality.lint.warnings),
+                quality.scan.safety if quality.scan else 0,
+                "%d/%d" % (quality.tests.passed, quality.tests.total) if quality.tests and quality.tests.has_tests
+                else "none"))
+            if best is None or (cand.quality and best.quality and cand.quality.score > best.quality.score):
+                best = cand
+            if quality.score >= threshold and quality.passes_gate:
+                result.accepted = True
+                break
+            if rnd < max_rounds:
+                messages.append({"role": "user", "content": build_feedback(cand, threshold)})
+
+        if best is None or best.quality is None:
+            raise ForgeError("the model did not produce a usable skill. Try another model with --model")
+        result.name = best.name
+        result.quality = best.quality
+        result.files = best.files
+        result.notes = best.notes
+
+        if not result.accepted and not force:
+            remember({"event": "rejected", "name": best.name, "score": round(best.quality.score, 3),
+                      "rounds": result.rounds, "provider": llm.name, "model": llm.model,
+                      "task": task[:200], "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())})
+            return result
+        if dry_run:
+            return result
+
+        dest = out / best.name
+        if dest.exists():
+            if not force:
+                raise ForgeError("%s already exists. Use --force to overwrite or choose another --name" % dest)
+            shutil.rmtree(dest)
+        dest.mkdir(parents=True, exist_ok=True)
+        write_files(dest, best.files)
+        result.path = dest
+        result.written = True
+        remember({"event": "created", "name": best.name, "score": round(best.quality.score, 3),
+                  "rounds": result.rounds, "provider": llm.name, "model": llm.model, "task": task[:200],
+                  "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())})
+        return result
+    finally:
+        if work_dir is None:
+            shutil.rmtree(tmp_root, ignore_errors=True)

agentskill_kit/i18n.py

@@ -0,0 +1,107 @@
+"""Interface strings. Rule messages and docs stay in English; the CLI chrome is translated."""
+
+from __future__ import annotations
+
+import locale
+import os
+from typing import Dict
+
+_LANG = "en"
+
+STRINGS: Dict[str, Dict[str, str]] = {
+    "en": {
+        "no_skills": "No skills found in {path}",
+        "lint_title": "Lint",
+        "scan_title": "Security scan",
+        "test_title": "Tests",
+        "score": "score",
+        "no_issues": "no issues",
+        "no_findings": "no findings",
+        "summary_lint": "{n} skill(s) checked: {e} error(s), {w} warning(s)",
+        "summary_scan": "{n} skill(s) scanned: {h} high, {m} medium, {l} low",
+        "summary_test": "{p}/{t} test case(s) passed across {n} skill(s)",
+        "no_tests": "no tests (instruction-only skill)",
+        "created": "Created {path}",
+        "exists": "{path} already exists (use --force to overwrite)",
+        "forge_start": "Forging a skill with {provider} ({model})",
+        "forge_round": "Round {n}/{total}",
+        "forge_done": "Skill written to {path} (score {score})",
+        "forge_below": "Best score {score} is below the threshold {threshold}; saved anyway because of --force",
+        "forge_rejected": "Best score {score} is below the threshold {threshold}; nothing written (lower --threshold or use --force)",
+        "exported": "Exported {name} to {target}",
+        "installed": "Installed {name} ({target})",
+        "uninstalled": "Removed {name}",
+        "packed": "Packed {path}",
+        "no_results": "No matching skills",
+        "mine_none": "No repeated workflows found (try --min-count 2)",
+        "mine_found": "Found {n} repeated workflow(s)",
+        "serving": "Serving on {url} (Ctrl+C to stop)",
+        "doctor_title": "Environment check",
+        "gate_failed": "Gate failed: {reason}",
+        "published": "Ready to publish {name}",
+        "provider_missing": "No LLM provider is configured. See: askit providers",
+        "threshold_note": "Quality gate: {threshold}",
+    },
+    "tr": {
+        "no_skills": "{path} içinde skill bulunamadı",
+        "lint_title": "Lint",
+        "scan_title": "Güvenlik taraması",
+        "test_title": "Testler",
+        "score": "puan",
+        "no_issues": "sorun yok",
+        "no_findings": "bulgu yok",
+        "summary_lint": "{n} skill kontrol edildi: {e} hata, {w} uyarı",
+        "summary_scan": "{n} skill tarandı: {h} yüksek, {m} orta, {l} düşük",
+        "summary_test": "{n} skill içinde {p}/{t} test senaryosu başarılı",
+        "no_tests": "test yok (yalnızca talimat içeren skill)",
+        "created": "{path} oluşturuldu",
+        "exists": "{path} zaten var (üzerine yazmak için --force kullanın)",
+        "forge_start": "{provider} ({model}) ile skill üretiliyor",
+        "forge_round": "Tur {n}/{total}",
+        "forge_done": "Skill {path} konumuna yazıldı (puan {score})",
+        "forge_below": "En iyi puan {score}, eşik {threshold} altında; --force nedeniyle yine de kaydedildi",
+        "forge_rejected": "En iyi puan {score}, eşik {threshold} altında; hiçbir şey yazılmadı (--threshold değerini düşürün veya --force kullanın)",
+        "exported": "{name}, {target} hedefine aktarıldı",
+        "installed": "{name} kuruldu ({target})",
+        "uninstalled": "{name} kaldırıldı",
+        "packed": "{path} paketlendi",
+        "no_results": "Eşleşen skill yok",
+        "mine_none": "Tekrar eden iş akışı bulunamadı (--min-count 2 deneyin)",
+        "mine_found": "{n} tekrar eden iş akışı bulundu",
+        "serving": "{url} adresinde çalışıyor (durdurmak için Ctrl+C)",
+        "doctor_title": "Ortam kontrolü",
+        "gate_failed": "Kapı geçilemedi: {reason}",
+        "published": "{name} yayına hazır",
+        "provider_missing": "Yapılandırılmış bir LLM sağlayıcı yok. Bkz: askit providers",
+        "threshold_note": "Kalite eşiği: {threshold}",
+    },
+}
+
+
+def set_lang(lang: str) -> None:
+    global _LANG
+    lang = (lang or "en").lower()[:2]
+    _LANG = lang if lang in STRINGS else "en"
+
+
+def get_lang() -> str:
+    return _LANG
+
+
+def detect_lang() -> str:
+    env = os.environ.get("ASKIT_LANG")
+    if env:
+        return env.lower()[:2]
+    try:
+        loc = locale.getlocale()[0] or os.environ.get("LANG", "")
+    except Exception:
+        loc = os.environ.get("LANG", "")
+    return "tr" if str(loc).lower().startswith("tr") else "en"
+
+
+def t(key: str, **kwargs) -> str:
+    text = STRINGS.get(_LANG, {}).get(key) or STRINGS["en"].get(key) or key
+    try:
+        return text.format(**kwargs)
+    except (KeyError, IndexError):
+        return text

agentskill_kit/install.py

@@ -0,0 +1,212 @@
+"""Install skills from a registry, a GitHub repository or a local folder.
+
+Every download is verified against the checksums in the registry index (when
+there is one) and is linted and scanned before it is placed anywhere.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import shutil
+import tempfile
+import urllib.parse
+import urllib.request
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from . import registry
+from .config import DEFAULT_REGISTRY, get_setting, ledger_path
+from .export import ExportError, export_skill, remove_skill
+from .lint import lint_skill
+from .scan import scan_skill
+from .skillfile import SkillError, load_skill
+
+
+class InstallError(Exception):
+    pass
+
+
+def _safe_rel(rel: str) -> bool:
+    p = Path(rel)
+    return bool(rel) and not p.is_absolute() and ".." not in p.parts and not re.match(r"^[A-Za-z]:", rel)
+
+
+def load_ledger() -> Dict[str, Any]:
+    p = ledger_path()
+    if not p.exists():
+        return {"installed": []}
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        data.setdefault("installed", [])
+        return data
+    except (OSError, ValueError):
+        return {"installed": []}
+
+
+def save_ledger(data: Dict[str, Any]) -> None:
+    ledger_path().write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _github_get(url: str) -> Any:
+    headers = {"User-Agent": registry.USER_AGENT, "Accept": "application/vnd.github+json"}
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = "Bearer " + token
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def parse_github_ref(spec: str) -> Tuple[str, str, str, str]:
+    """github:owner/repo/path/to/skill@ref -> (owner, repo, path, ref)."""
+    body = spec[len("github:"):] if spec.startswith("github:") else spec
+    body = re.sub(r"^https?://github\.com/", "", body)
+    ref = ""
+    if "@" in body:
+        body, ref = body.rsplit("@", 1)
+    m = re.match(r"^([\w.-]+)/([\w.-]+)(?:/(?:tree/[^/]+/)?(.*))?$", body)
+    if not m:
+        raise InstallError("expected github:owner/repo[/path][@ref], got %r" % spec)
+    return m.group(1), m.group(2), (m.group(3) or "").strip("/"), ref
+
+
+def _download_github(spec: str, dest: Path) -> str:
+    owner, repo, path, ref = parse_github_ref(spec)
+    api = "https://api.github.com/repos/%s/%s/contents/%s" % (owner, repo, urllib.parse.quote(path))
+    if ref:
+        api += "?ref=" + urllib.parse.quote(ref)
+
+    def walk(url: str, target: Path, depth: int = 0) -> None:
+        if depth > 5:
+            return
+        data = _github_get(url)
+        if isinstance(data, dict):
+            data = [data]
+        for item in data:
+            name = item.get("name", "")
+            if not _safe_rel(name):
+                continue
+            if item.get("type") == "dir":
+                walk(item["url"], target / name, depth + 1)
+            elif item.get("type") == "file" and item.get("download_url"):
+                if item.get("size", 0) > 2_000_000:
+                    continue
+                target.mkdir(parents=True, exist_ok=True)
+                (target / name).write_bytes(registry.fetch_bytes(item["download_url"]))
+
+    walk(api, dest)
+    return "github:%s/%s/%s" % (owner, repo, path)
+
+
+def _download_registry(entry: Dict[str, Any], index: Dict[str, Any], source: str, dest: Path) -> None:
+    base = index.get("base_url") or ""
+    is_remote = bool(re.match(r"^[a-z][a-z0-9+.-]*://", source, re.I))
+    local_root = None if is_remote else Path(source).expanduser().resolve().parent.parent
+    for f in entry.get("files", []):
+        rel = f["path"]
+        if not _safe_rel(rel) or not _safe_rel(entry["path"]):
+            raise InstallError("registry lists an unsafe file path: %s" % rel)
+        candidate = (local_root / entry["path"] / rel) if local_root else None
+        if candidate is not None and candidate.is_file():
+            data = candidate.read_bytes()
+        elif base.startswith("http"):
+            data = registry.fetch_bytes(base.rstrip("/") + "/" + entry["path"].strip("/") + "/" + rel)
+        else:
+            raise InstallError("cannot locate %s (registry has no usable base_url)" % rel)
+        digest = hashlib.sha256(data).hexdigest()
+        if f.get("sha256") and digest != f["sha256"]:
+            raise InstallError("checksum mismatch for %s (expected %s, got %s)" % (rel, f["sha256"][:12], digest[:12]))
+        out = dest / rel
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_bytes(data)
+
+
+def vet(path: Path) -> Tuple[List[str], List[str]]:
+    """Return (blocking_reasons, warnings) for a downloaded skill."""
+    blocking: List[str] = []
+    notes: List[str] = []
+    lint = lint_skill(path)
+    if lint.errors:
+        blocking.append("lint errors: " + "; ".join("[%s] %s" % (i.code, i.message) for i in lint.errors[:3]))
+    scan = scan_skill(path)
+    if scan.count("high"):
+        blocking.append("security scan found %d high severity issue(s): %s" % (
+            scan.count("high"), ", ".join(sorted({f.rule for f in scan.findings if f.severity == "high"}))))
+    if scan.count("medium"):
+        notes.append("%d medium severity finding(s); run: askit scan %s" % (scan.count("medium"), path.name))
+    return blocking, notes
+
+
+def install(source: str, target: str = "claude", base: Optional[Path] = None, global_: bool = False,
+            registry_url: Optional[str] = None, force: bool = False, dry_run: bool = False) -> Dict[str, Any]:
+    """Install a skill. `source` is a registry name, a local path or github:owner/repo/path."""
+    tmp = Path(tempfile.mkdtemp(prefix="askit-install-"))
+    try:
+        origin = ""
+        version = ""
+        if source.startswith("github:") or source.startswith("https://github.com/"):
+            staged = tmp / "skill"
+            origin = _download_github(source, staged)
+            if not (staged / "SKILL.md").exists():
+                subs = [d for d in staged.iterdir() if d.is_dir() and (d / "SKILL.md").exists()] if staged.exists() else []
+                if len(subs) == 1:
+                    staged = subs[0]
+                else:
+                    raise InstallError("no SKILL.md found at %s" % source)
+        elif Path(source).expanduser().exists():
+            src = Path(source).expanduser().resolve()
+            staged = tmp / src.name
+            shutil.copytree(src, staged, ignore=shutil.ignore_patterns("__pycache__", ".git", "*.pyc"))
+            origin = "local:%s" % src
+        else:
+            reg = registry_url or get_setting("registry") or DEFAULT_REGISTRY
+            index = registry.load_index(reg)
+            entry = registry.find(index, source)
+            if not entry:
+                close = [s["name"] for s in registry.search(index, source, limit=3)]
+                hint = (" Did you mean: %s?" % ", ".join(close)) if close else ""
+                raise InstallError("skill %r not found in %s.%s" % (source, reg, hint))
+            staged = tmp / entry["name"]
+            _download_registry(entry, index, reg, staged)
+            origin = "registry:%s" % reg
+            version = entry.get("version", "")
+
+        try:
+            skill = load_skill(staged)
+        except SkillError as exc:
+            raise InstallError(str(exc))
+        blocking, notes = vet(staged)
+        if blocking and not force:
+            raise InstallError("refusing to install %s: %s (use --force to override)" % (skill.name, " | ".join(blocking)))
+        if blocking:
+            notes.append("installed despite: " + " | ".join(blocking))
+        actions = export_skill(staged, target, base, global_, dry_run=dry_run)
+        if not dry_run:
+            ledger = load_ledger()
+            ledger["installed"] = [e for e in ledger["installed"]
+                                   if not (e["name"] == skill.name and e["target"] == target and e.get("global") == global_
+                                           and e.get("base") == str(base or Path.cwd()))]
+            ledger["installed"].append({"name": skill.name, "version": version or skill.version, "source": origin,
+                                        "target": target, "global": global_, "base": str(base or Path.cwd())})
+            save_ledger(ledger)
+        return {"name": skill.name, "version": version or skill.version, "target": target, "actions": actions,
+                "notes": notes, "source": origin}
+    except (ExportError, OSError, ValueError) as exc:
+        raise InstallError(str(exc))
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def uninstall(name: str, target: str = "claude", base: Optional[Path] = None, global_: bool = False) -> List[str]:
+    try:
+        done = remove_skill(name, target, base, global_)
+    except ExportError as exc:
+        raise InstallError(str(exc))
+    ledger = load_ledger()
+    ledger["installed"] = [e for e in ledger["installed"] if not (
+        e["name"] == name and e["target"] == target and e.get("global") == global_)]
+    save_ledger(ledger)
+    return done