@heytherevibin/skillforge 0.7.0 → 0.10.0

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:

package/python/app/mcp_server.py

@@ -2,11 +2,11 @@
 MCP server for skillforge.
 
 Exposes skill routing as MCP tools so MCP-aware clients (Claude Desktop,
-Claude Code, Cursor, etc.) can use the orchestrator without running the
-HTTP server.
+Claude Code, Cursor, etc.) can use the orchestrator locally.
 
 Tools exposed:
   route_skills / skillforge_bootstrap — routing (+ optional project materialize).
+  search_skills / explain_route / get_skill — retrieval, debugging, deterministic fetch.
   materialize_project — .cursor/rules, docs/SKILLFORGE-PRD.md, CLAUDE.md block.
   list_skills, skill_feedback, skill_referenced, disable_skill.
 
@@ -25,6 +25,9 @@ from pathlib import Path
 
 from app.db_paths import resolve_orchestrator_db
 from app.main import (
+    TOP_K_CANDIDATES,
+    MAX_ACTIVE_SKILLS,
+    SKILLFORGE_ROUTER_MODE,
     build_router_and_skills,
     format_context_items_markdown,
     init_db,
@@ -39,6 +42,14 @@ from app.main import (
 from app.materialize import materialize_project_files
 from app.mcp_contract import MCP_RESPONSE_SCHEMA_VERSION, build_route_skills_meta
 from app.redaction import redaction_enabled, redact_display_path
+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.routing_signals import build_route_query_text
 
 
 def _env_truthy(name: str, default: str = "1") -> bool:
@@ -85,7 +96,7 @@ class MCPServer:
         self._db_cache: dict[str, sqlite3.Connection] = {}
 
     def _mcp_user_id(self, args: dict) -> str:
-        """Per-tool user namespace for weights/sessions/events (aligned with HTTP bearer user id)."""
+        """Per-tool user namespace for weights/sessions/events."""
         raw = (
             args.get("user_id")
             or os.getenv("SKILLFORGE_MCP_USER_ID", "")
@@ -185,7 +196,7 @@ class MCPServer:
         return {
             "protocolVersion": "2024-11-05",
             "capabilities": caps,
-            "serverInfo": {"name": "skillforge", "version": "0.7.0"},
+            "serverInfo": {"name": "skillforge", "version": "0.10.0"},
         }
 
     def handle_tools_list(self, params):
@@ -194,20 +205,25 @@ class MCPServer:
                 {
                     "name": "route_skills",
                     "description": (
-                        "Route the user's prompt to the most relevant skills from the catalog "
-                        "and return SKILL.md context (full body or RAG chunks per CONTEXT_MODE). "
-                        "Returns up to 7 skills. "
-                        "Pass project_root for per-repo SQLite in .skillforge/ and learning. "
-                        "Optional include_project_rag merges top chunks from `skillforge index` into context. "
-                        "On success, _meta includes schema_version ("
-                        f"{MCP_RESPONSE_SCHEMA_VERSION}), sources[] (kind skill or file), "
-                        "budget (chars_skill_bodies, chars_project_chunks), fusion (MMR when combined index+RAG), "
-                        "candidates_preview, context_items_count."
+                        "Two-step when SKILLFORGE_ROUTER_MODE=host (no in-process router LLM): (1) call with prompt "
+                        "only — returns a tight numbered shortlist + session_id; (2) call again with the same prompt "
+                        "and picked_names (JSON array of exact catalog ids from the list) to load SKILL.md chunks. "
+                        "With auto router modes, one call returns context. Optional conversation, project_root, "
+                        "include_project_rag. picked_names may also be passed in embedding/full mode to skip "
+                        "auto-pick and use the host-provided list."
                     ),
                     "inputSchema": {
                         "type": "object",
                         "properties": {
                             "prompt": {"type": "string", "description": "The user's prompt or task description"},
+                            "picked_names": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": (
+                                    "Host-chosen skill ids from the shortlist (same prompt as step 1). "
+                                    "Omit on first host-mode call; required for finalize after shortlist."
+                                ),
+                            },
                             "project_root": {
                                 "type": "string",
                                 "description": "Repo/workspace root — stores orchestrator state in .skillforge/",
@@ -231,12 +247,80 @@ class MCPServer:
                             },
                             "user_id": {
                                 "type": "string",
-                                "description": "Logical user id for weights/sessions/events (same as HTTP user id string)",
+                                "description": "Logical user id for weights/sessions/events",
                             },
                         },
                         "required": ["prompt"],
                     },
                 },
+                {
+                    "name": "search_skills",
+                    "description": (
+                        "Embedding-only retrieval: top skills for a query with similarity scores "
+                        "and descriptions (no Haiku, no full route). Use to explore the catalog."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "query": {"type": "string", "description": "Search query or task text"},
+                            "limit": {
+                                "type": "integer",
+                                "description": f"Max skills to return (default {TOP_K_CANDIDATES})",
+                            },
+                            "project_root": {"type": "string"},
+                            "user_id": {"type": "string"},
+                        },
+                        "required": ["query"],
+                    },
+                },
+                {
+                    "name": "explain_route",
+                    "description": (
+                        "Debug routing: embedding facets for the shortlist (same query text as route_skills when "
+                        "`conversation` is passed — conversation-aware when SKILLFORGE_ROUTER_CONV_MAX_TURNS > 0), "
+                        "optional Haiku rerank, Haiku/embedding-only pick with reasoning, and policy merge audit. "
+                        "Does not write sessions or increment uses."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "prompt": {"type": "string"},
+                            "conversation": {"type": "array", "items": {"type": "object"}},
+                            "limit": {
+                                "type": "integer",
+                                "description": "Max shortlist rows in facets (default TOP_K)",
+                            },
+                            "project_root": {"type": "string"},
+                            "user_id": {"type": "string"},
+                        },
+                        "required": ["prompt"],
+                    },
+                },
+                {
+                    "name": "get_skill",
+                    "description": (
+                        "Load one skill by name: full SKILL.md body or a short summary. "
+                        "Use for deterministic workflows when you already know the skill name."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "skill_name": {"type": "string"},
+                            "format": {
+                                "type": "string",
+                                "enum": ["full", "summary"],
+                                "description": "summary = description + first ~8k chars of body",
+                                "default": "full",
+                            },
+                            "max_chars": {
+                                "type": "integer",
+                                "description": "If > 0, truncate body to this many characters",
+                                "default": 0,
+                            },
+                        },
+                        "required": ["skill_name"],
+                    },
+                },
                 {
                     "name": "list_skills",
                     "description": (
@@ -303,6 +387,8 @@ class MCPServer:
                     "name": "materialize_project",
                     "description": (
                         "Write project-local Skillforge files: .cursor/rules/skillforge.mdc, "
+                        ".cursor/commands/skillforge.md (Cursor /skillforge), "
+                        ".claude/commands/skillforge.md (Claude Code /skillforge), "
                         "docs/SKILLFORGE-PRD.md, and a CLAUDE.md section. "
                         "Pass project_root (workspace path) and skill_names from route_skills. "
                         "Hosts must supply project_root; MCP does not infer cwd."
@@ -318,7 +404,11 @@ class MCPServer:
                             },
                             "merge": {
                                 "type": "boolean",
-                                "description": "If false and .cursor/rules/skillforge.mdc exists, skip overwriting that file",
+                                "description": (
+                                "If false and .cursor/rules/skillforge.mdc, "
+                                ".cursor/commands/skillforge.md, or "
+                                ".claude/commands/skillforge.md exists, skip overwriting those files"
+                                ),
                                 "default": True,
                             },
                         },
@@ -358,6 +448,12 @@ class MCPServer:
 
         if name == "route_skills":
             return await self._tool_route_skills(args)
+        if name == "search_skills":
+            return self._tool_search_skills(args)
+        if name == "explain_route":
+            return await self._tool_explain_route(args)
+        if name == "get_skill":
+            return self._tool_get_skill(args)
         if name == "list_skills":
             return self._tool_list_skills(args)
         if name == "skill_feedback":
@@ -396,6 +492,16 @@ class MCPServer:
                 ),
             }
 
+        picked_names_from_host_supplied = "picked_names" in args
+        if picked_names_from_host_supplied:
+            raw_pn = args.get("picked_names")
+            if isinstance(raw_pn, list):
+                picked_names_from_host = [str(x) for x in raw_pn if x is not None]
+            else:
+                picked_names_from_host = []
+        else:
+            picked_names_from_host = None
+
         con = self._get_con(args)
         result = await run_route_turn(
             con,
@@ -406,6 +512,8 @@ class MCPServer:
             session_id=session_id,
             project_root=pr,
             include_project_rag=self._include_project_rag_from_args(args),
+            picked_names_from_host=picked_names_from_host,
+            picked_names_from_host_supplied=picked_names_from_host_supplied,
         )
         picked_names = result["picked_names"]
         reasoning = result["reasoning"]
@@ -425,22 +533,29 @@ class MCPServer:
                     "context_mode": self.router.context_mode,
                     "context_items_count": len(context_items),
                     "project_rag_items_count": (result.get("event") or {}).get("project_rag_items_count", 0),
+                    "host_pick_shortlist": bool(result.get("host_pick_shortlist")),
                 }
                 (d / "last_route.json").write_text(json.dumps(snap, indent=2), encoding="utf-8")
             except OSError:
                 pass
 
         db_disp = redact_display_path(db_path) if redaction_enabled() else str(db_path)
-        blocks = [
-            f"# Skillforge — routed {len(picked_names)} skill(s); context=`{self.router.context_mode}`",
-            f"_DB:_ `{db_disp}`",
-            f"_Reasoning: {reasoning}_" if reasoning else "",
-            "",
-        ]
-        if context_items:
-            blocks.append(format_context_items_markdown(context_items))
-        elif not picked_names:
-            blocks.append("_No skills matched this prompt closely enough to load._")
+        if result.get("host_pick_shortlist"):
+            response_text = (result.get("host_pick_markdown") or "").strip() + (
+                f"\n\n---\n_session_id:_ `{result['session_id']}` · _orchestrator:_ `{db_disp}`"
+            )
+            blocks = [response_text]
+        else:
+            blocks = [
+                f"# Skillforge — routed {len(picked_names)} skill(s); context=`{self.router.context_mode}`",
+                f"_DB:_ `{db_disp}`",
+                f"_Reasoning: {reasoning}_" if reasoning else "",
+                "",
+            ]
+            if context_items:
+                blocks.append(format_context_items_markdown(context_items))
+            elif not picked_names:
+                blocks.append("_No skills matched this prompt closely enough to load._")
         response_text = "\n".join(b for b in blocks if b is not None)
         meta = build_route_skills_meta(
             result=result,
@@ -453,11 +568,208 @@ class MCPServer:
             fusion=(result.get("event") or {}).get("context_fusion"),
             context_redaction=(result.get("event") or {}).get("context_redaction"),
         )
+        if result.get("host_pick_shortlist"):
+            meta["host_pick_shortlist"] = True
+            meta["host_pick_candidates"] = result.get("host_pick_candidates") or []
         return {
             "content": [{"type": "text", "text": response_text}],
             "_meta": meta,
         }
 
+    def _tool_search_skills(self, args):
+        query = (args.get("query") or "").strip()
+        user_id = self._mcp_user_id(args)
+        pr = self._project_root_from_args(args)
+        db_path = resolve_orchestrator_db(pr)
+        if not query:
+            return {
+                "content": [{"type": "text", "text": "query is required."}],
+                "isError": True,
+            }
+        try:
+            limit = int(args.get("limit") or TOP_K_CANDIDATES)
+        except (TypeError, ValueError):
+            limit = TOP_K_CANDIDATES
+        limit = max(1, min(limit, 50))
+        con = self._get_con(args)
+        policies_cfg = load_route_policies_config(pr)
+        overlay_audit = []
+        exclude_skills, routing_boosts, project_notes = parse_routing_overlay(
+            policies_cfg,
+            by_name=self.router._by_name,
+            audit_out=overlay_audit,
+        )
+        q2 = merge_project_notes_into_route_query(query, project_notes, pr)
+        facets = self.router.shortlist_with_facets(
+            q2,
+            con,
+            k=limit,
+            user_id=user_id,
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+        )
+        lines = ["# search_skills — embedding shortlist", ""]
+        for f in facets:
+            lines.append(
+                f"- **{f['name']}** (cos {f['cosine_similarity']}, score {f['routing_score']}): "
+                f"{(f.get('description_preview') or '')[:220]}"
+            )
+        text = "\n".join(lines)
+        return {
+            "content": [{"type": "text", "text": text}],
+            "_meta": {
+                "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
+                "tool": "search_skills",
+                "orchestrator_db": redact_display_path(db_path) if redaction_enabled() else str(db_path),
+                "results": facets,
+                "count": len(facets),
+            },
+        }
+
+    async def _tool_explain_route(self, args):
+        prompt = (args.get("prompt") or "").strip()
+        conversation = args.get("conversation") or []
+        user_id = self._mcp_user_id(args)
+        pr = self._project_root_from_args(args)
+        db_path = resolve_orchestrator_db(pr)
+        if not prompt:
+            return {
+                "content": [{"type": "text", "text": "prompt is required."}],
+                "isError": True,
+            }
+        try:
+            limit = int(args.get("limit") or TOP_K_CANDIDATES)
+        except (TypeError, ValueError):
+            limit = TOP_K_CANDIDATES
+        limit = max(1, min(limit, 50))
+        con = self._get_con(args)
+        policies_cfg = load_route_policies_config(pr)
+        overlay_audit = []
+        exclude_skills, routing_boosts, project_notes = parse_routing_overlay(
+            policies_cfg,
+            by_name=self.router._by_name,
+            audit_out=overlay_audit,
+        )
+        route_query = merge_project_notes_into_route_query(
+            build_route_query_text(prompt, conversation),
+            project_notes,
+            pr,
+        )
+        facets = self.router.shortlist_with_facets(
+            route_query,
+            con,
+            k=limit,
+            user_id=user_id,
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+        )
+        candidates = self.router.shortlist(
+            route_query,
+            con,
+            limit,
+            user_id,
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+        )
+        candidates = await self.router.rerank_candidates_haiku(route_query, conversation, candidates)
+        picked, reasoning = await self.router.pick_final(
+            prompt, conversation, candidates, route_query=route_query
+        )
+        merged, policy_audit = merge_policy_includes(
+            prompt,
+            list(picked),
+            policies_cfg,
+            self.router._by_name,
+            con,
+            user_id,
+            max_active=MAX_ACTIVE_SKILLS,
+        )
+        router_mode = "full" if self.router.anthropic else "embedding-only"
+        notes_effective = bool(project_notes.strip() and (pr or "").strip())
+        routing_ov = build_routing_overlay_payload(
+            project_root=pr or "",
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+            project_notes_applied=notes_effective,
+            project_notes_len=len(project_notes) if project_notes else 0,
+            audit=overlay_audit,
+        )
+        explain = {
+            "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
+            "tool": "explain_route",
+            "orchestrator_db": redact_display_path(db_path) if redaction_enabled() else str(db_path),
+            "router_mode": router_mode,
+            "embedding_shortlist": facets,
+            "picked_before_policy": list(picked),
+            "picked_after_policy": merged,
+            "router_reasoning": reasoning,
+            "policy": {
+                "rules_loaded": len(policies_cfg.get("rules") or [])
+                if isinstance(policies_cfg.get("rules"), list)
+                else 0,
+                "audit": policy_audit,
+            },
+        }
+        if routing_ov is not None:
+            explain["routing_overlay"] = routing_ov
+        lines = [
+            "# explain_route — routing diagnostics (no DB writes)",
+            "",
+            f"**Router:** {router_mode}",
+            f"**Picked (router):** {', '.join(picked) if picked else '_(none)_'}",
+            f"**After policies:** {', '.join(merged) if merged else '_(none)_'}",
+            f"**Reasoning:** {reasoning}" if reasoning else "**Reasoning:** _(n/a)_",
+            "",
+            "## Shortlist (embedding)",
+        ]
+        for f in facets[:15]:
+            lines.append(
+                f"- `{f['name']}` cos={f['cosine_similarity']} weight={f['learned_weight']} "
+                f"score={f['routing_score']}"
+            )
+        if policy_audit:
+            lines.extend(["", "## Policy audit"])
+            for row in policy_audit[:30]:
+                lines.append(f"- {row}")
+        body = "\n".join(lines)
+        return {"content": [{"type": "text", "text": body}], "_meta": explain}
+
+    def _tool_get_skill(self, args):
+        name = (args.get("skill_name") or "").strip()
+        fmt = (args.get("format") or "full").strip().lower()
+        if fmt not in ("full", "summary"):
+            fmt = "full"
+        max_chars = args.get("max_chars")
+        try:
+            mc = int(max_chars) if max_chars is not None else 0
+        except (TypeError, ValueError):
+            mc = 0
+        if not name or name not in self.skills:
+            return {
+                "content": [{"type": "text", "text": f"Unknown skill: {name or '(empty)'}"}],
+                "isError": True,
+            }
+        s = self.skills[name]
+        if fmt == "summary":
+            body = f"{s.description}\n\n---\n\n{(s.body or '')[:8000]}"
+        else:
+            body = s.body or ""
+        if mc > 0:
+            body = body[:mc]
+        header = f"# get_skill: `{name}`\n**Source:** {s.source} · **format:** {fmt}\n\n"
+        text = header + body
+        return {
+            "content": [{"type": "text", "text": text}],
+            "_meta": {
+                "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
+                "tool": "get_skill",
+                "skill_name": name,
+                "source": s.source,
+                "format": fmt,
+                "chars": len(body),
+            },
+        }
+
     def _tool_list_skills(self, args):
         user_id = self._mcp_user_id(args)
         con = self._get_con(args)
@@ -551,6 +863,13 @@ class MCPServer:
         session_id = args.get("session_id") or None
         user_id = self._mcp_user_id(args)
         merge = args.get("merge", True)
+        if SKILLFORGE_ROUTER_MODE == "host":
+            msg = (
+                "skillforge_bootstrap does not support SKILLFORGE_ROUTER_MODE=host (two-step routing). "
+                "Set SKILLFORGE_ROUTER_MODE=embedding for one-shot bootstrap, or call route_skills twice "
+                "(shortlist then picked_names) and materialize_project yourself."
+            )
+            return {"content": [{"type": "text", "text": msg}], "isError": True}
         if not prompt.strip():
             return {"content": [{"type": "text", "text": "No prompt provided."}], "isError": True}
         if not root: