agentskill-toolkit 0.1.0__py3-none-any.whl

agentskill_kit/config.py

@@ -0,0 +1,104 @@
+"""Paths, user configuration and a tiny .env loader."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+DEFAULT_REPO = "Lethe044/agentskill-kit"
+DEFAULT_BRANCH = "main"
+RAW_BASE = "https://raw.githubusercontent.com/%s/%s/" % (DEFAULT_REPO, DEFAULT_BRANCH)
+DEFAULT_REGISTRY = RAW_BASE + "registry/index.json"
+DEFAULT_THRESHOLD = 0.8
+
+CONFIG_KEYS = {
+    "provider": "Default LLM provider (ollama, groq, gemini, openrouter, ...)",
+    "model": "Default model name for the provider",
+    "base_url": "Override the provider base URL",
+    "lang": "Interface language (en or tr)",
+    "registry": "Registry index URL or local path",
+    "threshold": "Minimum quality score (0-1) to accept a forged skill",
+    "max_rounds": "Maximum refinement rounds for forge",
+    "output_dir": "Default directory for forged skills",
+}
+
+
+def home_dir() -> Path:
+    """Directory for config, memory and the install ledger."""
+    env = os.environ.get("ASKIT_HOME")
+    p = Path(env).expanduser() if env else Path.home() / ".agentskill-kit"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def config_path() -> Path:
+    return home_dir() / "config.json"
+
+
+def load_config() -> Dict[str, Any]:
+    p = config_path()
+    if not p.exists():
+        return {}
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def save_config(data: Dict[str, Any]) -> None:
+    config_path().write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def get_setting(key: str, default: Any = None) -> Any:
+    env = os.environ.get("ASKIT_" + key.upper())
+    if env:
+        return env
+    return load_config().get(key, default)
+
+
+def set_setting(key: str, value: Any) -> None:
+    if key not in CONFIG_KEYS:
+        raise KeyError(key)
+    cfg = load_config()
+    if value is None or value == "":
+        cfg.pop(key, None)
+    else:
+        cfg[key] = value
+    save_config(cfg)
+
+
+def memory_path() -> Path:
+    return home_dir() / "memory.jsonl"
+
+
+def ledger_path() -> Path:
+    return home_dir() / "installed.json"
+
+
+def load_dotenv(path: Optional[Path] = None) -> int:
+    """Load KEY=VALUE pairs from .env into os.environ without overriding."""
+    p = path or Path.cwd() / ".env"
+    if not p.is_file():
+        return 0
+    count = 0
+    try:
+        for line in p.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            if line.startswith("export "):
+                line = line[7:]
+            key, _, val = line.partition("=")
+            key = key.strip()
+            val = val.strip()
+            if len(val) >= 2 and val[0] == val[-1] and val[0] in "\"'":
+                val = val[1:-1]
+            if key and key not in os.environ:
+                os.environ[key] = val
+                count += 1
+    except (OSError, UnicodeDecodeError):
+        return count
+    return count

agentskill_kit/evalrun.py

@@ -0,0 +1,95 @@
+"""Behaviour evals: does a model follow a skill better than it does without it?
+
+A skill may ship ``evals/evals.json``:
+
+    {"cases": [{"name": "...", "prompt": "...", "must_include": ["..."],
+                "must_not_include": ["..."], "regex": ["..."]}]}
+
+The prompt is sent to a model twice, once with the skill instructions in the
+system message and once without (``--baseline``). Checks are plain string
+and regex assertions, so results are reproducible and need no judge model.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .providers import LLM
+from .skillfile import SkillError, load_skill
+
+
+@dataclass
+class EvalCase:
+    name: str
+    passed: bool
+    detail: str = ""
+    baseline_passed: Optional[bool] = None
+    output: str = ""
+
+
+@dataclass
+class EvalReport:
+    skill: str
+    cases: List[EvalCase] = field(default_factory=list)
+    has_evals: bool = False
+
+    @property
+    def passed(self) -> int:
+        return sum(1 for c in self.cases if c.passed)
+
+    @property
+    def baseline_passed(self) -> Optional[int]:
+        vals = [c.baseline_passed for c in self.cases if c.baseline_passed is not None]
+        return sum(1 for v in vals if v) if vals else None
+
+
+def skill_system_prompt(name: str, description: str, body: str) -> str:
+    return ("You are a coding assistant. You have access to the following skill. Apply it when the request "
+            "matches its description.\n\nSkill name: %s\nDescription: %s\n\nInstructions:\n%s" % (name, description, body))
+
+
+def check_output(case: Dict[str, Any], output: str) -> str:
+    low = output.lower()
+    for s in case.get("must_include", []) or []:
+        if str(s).lower() not in low:
+            return "missing %r" % s
+    for s in case.get("must_not_include", []) or []:
+        if str(s).lower() in low:
+            return "contains forbidden %r" % s
+    for rx in case.get("regex", []) or []:
+        if not re.search(rx, output, re.M | re.I):
+            return "does not match /%s/" % rx
+    return ""
+
+
+def run_evals(skill_dir: Any, llm: LLM, baseline: bool = False, limit: int = 0) -> EvalReport:
+    skill = load_skill(skill_dir)
+    path = skill.path / "evals" / "evals.json"
+    report = EvalReport(skill=skill.name)
+    if not path.exists():
+        return report
+    report.has_evals = True
+    try:
+        spec = json.loads(path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        raise SkillError("evals/evals.json is not valid JSON: %s" % exc)
+    cases = spec.get("cases", [])
+    if limit:
+        cases = cases[:limit]
+    system = skill_system_prompt(skill.name, skill.description, skill.body)
+    for idx, case in enumerate(cases):
+        name = str(case.get("name") or "case %d" % (idx + 1))
+        prompt = str(case.get("prompt", ""))
+        out = llm.chat([{"role": "system", "content": system}, {"role": "user", "content": prompt}],
+                       temperature=0.0, max_tokens=1500).content
+        reason = check_output(case, out)
+        item = EvalCase(name, not reason, reason, output=out)
+        if baseline:
+            base_out = llm.chat([{"role": "user", "content": prompt}], temperature=0.0, max_tokens=1500).content
+            item.baseline_passed = not check_output(case, base_out)
+        report.cases.append(item)
+    return report

agentskill_kit/export.py

@@ -0,0 +1,188 @@
+"""Install a skill into the format used by different coding agents.
+
+Skill directories (Claude Code, Hermes) are copied as they are. Agents that
+use rule files or a single instructions file (Cursor, Windsurf, Copilot,
+Codex, Gemini CLI) get the skill converted: frontmatter is rewritten and the
+instructions are inlined. Managed blocks are marked so re-exporting updates
+them instead of duplicating them.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .skillfile import Skill, SkillError, _dump_scalar, iter_skill_files, load_skill
+
+BUNDLE_DIR = ".agent-skills"
+
+
+@dataclass
+class Target:
+    name: str
+    label: str
+    kind: str  # dir | file | block
+    project: str
+    global_: str = ""
+
+
+TARGETS: Dict[str, Target] = {
+    "claude": Target("claude", "Claude Code skills", "dir", ".claude/skills", "~/.claude/skills"),
+    "hermes": Target("hermes", "Hermes Agent skills", "dir", ".hermes/skills", "~/.hermes/skills"),
+    "cursor": Target("cursor", "Cursor project rules", "file", ".cursor/rules"),
+    "windsurf": Target("windsurf", "Windsurf rules", "file", ".windsurf/rules"),
+    "copilot": Target("copilot", "GitHub Copilot instructions", "file", ".github/instructions"),
+    "codex": Target("codex", "AGENTS.md (Codex and others)", "block", "AGENTS.md", "~/.codex/AGENTS.md"),
+    "gemini": Target("gemini", "Gemini CLI GEMINI.md", "block", "GEMINI.md", "~/.gemini/GEMINI.md"),
+}
+
+
+class ExportError(Exception):
+    pass
+
+
+def _begin(name: str) -> str:
+    return "<!-- agentskill-kit:begin %s -->" % name
+
+
+def _end(name: str) -> str:
+    return "<!-- agentskill-kit:end %s -->" % name
+
+
+def _extra_files(skill: Skill) -> List[Path]:
+    return [p for p in iter_skill_files(skill.path) if p.as_posix() != "SKILL.md"]
+
+
+def _footer(skill: Skill, extras: bool) -> str:
+    if not extras:
+        return ""
+    return "\n\nBundled files for this skill are in `%s/%s/`." % (BUNDLE_DIR, skill.name)
+
+
+def _copy_tree(skill: Skill, dest: Path) -> None:
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(skill.path, dest, ignore=shutil.ignore_patterns("__pycache__", ".git", "*.pyc"))
+
+
+def render_rule(skill: Skill, target: str, extras: bool) -> str:
+    body = skill.body.strip() + _footer(skill, extras)
+    desc = _dump_scalar(skill.description)
+    if target == "cursor":
+        return "---\ndescription: %s\nglobs:\nalwaysApply: false\n---\n\n%s\n" % (desc, body)
+    if target == "windsurf":
+        return "---\ntrigger: model_decision\ndescription: %s\n---\n\n%s\n" % (desc, body)
+    if target == "copilot":
+        return '---\napplyTo: "**"\n---\n\n# %s\n\n%s\n\n%s\n' % (skill.name, skill.description, body)
+    raise ExportError("no rule renderer for %s" % target)
+
+
+def render_block(skill: Skill, extras: bool) -> str:
+    body = skill.body.strip() + _footer(skill, extras)
+    return "%s\n## Skill: %s\n\n%s\n\n%s\n%s\n" % (_begin(skill.name), skill.name, skill.description, body,
+                                                    _end(skill.name))
+
+
+def _upsert_block(path: Path, skill: Skill, block: str) -> str:
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    pattern = re.compile(re.escape(_begin(skill.name)) + r".*?" + re.escape(_end(skill.name)) + r"\n?", re.S)
+    if pattern.search(text):
+        new = pattern.sub(lambda _m: block, text)
+        action = "updated"
+    else:
+        sep = "" if not text or text.endswith("\n\n") else ("\n" if text.endswith("\n") else "\n\n")
+        new = text + sep + block
+        action = "added"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(new, encoding="utf-8")
+    return action
+
+
+def destination(target: str, base: Optional[Path] = None, global_: bool = False) -> Path:
+    if target not in TARGETS:
+        raise ExportError("unknown target %r. Choose from: %s" % (target, ", ".join(TARGETS)))
+    t = TARGETS[target]
+    if global_:
+        if not t.global_:
+            raise ExportError("%s has no global location; export it into a project instead" % t.label)
+        return Path(t.global_).expanduser()
+    return (base or Path.cwd()) / t.project
+
+
+def export_skill(skill_path: Path, target: str, base: Optional[Path] = None, global_: bool = False,
+                 dry_run: bool = False) -> List[str]:
+    """Export one skill. Returns a list of human readable actions."""
+    try:
+        skill = load_skill(skill_path)
+    except SkillError as exc:
+        raise ExportError(str(exc))
+    t = TARGETS.get(target)
+    if t is None:
+        raise ExportError("unknown target %r. Choose from: %s" % (target, ", ".join(TARGETS)))
+    dest = destination(target, base, global_)
+    extras = bool(_extra_files(skill))
+    actions: List[str] = []
+
+    if t.kind == "dir":
+        out = dest / skill.name
+        actions.append("copy %s -> %s" % (skill.path, out))
+        if not dry_run:
+            dest.mkdir(parents=True, exist_ok=True)
+            _copy_tree(skill, out)
+    elif t.kind == "file":
+        ext = ".mdc" if target == "cursor" else (".instructions.md" if target == "copilot" else ".md")
+        out = dest / (skill.name + ext)
+        actions.append("write %s" % out)
+        if extras:
+            bundle = (base or Path.cwd()) / BUNDLE_DIR / skill.name
+            actions.append("copy bundled files -> %s" % bundle)
+        if not dry_run:
+            dest.mkdir(parents=True, exist_ok=True)
+            out.write_text(render_rule(skill, target, extras), encoding="utf-8")
+            if extras:
+                _copy_tree(skill, (base or Path.cwd()) / BUNDLE_DIR / skill.name)
+    else:
+        actions.append("%s block for %s in %s" % ("write", skill.name, dest))
+        if extras:
+            bundle = (base or Path.cwd()) / BUNDLE_DIR / skill.name
+            actions.append("copy bundled files -> %s" % bundle)
+        if not dry_run:
+            action = _upsert_block(dest, skill, render_block(skill, extras))
+            actions[0] = "%s block for %s in %s" % (action, skill.name, dest)
+            if extras:
+                _copy_tree(skill, (base or Path.cwd()) / BUNDLE_DIR / skill.name)
+    return actions
+
+
+def remove_skill(name: str, target: str, base: Optional[Path] = None, global_: bool = False) -> List[str]:
+    t = TARGETS.get(target)
+    if t is None:
+        raise ExportError("unknown target %r" % target)
+    dest = destination(target, base, global_)
+    done: List[str] = []
+    if t.kind == "dir":
+        out = dest / name
+        if out.exists():
+            shutil.rmtree(out)
+            done.append("removed %s" % out)
+    elif t.kind == "file":
+        for ext in (".mdc", ".instructions.md", ".md"):
+            out = dest / (name + ext)
+            if out.exists():
+                out.unlink()
+                done.append("removed %s" % out)
+    else:
+        if dest.exists():
+            text = dest.read_text(encoding="utf-8")
+            pat = re.compile(r"\n?" + re.escape(_begin(name)) + r".*?" + re.escape(_end(name)) + r"\n?", re.S)
+            if pat.search(text):
+                dest.write_text(pat.sub("\n", text).lstrip("\n"), encoding="utf-8")
+                done.append("removed block %s from %s" % (name, dest))
+    bundle = (base or Path.cwd()) / BUNDLE_DIR / name
+    if bundle.exists():
+        shutil.rmtree(bundle)
+        done.append("removed %s" % bundle)
+    return done