@event4u/agent-config 5.4.1 → 5.5.0

package/scripts/skill_discovery.py

@@ -0,0 +1,254 @@
+"""Skill discovery recommender — local-only, explained, no network.
+
+Phase 3 of `road-to-leaner-core-and-discovery`. Turns existing local signals
+(skill catalog frontmatter, role shortlists, optional local-analytics JSONL)
+into a short, *explained* skill shortlist. Every recommendation carries a
+non-empty `why` (contract: docs/contracts/skill-discovery.md). Adds no
+always-loaded layer; reads local files only.
+
+Four classes:
+  most-useful-for-role   — role skills.yml priority order
+  related-to-current-task— skills sharing the role's core domains
+  recently-adopted       — analytics events (last 14d) with a skill id
+  popular-in-role        — analytics skill-events filtered by role, by frequency
+
+Analytics is optional; missing / empty / opted-out degrades gracefully to
+the role shortlist with an honest `why`. Honours the same opt-out as
+local-analytics.md (AGENT_CONFIG_NO_LOCAL_ANALYTICS env + analytics.local config).
+
+Usage:
+    python3 scripts/skill_discovery.py [--role ROLE] [--format text|json] [--limit N]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_DIR = REPO_ROOT / ".agent-src" / "skills"
+ROLES_DIR = REPO_ROOT / "agents" / "roles"
+COMMANDS_DIR = REPO_ROOT / ".agent-src" / "commands"
+RECENT_DAYS = 14
+
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+try:
+    from _lib.user_global_paths import event4u_root  # type: ignore
+except Exception:  # pragma: no cover - fallback when run outside repo
+    def event4u_root(env=None):  # type: ignore
+        return Path.home() / ".event4u" / "agent-config"
+
+CLASSES = ("most-useful-for-role", "related-to-current-task", "recently-adopted", "popular-in-role")
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    domain: str
+
+
+@dataclass
+class Rec:
+    skill: str
+    cls: str
+    why: str
+    first_command: str = ""
+
+
+def _frontmatter(text: str) -> dict:
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    try:
+        return yaml.safe_load(text[3:end]) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def load_catalog() -> dict[str, Skill]:
+    out: dict[str, Skill] = {}
+    if not SKILLS_DIR.exists():
+        return out
+    for d in sorted(SKILLS_DIR.iterdir()):
+        sk = d / "SKILL.md"
+        if not sk.is_file():
+            continue
+        fm = _frontmatter(sk.read_text(encoding="utf-8", errors="replace"))
+        name = str(fm.get("name") or d.name).strip().strip('"')
+        out[name] = Skill(name, str(fm.get("description", "")).strip(), str(fm.get("domain", "")).strip())
+    return out
+
+
+def load_role_shortlist(role: str) -> list[dict]:
+    f = ROLES_DIR / role / "skills.yml"
+    if not f.is_file():
+        return []
+    data = yaml.safe_load(f.read_text(encoding="utf-8", errors="replace")) or {}
+    return [s for s in (data.get("skills") or []) if isinstance(s, dict) and s.get("id")]
+
+
+def available_roles() -> list[str]:
+    if not ROLES_DIR.exists():
+        return []
+    return sorted(d.name for d in ROLES_DIR.iterdir() if (d / "skills.yml").is_file())
+
+
+def analytics_enabled(settings: dict) -> bool:
+    if os.environ.get("AGENT_CONFIG_NO_LOCAL_ANALYTICS", "").strip():
+        return False
+    val = ((settings.get("analytics") or {}).get("local"))
+    return str(val).strip().lower() not in ("off", "false", "0", "no")
+
+
+def load_settings() -> dict:
+    try:
+        from _lib.agent_settings import load_agent_settings  # type: ignore
+        return load_agent_settings(cwd=Path.cwd()) or {}
+    except Exception:
+        return {}
+
+
+def load_analytics_events() -> list[dict]:
+    path = event4u_root() / "workspace" / "analytics" / "events.jsonl"
+    if not path.is_file():
+        return []
+    events: list[dict] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return events
+
+
+def _days_ago(ts: str, now: datetime) -> int | None:
+    try:
+        dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return (now - dt).days
+    except (ValueError, AttributeError):
+        return None
+
+
+def first_command(name: str) -> str:
+    for cand in (COMMANDS_DIR / f"{name}.md", *COMMANDS_DIR.glob(f"*/{name}.md")):
+        if cand.is_file():
+            return f"/{name}"
+    return f"Skill › {name}"
+
+
+def recommend(role: str, catalog: dict[str, Skill], shortlist: list[dict],
+              events: list[dict], use_analytics: bool, now: datetime, limit: int) -> list[Rec]:
+    recs: list[Rec] = []
+    claimed: set[str] = set()
+
+    def add(name: str, cls: str, why: str) -> None:
+        if name in claimed or name not in catalog or not why:
+            return
+        claimed.add(name)
+        recs.append(Rec(name, cls, why, first_command(name)))
+
+    # 1. most-useful-for-role — role shortlist priority order.
+    short_ids = [s["id"] for s in shortlist]
+    for s in shortlist[:limit]:
+        why = (s.get("why") or "").strip() or f"on the {role} role's priority shortlist"
+        add(s["id"], "most-useful-for-role", why)
+
+    # 2. related-to-current-task — same domain as the role's core skills, not yet shortlisted.
+    role_domains = {catalog[i].domain for i in short_ids if i in catalog and catalog[i].domain}
+    related = [sk for n, sk in sorted(catalog.items())
+               if sk.domain in role_domains and n not in short_ids and sk.domain]
+    for sk in related[:limit]:
+        add(sk.name, "related-to-current-task", f"same domain ({sk.domain}) as your {role} core skills")
+
+    # 3 + 4. analytics-backed, or graceful role-shortlist fallback.
+    skill_events = [e for e in events if isinstance(e.get("data"), dict) and e["data"].get("skill")]
+    if use_analytics and skill_events:
+        recent = sorted(
+            ((e["data"]["skill"], _days_ago(e.get("ts", ""), now)) for e in skill_events),
+            key=lambda kv: (kv[1] is None, kv[1] if kv[1] is not None else 1e9),
+        )
+        for name, days in recent:
+            if days is not None and days <= RECENT_DAYS:
+                add(name, "recently-adopted", f"used {days}d ago in this workspace")
+        role_counts = Counter(
+            e["data"]["skill"] for e in skill_events if e["data"].get("role") == role
+        )
+        for name, n in role_counts.most_common(limit):
+            add(name, "popular-in-role", f"launched {n}× by the {role} role locally")
+    else:
+        reason = "from your role shortlist — no local usage signal yet"
+        for s in shortlist[limit: limit * 2]:
+            add(s["id"], "recently-adopted", reason)
+        for s in shortlist:
+            add(s["id"], "popular-in-role", reason)
+    return recs
+
+
+def render_text(role: str, recs: list[Rec], analytics_on: bool) -> str:
+    lines = [f"# Suggested skills for the `{role}` role", ""]
+    note = "local analytics: on" if analytics_on else "local analytics: off (role shortlist only)"
+    lines.append(f"_{note}_\n")
+    lines += ["| skill | class | why | first command |", "|---|---|---|---|"]
+    for r in recs:
+        lines.append(f"| `{r.skill}` | {r.cls} | {r.why} | `{r.first_command}` |")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Local skill-discovery recommender (read-only, explained).")
+    ap.add_argument("--role", default=None, help="Role id (defaults to active role experience, else prompts).")
+    ap.add_argument("--format", choices=("text", "json"), default="text")
+    ap.add_argument("--limit", type=int, default=5)
+    ap.add_argument("--now", default=None, help="ISO timestamp override for tests.")
+    args = ap.parse_args(argv)
+
+    settings = load_settings()
+    role = args.role or ((settings.get("roles") or {}).get("active_role") or "").strip()
+    roles = available_roles()
+    if not role:
+        print(f"No role given and no active role set. Available roles: {', '.join(roles) or '(none)'}", file=sys.stderr)
+        print("Re-run with --role <role>.", file=sys.stderr)
+        return 2
+    if role not in roles:
+        print(f"Unknown role {role!r}. Available: {', '.join(roles) or '(none)'}", file=sys.stderr)
+        return 2
+
+    catalog = load_catalog()
+    shortlist = load_role_shortlist(role)
+    use_analytics = analytics_enabled(settings)
+    events = load_analytics_events() if use_analytics else []
+    now = datetime.fromisoformat(args.now.replace("Z", "+00:00")) if args.now else datetime.now(timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+
+    recs = recommend(role, catalog, shortlist, events, use_analytics, now, args.limit)
+
+    if args.format == "json":
+        print(json.dumps({
+            "role": role,
+            "analytics": use_analytics,
+            "recommendations": [r.__dict__ for r in recs],
+        }, indent=2))
+    else:
+        print(render_text(role, recs, use_analytics))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/skill_linter.py

@@ -533,12 +533,16 @@ def detect_artifact_type(path: Path, text: str) -> ArtifactType:
     path_str = str(path).lower()
     has_skill_heading = "## When to use" in text and "## Procedure" in text
 
-    # Skills take priority — /skills/commands/SKILL.md is a skill, not a command
+    # A file inside a /commands/ tree is a command — the commands tree wins,
+    # even for a cluster head literally named `skill.md` or a sub-command under
+    # a `skills/` cluster dir (e.g. /commands/skills/discover.md). The only
+    # /commands/ file that is NOT a command is a nested skill body, which is
+    # always `SKILL.md` (case-sensitive — command files are lowercase).
+    if "/commands/" in path_str and path.name != "SKILL.md":
+        return "command"
+    # Skills: a SKILL.md body, or anything under a /skills/ tree.
     if path.name.lower() == "skill.md" or "/skills/" in path_str:
         return "skill"
-    # Commands are flat .md files in /commands/ directories (not SKILL.md)
-    if "/commands/" in path_str and path.name.lower() != "skill.md":
-        return "command"
     if "/rules/" in path_str:
         return "rule"
     if "/guidelines/" in path_str:

package/scripts/skill_preview.py

@@ -0,0 +1,179 @@
+"""Skill preview — non-destructive "what will this skill do?" summary.
+
+Phase 5 of `road-to-leaner-core-and-discovery`. Reads a skill's declared intent
+(frontmatter + `## Steps` body) and renders a plain-language summary BEFORE the
+skill runs. Read-only, no network, no execution.
+
+NOT a sandbox: it surfaces declared intent, it does not run the skill or prove
+side-effect-freeness (contract: docs/contracts/skill-dry-run.md). For
+`execution: manual` skills (the default) it states "instructional only".
+
+Usage:
+    python3 scripts/skill_preview.py <name> [--technical] [--format text|json]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_DIR = REPO_ROOT / ".agent-src" / "skills"
+
+_CMD_RE = re.compile(r"`(python3?|bash|node|php|npm|task|pytest)\s+[^`]+`")
+_PATH_RE = re.compile(r"`([\w./-]+\.(?:py|sh|md|json|yml|yaml|ts|js|php))`")
+
+
+class PreviewError(Exception):
+    """Raised for a missing or malformed SKILL.md — rendered, never crashed on."""
+
+
+def _split_frontmatter(text: str) -> tuple[dict, str]:
+    if not text.startswith("---"):
+        raise PreviewError("SKILL.md has no YAML frontmatter (missing leading `---`).")
+    end = text.find("\n---", 3)
+    if end == -1:
+        raise PreviewError("SKILL.md frontmatter is not closed (missing terminating `---`).")
+    try:
+        fm = yaml.safe_load(text[3:end]) or {}
+    except yaml.YAMLError as exc:
+        raise PreviewError(f"SKILL.md frontmatter is not valid YAML: {exc}")
+    if not isinstance(fm, dict):
+        raise PreviewError("SKILL.md frontmatter did not parse to a mapping.")
+    return fm, text[end + 4:]
+
+
+def _steps(body: str) -> list[str]:
+    out: list[str] = []
+    in_steps = False
+    for line in body.splitlines():
+        if re.match(r"^##\s+Steps\b", line, re.IGNORECASE):
+            in_steps = True
+            continue
+        if in_steps and re.match(r"^##\s+\S", line):  # next top-level section
+            break
+        if in_steps:
+            m = re.match(r"^###\s+(.*)", line)
+            if m:
+                out.append(m.group(1).strip())
+    return out
+
+
+def _targets(body: str) -> tuple[list[str], list[str]]:
+    cmds = sorted({m.group(0).strip("`") for m in _CMD_RE.finditer(body)})
+    paths = sorted({m.group(1) for m in _PATH_RE.finditer(body)})
+    return cmds, paths
+
+
+def load_preview(name: str) -> dict:
+    skill_dir = SKILLS_DIR / name
+    sk = skill_dir / "SKILL.md"
+    if not sk.is_file():
+        try:
+            shown = sk.relative_to(REPO_ROOT)
+        except ValueError:
+            shown = sk
+        raise PreviewError(f"no skill named {name!r} (looked for {shown}).")
+    fm, body = _split_frontmatter(sk.read_text(encoding="utf-8", errors="replace"))
+    execution = fm.get("execution") or {}
+    if not isinstance(execution, dict):
+        execution = {}
+    cmds, paths = _targets(body)
+    return {
+        "name": fm.get("name") or name,
+        "description": (fm.get("description") or "").strip(),
+        "domain": fm.get("domain") or "",
+        "execution_type": (execution.get("type") or "manual"),
+        "handler": (execution.get("handler") or "none"),
+        "allowed_tools": execution.get("allowed_tools") or [],
+        "command": execution.get("command") or [],
+        "steps": _steps(body),
+        "commands_named": cmds,
+        "paths_named": paths,
+    }
+
+
+def render_plain(p: dict) -> str:
+    lines = [f"# Preview — `{p['name']}`", ""]
+    if p["description"]:
+        lines += [p["description"], ""]
+    etype = p["execution_type"]
+    if etype == "manual":
+        lines.append("**Execution: instructional only.** This skill does not run anything "
+                     "automatically — it guides the agent step by step.")
+    elif etype == "assisted":
+        lines.append(f"**Execution: assisted** (handler `{p['handler']}`). It will *propose* actions "
+                     "for you to approve — it never executes silently.")
+    else:
+        lines.append(f"**Execution: {etype}** (handler `{p['handler']}`). It can run actions; review the "
+                     "declared tools and commands below before allowing it.")
+    lines.append("")
+    if p["steps"]:
+        lines.append("This skill will walk these steps:")
+        lines += [f"- {s}" for s in p["steps"]]
+        lines.append("")
+    if p["allowed_tools"]:
+        lines.append(f"Declared tools: {', '.join(p['allowed_tools'])}")
+    if p["command"]:
+        lines.append(f"Declared command: `{' '.join(str(c) for c in p['command'])}`")
+    if p["commands_named"]:
+        lines.append("Commands it may run:")
+        lines += [f"- `{c}`" for c in p["commands_named"]]
+    if p["paths_named"]:
+        lines.append("Files / scripts it references:")
+        lines += [f"- `{f}`" for f in p["paths_named"]]
+    if not (p["allowed_tools"] or p["command"] or p["commands_named"] or p["paths_named"]):
+        lines.append("_No tools, commands, or file targets declared — pure guidance._")
+    lines.append("")
+    lines.append("> Preview shows declared intent only — it does not run the skill or guarantee "
+                 "side-effect-freeness. Contract: docs/contracts/skill-dry-run.md")
+    return "\n".join(lines)
+
+
+def render_technical(p: dict) -> str:
+    lines = [f"# Preview (technical) — {p['name']}", "", "## Frontmatter (execution)", "```yaml"]
+    lines.append(f"execution_type: {p['execution_type']}")
+    lines.append(f"handler: {p['handler']}")
+    lines.append(f"allowed_tools: {p['allowed_tools']}")
+    if p["command"]:
+        lines.append(f"command: {p['command']}")
+    lines += ["```", "", "## Declared steps"]
+    lines += [f"{i+1}. {s}" for i, s in enumerate(p["steps"])] or ["(none)"]
+    if p["commands_named"]:
+        lines += ["", "## Commands named in body"] + [f"- `{c}`" for c in p["commands_named"]]
+    if p["paths_named"]:
+        lines += ["", "## Paths named in body"] + [f"- `{f}`" for f in p["paths_named"]]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Preview a skill's declared intent (read-only, no execution).")
+    ap.add_argument("name", help="Skill name (directory under .agent-src/skills/).")
+    ap.add_argument("--technical", action="store_true", help="Show raw frontmatter + step list.")
+    ap.add_argument("--format", choices=("text", "json"), default="text")
+    args = ap.parse_args(argv)
+
+    try:
+        preview = load_preview(args.name)
+    except PreviewError as exc:
+        if args.format == "json":
+            print(json.dumps({"error": str(exc), "name": args.name}, indent=2))
+        else:
+            print(f"❌  Cannot preview {args.name!r}: {exc}", file=sys.stderr)
+        return 2
+
+    if args.format == "json":
+        print(json.dumps(preview, indent=2))
+    elif args.technical:
+        print(render_technical(preview))
+    else:
+        print(render_plain(preview))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())