@heytherevibin/skillforge 0.8.0 → 0.10.1

package/python/app/health_cli.py

@@ -0,0 +1,160 @@
+"""Preflight / health checks for Skillforge (paths, catalog, optional full router load)."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sqlite3
+import sys
+from pathlib import Path
+
+from app.db_paths import resolve_orchestrator_db
+
+
+def _bundled_skills_dir() -> Path:
+    return Path(os.getenv("SKILLFORGE_BUNDLED_SKILLS", "./skills"))
+
+
+def _user_skills_dir() -> Path:
+    return Path(os.getenv("SKILLFORGE_USER_SKILLS", str(Path.home() / ".skillforge" / "skills")))
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description="Check Skillforge install paths, skill catalog, and optionally load the embedding router."
+    )
+    p.add_argument(
+        "--quick",
+        action="store_true",
+        help="Skip embedding model load (fast; checks paths + skill file counts only).",
+    )
+    p.add_argument(
+        "--project-root",
+        default="",
+        help="If set, also checks <root>/.skillforge/ DB path resolution.",
+    )
+    p.add_argument("--json", action="store_true", help="Machine-readable output on stdout.")
+    return p.parse_args(argv)
+
+
+def _count_skill_md(root: Path) -> int:
+    if not root.is_dir():
+        return 0
+    return sum(1 for _ in root.glob("*/SKILL.md"))
+
+
+def run_health(*, quick: bool, project_root: str, json_out: bool) -> int:
+    checks: list[dict] = []
+    failed = False
+
+    bundled = _bundled_skills_dir()
+    user_skills = _user_skills_dir()
+    bundled_n = _count_skill_md(bundled)
+
+    b_ok = bundled.is_dir() and bundled_n > 0
+    checks.append({
+        "name": "bundled_skills",
+        "ok": b_ok,
+        "path": str(bundled.resolve()) if bundled.exists() else str(bundled),
+        "skill_md_count": bundled_n,
+    })
+    if not b_ok:
+        failed = True
+
+    user_n = _count_skill_md(user_skills)
+    u_ok = True
+    u_err: str | None = None
+    if not user_skills.is_dir():
+        try:
+            user_skills.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            u_ok = False
+            u_err = str(e)
+            failed = True
+    checks.append({
+        "name": "user_skills",
+        "ok": u_ok,
+        "path": str(user_skills),
+        "skill_md_count": user_n,
+        "error": u_err,
+    })
+
+    pr = (project_root or "").strip() or None
+    db_path = resolve_orchestrator_db(pr)
+    db_ok = True
+    db_err: str | None = None
+    try:
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        con = sqlite3.connect(str(db_path))
+        try:
+            con.execute("SELECT 1")
+        finally:
+            con.close()
+    except OSError as e:
+        db_ok = False
+        db_err = str(e)
+        failed = True
+    checks.append({
+        "name": "orchestrator_db",
+        "ok": db_ok,
+        "path": str(db_path),
+        "error": db_err,
+    })
+
+    router_skill_count: int | None = None
+    if not quick:
+        try:
+            from app.main import build_router_and_skills
+
+            _router, skills = build_router_and_skills(log=not json_out, log_prefix="[skillforge-health]")
+            router_skill_count = len(skills)
+            if router_skill_count <= 0:
+                failed = True
+            checks.append({
+                "name": "router_load",
+                "ok": router_skill_count > 0,
+                "skill_count": router_skill_count,
+                "error": None if router_skill_count and router_skill_count > 0 else "empty catalog",
+            })
+        except Exception as e:
+            failed = True
+            checks.append({
+                "name": "router_load",
+                "ok": False,
+                "skill_count": None,
+                "error": str(e),
+            })
+
+    payload = {
+        "ok": not failed,
+        "quick": quick,
+        "checks": checks,
+    }
+    if json_out:
+        print(json.dumps(payload, indent=2))
+    else:
+        for c in checks:
+            sym = "✓" if c.get("ok") else "✗"
+            print(f"{sym} {c['name']}", file=sys.stderr)
+            if c.get("path"):
+                print(f"    path: {c['path']}", file=sys.stderr)
+            if c.get("skill_md_count") is not None:
+                print(f"    SKILL.md count: {c['skill_md_count']}", file=sys.stderr)
+            if c.get("skill_count") is not None:
+                print(f"    router skills: {c['skill_count']}", file=sys.stderr)
+            if c.get("error"):
+                print(f"    error: {c['error']}", file=sys.stderr)
+        print("health: ok" if not failed else "health: failed", file=sys.stderr)
+
+    return 0 if not failed else 1
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parse_args(argv)
+    raise SystemExit(
+        run_health(quick=bool(args.quick), project_root=args.project_root, json_out=bool(args.json))
+    )
+
+
+if __name__ == "__main__":
+    main()

package/python/app/main.py

@@ -32,9 +32,18 @@ from app.project_index import (
     retrieve_project_context_items,
 )
 from app.redaction import redaction_enabled, redact_secret_patterns, sanitize_context_items
-from app.route_policies import load_route_policies_config, merge_policy_includes
+from app.feedback_meta import build_feedback_effect
+from app.route_policies import (
+    build_routing_overlay_payload,
+    load_route_policies_config,
+    merge_policy_includes,
+    merge_project_notes_into_route_query,
+    parse_routing_overlay,
+)
+from app.route_quality import build_route_quality, coerce_route_float
 from app.routing_signals import (
     build_route_query_text,
+    host_pick_shortlist_lines,
     keyword_overlap_scores,
     normalize_minmax,
     skill_routing_card,
@@ -54,7 +63,7 @@ ROUTER_MODEL = os.getenv("SKILLFORGE_ROUTER_MODEL", "claude-haiku-4-5-20251001")
 TOP_K_CANDIDATES = int(os.getenv("SKILLFORGE_TOP_K", "15"))
 MAX_ACTIVE_SKILLS = int(os.getenv("SKILLFORGE_MAX_ACTIVE", "7"))
 REROUTE_THRESHOLD = float(os.getenv("SKILLFORGE_REROUTE_THRESHOLD", "0.4"))
-# "" | "full" | "embedding" — embedding skips Haiku and takes top skills from the shortlist only.
+# "" | "full" | "embedding" | "host" — embedding skips Haiku; host skips in-process pick (MCP must pass picked_names).
 SKILLFORGE_ROUTER_MODE = os.getenv("SKILLFORGE_ROUTER_MODE", "").strip().lower()
 # chunks: RAG-style line-bounded chunks from picked skills. full_body: inject entire SKILL.md per pick (legacy).
 SKILLFORGE_CONTEXT_MODE = os.getenv("SKILLFORGE_CONTEXT_MODE", "chunks").strip().lower()
@@ -105,6 +114,12 @@ def build_router_and_skills(
     if mode == "embedding":
         anthropic = None
         router_note = "embedding-only (SKILLFORGE_ROUTER_MODE=embedding)"
+    elif mode == "host":
+        anthropic = None
+        router_note = (
+            "host-pick (SKILLFORGE_ROUTER_MODE=host): no in-process router LLM; "
+            "first route_skills call returns a shortlist — call again with picked_names"
+        )
     elif mode == "full":
         if key:
             anthropic = AsyncAnthropic()
@@ -446,19 +461,50 @@ class Router:
         fused = self._hybrid_alpha * d_norm + (1.0 - self._hybrid_alpha) * s_norm
         return sims, fused
 
-    def shortlist(self, route_query, con, k=TOP_K_CANDIDATES, user_id=""):
+    def _bias_with_learning_and_overlay(
+        self,
+        con: sqlite3.Connection,
+        biased: np.ndarray,
+        user_id: str,
+        *,
+        exclude_skills: frozenset[str] | None = None,
+        routing_boosts: dict[str, float] | None = None,
+    ) -> None:
+        excl = exclude_skills or frozenset()
+        boosts = routing_boosts or {}
+        for i, s in enumerate(self.skills):
+            w, disabled = get_skill_weight(con, s.name, user_id=user_id)
+            if disabled or s.name in excl:
+                biased[i] = -999.0
+            else:
+                biased[i] += w
+                extra = boosts.get(s.name)
+                if extra is not None:
+                    biased[i] += float(extra)
+
+    def shortlist(
+        self,
+        route_query,
+        con,
+        k=TOP_K_CANDIDATES,
+        user_id="",
+        *,
+        exclude_skills: frozenset[str] | None = None,
+        routing_boosts: dict[str, float] | None = None,
+    ):
         if len(self.skills) == 0:
             return []
         q = self.embed_model.encode(route_query, convert_to_numpy=True)
         q = q / np.linalg.norm(q)
         sims, rank_scores = self._base_routing_scores(route_query, q)
         biased = rank_scores.copy()
-        for i, s in enumerate(self.skills):
-            w, disabled = get_skill_weight(con, s.name, user_id=user_id)
-            if disabled:
-                biased[i] = -999.0
-            else:
-                biased[i] += w
+        self._bias_with_learning_and_overlay(
+            con,
+            biased,
+            user_id,
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+        )
         top_idx = np.argsort(-biased)[:k]
         return [(self.skills[i], float(sims[i])) for i in top_idx if biased[i] > -100]
 
@@ -469,6 +515,8 @@ class Router:
         *,
         k: int | None = None,
         user_id: str = "",
+        exclude_skills: frozenset[str] | None = None,
+        routing_boosts: dict[str, float] | None = None,
     ) -> list[dict[str, Any]]:
         """Embedding shortlist with cosine sim, learned weight, and routing score (no LLM)."""
         limit = k if k is not None else TOP_K_CANDIDATES
@@ -483,12 +531,13 @@ class Router:
             )
         )
         biased = rank_scores.copy()
-        for i, s in enumerate(self.skills):
-            w, disabled = get_skill_weight(con, s.name, user_id=user_id)
-            if disabled:
-                biased[i] = -999.0
-            else:
-                biased[i] += w
+        self._bias_with_learning_and_overlay(
+            con,
+            biased,
+            user_id,
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+        )
         top_idx = np.argsort(-biased)[:limit]
         out: list[dict[str, Any]] = []
         for i in top_idx:
@@ -845,6 +894,26 @@ def format_context_items_markdown(context_items: list[dict[str, Any]]) -> str:
     return "\n".join(blocks)
 
 
+def normalize_host_picked_names(
+    raw: list[str] | None,
+    by_name: dict[str, Skill],
+    cap: int,
+) -> list[str]:
+    """Dedupe, order-stable, cap length; only catalog names."""
+    out: list[str] = []
+    seen: set[str] = set()
+    for item in raw or []:
+        if not isinstance(item, str):
+            continue
+        n = item.strip()
+        if n in by_name and n not in seen:
+            out.append(n)
+            seen.add(n)
+        if len(out) >= cap:
+            break
+    return out
+
+
 async def run_route_turn(
     con: sqlite3.Connection,
     router: Router,
@@ -855,21 +924,156 @@ async def run_route_turn(
     *,
     project_root: str | None = None,
     include_project_rag: bool = False,
+    picked_names_from_host: list[str] | None = None,
+    picked_names_from_host_supplied: bool = False,
 ) -> dict[str, Any]:
     """Shared routing + session + telemetry for MCP route_skills and ``skillforge route``.
 
-    Updates sessions, skill usage stats, and writes a route row to events.
+    ``SKILLFORGE_ROUTER_MODE=host`` without ``picked_names`` returns a tight shortlist only (no ``uses``,
+    no skill chunks). Pass ``picked_names`` on the next call to finalize context.
+
+    When ``picked_names_from_host_supplied`` is True, skips rerank/Haiku and uses the supplied names
+    (after validation) in any router mode.
     """
     sid = session_id or str(uuid.uuid4())
     t0 = time.time()
     route_query = build_route_query_text(prompt, conversation)
-    candidates = router.shortlist(route_query, con, user_id=user_id)
-    candidates = await router.rerank_candidates_haiku(route_query, conversation, candidates)
-    picked_names, reasoning = await router.pick_final(
-        prompt, conversation, candidates, route_query=route_query
-    )
     pr = (project_root or "").strip()
     policies_cfg = load_route_policies_config(pr or None)
+    overlay_audit: list[dict[str, Any]] = []
+    exclude_skills, routing_boosts, project_notes_raw = parse_routing_overlay(
+        policies_cfg,
+        by_name=router._by_name,
+        audit_out=overlay_audit,
+    )
+    route_query = merge_project_notes_into_route_query(route_query, project_notes_raw, pr)
+    notes_effective = bool(project_notes_raw.strip() and pr)
+    routing_overlay_meta = build_routing_overlay_payload(
+        project_root=pr,
+        exclude_skills=exclude_skills,
+        routing_boosts=routing_boosts,
+        project_notes_applied=notes_effective,
+        project_notes_len=len(project_notes_raw) if project_notes_raw else 0,
+        audit=overlay_audit,
+    )
+    rules_list_early = policies_cfg.get("rules") if isinstance(policies_cfg.get("rules"), list) else []
+    rules_n = len(rules_list_early)
+
+    host_router = SKILLFORGE_ROUTER_MODE == "host"
+
+    if host_router and not picked_names_from_host_supplied:
+        k = max(3, min(TOP_K_CANDIDATES, int(os.getenv("SKILLFORGE_HOST_PICK_MAX", "12"))))
+        facets = router.shortlist_with_facets(
+            route_query,
+            con,
+            k=k,
+            user_id=user_id,
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+        )
+        candidates = [
+            (router._by_name[nm], coerce_route_float(f.get("cosine_similarity")))
+            for f in facets
+            if (nm := f.get("name")) in router._by_name
+        ]
+        md, rows = host_pick_shortlist_lines(
+            prompt=prompt,
+            route_query=route_query,
+            facet_rows=facets,
+            max_candidates=k,
+        )
+        route_ms = (time.time() - t0) * 1000
+        safe_prompt_snip = prompt[:300]
+        if redaction_enabled():
+            safe_prompt_snip, _ = redact_secret_patterns(prompt[:300])
+        route_quality = build_route_quality(
+            facet_list=facets,
+            router_mode=SKILLFORGE_ROUTER_MODE or "auto",
+            router_hybrid=router._hybrid_mode,
+            picked_names=[],
+            rerouted=False,
+            change=0.0,
+            policy_rules_loaded=rules_n,
+            policy_audit=[],
+            host_picked=False,
+            host_shortlist_only=True,
+            haiku_rerank_applied=False,
+            pick_path="host_shortlist",
+        )
+        feedback_effect = build_feedback_effect(con, [], user_id=user_id)
+        event = {
+            "type": "host_shortlist",
+            "session_id": sid,
+            "user_id": user_id,
+            "prompt": safe_prompt_snip,
+            "candidates": [{"name": s.name, "score": sc} for s, sc in candidates[:15]],
+            "picked": [],
+            "reasoning": "host_pick_shortlist",
+            "route_ms": round(route_ms, 1),
+            "ts": time.time(),
+            "host_pick_candidates": rows,
+            "policy": {"rules_loaded": rules_n, "audit": []},
+            "route_quality": route_quality,
+            "feedback_effect": feedback_effect,
+        }
+        if routing_overlay_meta is not None:
+            event["routing_overlay"] = routing_overlay_meta
+        log_event(con, sid, "host_shortlist", event, user_id=user_id)
+        con.commit()
+        ret_host: dict[str, Any] = {
+            "session_id": sid,
+            "picked_names": [],
+            "reasoning": (
+                "host_pick_shortlist — choose names from the list; call route_skills again "
+                "with picked_names (reuse session_id if you use sessions)."
+            ),
+            "candidates": candidates,
+            "route_ms": route_ms,
+            "rerouted": False,
+            "change": 0.0,
+            "event": event,
+            "context_items": [],
+            "host_pick_shortlist": True,
+            "host_pick_markdown": md,
+            "host_pick_candidates": rows,
+            "route_query": route_query,
+            "route_quality": route_quality,
+            "feedback_effect": feedback_effect,
+        }
+        if routing_overlay_meta is not None:
+            ret_host["routing_overlay"] = routing_overlay_meta
+        return ret_host
+
+    facet_list = router.shortlist_with_facets(
+        route_query,
+        con,
+        k=TOP_K_CANDIDATES,
+        user_id=user_id,
+        exclude_skills=exclude_skills,
+        routing_boosts=routing_boosts,
+    )
+    candidates = [
+        (router._by_name[nm], coerce_route_float(f.get("cosine_similarity")))
+        for f in facet_list
+        if (nm := f.get("name")) in router._by_name
+    ]
+    haiku_rerank_applied = False
+    if picked_names_from_host_supplied:
+        picked_names = normalize_host_picked_names(
+            picked_names_from_host, router._by_name, MAX_ACTIVE_SKILLS
+        )
+        reasoning = "host-picked: MCP picked_names"
+    else:
+        names_before = [s.name for s, _ in candidates]
+        rerank_eligible = bool(
+            candidates and router.anthropic is not None and _env_truthy("SKILLFORGE_HAIKU_RERANK", "0")
+        )
+        candidates = await router.rerank_candidates_haiku(route_query, conversation, candidates)
+        names_after = [s.name for s, _ in candidates]
+        haiku_rerank_applied = rerank_eligible and names_before != names_after
+        picked_names, reasoning = await router.pick_final(
+            prompt, conversation, candidates, route_query=route_query
+        )
     picked_names, policy_audit = merge_policy_includes(
         prompt,
         picked_names,
@@ -984,6 +1188,29 @@ async def run_route_turn(
 
     project_rag_items_count = sum(1 for c in context_items if c.get("path"))
 
+    if picked_names_from_host_supplied:
+        pick_path = "host_picked"
+    elif router.anthropic is None or SKILLFORGE_ROUTER_MODE == "embedding":
+        pick_path = "embedding_top"
+    else:
+        pick_path = "haiku_pick"
+
+    rules_list = policies_cfg.get("rules") if isinstance(policies_cfg.get("rules"), list) else []
+    route_quality = build_route_quality(
+        facet_list=facet_list,
+        router_mode=SKILLFORGE_ROUTER_MODE or "auto",
+        router_hybrid=router._hybrid_mode,
+        picked_names=picked_names,
+        rerouted=rerouted,
+        change=change,
+        policy_rules_loaded=len(rules_list),
+        policy_audit=policy_audit,
+        host_picked=picked_names_from_host_supplied,
+        host_shortlist_only=False,
+        haiku_rerank_applied=haiku_rerank_applied,
+        pick_path=pick_path,
+    )
+
     reasoning_out = reasoning
     safe_prompt_snip = prompt[:300]
     context_redaction_stats: dict[str, Any] = {"enabled": False, "secret_hits": 0, "path_hits": 0}
@@ -1003,6 +1230,8 @@ async def run_route_turn(
     for n in picked_names:
         update_skill_stat(con, n, "uses", 1, user_id=user_id)
 
+    feedback_effect = build_feedback_effect(con, picked_names, user_id=user_id)
+
     event = {
         "type": "route",
         "session_id": sid,
@@ -1035,9 +1264,14 @@ async def run_route_turn(
             }
             for c in context_items[:24]
         ],
+        "host_picked": bool(picked_names_from_host_supplied),
+        "route_quality": route_quality,
+        "feedback_effect": feedback_effect,
     }
+    if routing_overlay_meta is not None:
+        event["routing_overlay"] = routing_overlay_meta
     log_event(con, sid, "route", event, user_id=user_id)
-    return {
+    ret_main: dict[str, Any] = {
         "session_id": sid,
         "picked_names": picked_names,
         "reasoning": reasoning_out,
@@ -1047,4 +1281,9 @@ async def run_route_turn(
         "change": change,
         "event": event,
         "context_items": context_items,
+        "route_quality": route_quality,
+        "feedback_effect": feedback_effect,
     }
+    if routing_overlay_meta is not None:
+        ret_main["routing_overlay"] = routing_overlay_meta
+    return ret_main

package/python/app/materialize.py

@@ -1,4 +1,4 @@
-"""Write project-local Skillforge bootstrap files (.cursor/rules, docs PRD, CLAUDE.md block)."""
+"""Write project-local Skillforge bootstrap files (.cursor, .claude/commands, PRD, CLAUDE.md)."""
 from __future__ import annotations
 
 import re
@@ -30,7 +30,12 @@ def materialize_project_files(
     *,
     merge: bool = True,
 ) -> dict[str, Any]:
-    """Create or update Cursor rule, PRD stub, and CLAUDE.md section. merge=False overwrites rule file only."""
+    """Create or update Cursor rule + command, Claude Code command, PRD stub, and CLAUDE.md section.
+
+    merge=False skips overwriting existing `.cursor/rules/skillforge.mdc`,
+    `.cursor/commands/skillforge.md`, and `.claude/commands/skillforge.md` if they already exist
+    (other files still update).
+    """
     root = _safe_root(project_root)
     written: list[str] = []
 
@@ -51,9 +56,11 @@ alwaysApply: false
 
 # Skillforge
 
-When the user invokes **Skillforge**, **`/skillforge`**, or needs deep SKILL.md guidance for this codebase:
+When the user invokes **Skillforge**, types **`/skillforge`** (Cursor or **Claude Code** project command), or needs deep SKILL.md guidance for this codebase:
 
 1. Call **route_skills** with **`project_root`** set to this workspace root (so learning and SQLite live in **`.skillforge/`** here), the user's task, and optional **session_id** (reuse within a thread for reroute stats). If the host sets **`SKILLFORGE_PROJECT_ROOT`**, you can omit **project_root** on each call.
+
+   If **`SKILLFORGE_ROUTER_MODE=host`**: first **`route_skills`** without **`picked_names`** (shortlist only); then call again with **`picked_names`** for the chosen catalog ids before continuing.
 2. Inject the returned skill bodies into context before continuing.
 3. To refresh project files, call **materialize_project** with **project_root** set to this workspace root and **skill_names** from the last **route_skills** result.
 
@@ -67,6 +74,65 @@ When the user invokes **Skillforge**, **`/skillforge`**, or needs deep SKILL.md
         cursor_rule.write_text(mdc_body, encoding="utf-8")
         written.append(str(cursor_rule.relative_to(root)))
 
+    cursor_cmd = root / ".cursor" / "commands" / "skillforge.md"
+    _assert_under(root, cursor_cmd)
+    cursor_cmd.parent.mkdir(parents=True, exist_ok=True)
+    cmd_body = f"""# Skillforge — route SKILL.md context (MCP)
+
+The user chose the **`/skillforge`** project command. Use the **skillforge** MCP server.
+
+## Do this
+
+1. **`route_skills`**: pass **`project_root`** as this workspace root (absolute path) so SQLite lives in **`.skillforge/`** here. Pass the **current user task** as **`prompt`**. Reuse **`session_id`** across turns in the same thread when the MCP returns one.
+
+   - **`SKILLFORGE_ROUTER_MODE=host`**: call once **without** **`picked_names`** (shortlist in the response); then call again with **`picked_names`** (exact catalog ids) to load skill context.
+   - Optional: pass **`conversation`** when recent turns should influence routing.
+
+2. **Use the returned skill text** in your answer (summarize or follow the SKILL.md guidance as appropriate).
+
+3. Optionally **`materialize_project`** with the same **`project_root`** and **`skill_names`** from **`route_skills`** to refresh **`.cursor/rules`**, **`.cursor/commands`**, **`.claude/commands`**, and **docs/SKILLFORGE-PRD.md**.
+
+## Skills last materialized for this project
+
+{skills_md}
+"""
+    if cursor_cmd.exists() and not merge:
+        pass
+    else:
+        cursor_cmd.write_text(cmd_body, encoding="utf-8")
+        written.append(str(cursor_cmd.relative_to(root)))
+
+    claude_cmd = root / ".claude" / "commands" / "skillforge.md"
+    _assert_under(root, claude_cmd)
+    claude_cmd.parent.mkdir(parents=True, exist_ok=True)
+    cc_body = f"""---
+description: Use Skillforge MCP route_skills for this repo. Invoke when the user runs /skillforge or needs routed SKILL.md context.
+---
+
+# Skillforge — route SKILL.md context (MCP)
+
+Project-local **`/skillforge`** for **Claude Code**. Use the **skillforge** MCP server.
+
+## Do this
+
+1. **`route_skills`**: pass **`project_root`** as this workspace root (absolute path). Pass the **current user task** as **`prompt`**. Reuse **`session_id`** when returned.
+
+   - **`SKILLFORGE_ROUTER_MODE=host`**: shortlist first, then **`picked_names`**.
+
+2. **Use the returned skill text** in your answer.
+
+3. Optionally **`materialize_project`** to refresh this file and **`.cursor`** files.
+
+## Skills last materialized for this project
+
+{skills_md}
+"""
+    if claude_cmd.exists() and not merge:
+        pass
+    else:
+        claude_cmd.write_text(cc_body, encoding="utf-8")
+        written.append(str(claude_cmd.relative_to(root)))
+
     docs_dir = root / "docs"
     docs_dir.mkdir(parents=True, exist_ok=True)
     prd = docs_dir / "SKILLFORGE-PRD.md"
@@ -82,6 +148,8 @@ Scaffold for goals and milestones. Re-run **materialize_project** after major ro
 ## How to run Skillforge here
 
 - **MCP**: configure the `skillforge` server (e.g. `npx -y @heytherevibin/skillforge mcp`). No API key required for embedding-only routing.
+- **Cursor**: use **`/skillforge`** (**`.cursor/commands/skillforge.md`**) to steer the agent through **route_skills** for this workspace.
+- **Claude Code**: use **`/skillforge`** (**`.claude/commands/skillforge.md`**) the same way.
 - **session_id**: reuse the same value across **route_skills** calls in one conversation thread.
 - Re-bootstrap this project after new skills: **materialize_project** again.
 
@@ -110,7 +178,7 @@ Use [Skillforge](https://www.npmjs.com/package/@heytherevibin/skillforge) for **
 
 - Call **route_skills** for the current task; reuse **session_id** within a thread.
 - See **docs/SKILLFORGE-PRD.md** for the skill list and runbook.
-- Map **`/skillforge`** in agent rules to the MCP tools above.
+- In Cursor, **`/skillforge`** is **`.cursor/commands/skillforge.md`**; in **Claude Code**, **`.claude/commands/skillforge.md`** (after **materialize_project**).
 
 **Routed skills (last materialize):** {skill_list}
 

package/python/app/mcp_contract.py

@@ -4,6 +4,9 @@ Versioned ``_meta`` with ``sources[]`` and ``budget``. Schema **1.1** adds
 per-chunk ``sources`` when ``context_items`` (RAG chunks) are returned from Phase 1.
 Schema **1.2** adds ``kind: file`` sources and project chunk char counts in ``budget``.
 Schema **1.4** adds optional ``context_redaction`` (hit counts when scrubbing is on).
+Schema **1.5** adds optional ``route_quality`` (shortlist margins, hybrid diagnostics, policy/session).
+Schema **1.6** adds optional ``feedback_effect`` (per-pick learned weights / thumbs / uses used in ranking).
+Schema **1.7** adds optional ``routing_overlay`` (project exclude/boost/notes audit for embedding shortlist).
 """
 from __future__ import annotations
 
@@ -18,7 +21,7 @@ class _SkillBody(Protocol):
     body: str
 
 
-MCP_RESPONSE_SCHEMA_VERSION = "1.4"
+MCP_RESPONSE_SCHEMA_VERSION = "1.7"
 
 
 def build_route_skills_meta(
@@ -112,6 +115,15 @@ def build_route_skills_meta(
         "candidates_preview": candidates_preview,
         "context_items_count": len(context_items or []),
     }
+    rq_meta = result.get("route_quality")
+    if isinstance(rq_meta, dict):
+        meta["route_quality"] = rq_meta
+    fb_meta = result.get("feedback_effect")
+    if isinstance(fb_meta, dict):
+        meta["feedback_effect"] = fb_meta
+    ro_meta = result.get("routing_overlay")
+    if isinstance(ro_meta, dict):
+        meta["routing_overlay"] = ro_meta
     if fusion is not None and fusion.get("enabled"):
         meta["fusion"] = fusion
     if context_redaction is not None: