feat(skills): wire LLM agent runner for richer skill generation

When ANTHROPIC_API_KEY, OPENAI_API_KEY, or Ollama is configured,
build_skill() now calls AgentRunner.run_task() with a structured JSON
prompt to produce richer activation rules, input/output schemas, epistemic
contract, tools, tests, and stop conditions.

Falls back silently to the deterministic stub when:
- No provider env var is set
- AgentRunner import fails (SDK not installed)
- LLM returns non-JSON or any exception is raised

No new test-time dependencies; the stub path is unchanged.

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

src/specsmith/skills_builder.py

@@ -106,37 +106,113 @@ def _generate_skill_id(name: str) -> str:
     return f"skill-{slug}-{uuid.uuid4().hex[:6]}"
 
 
+_SKILL_PROMPT = """
+You are an expert agent-skill designer for the specsmith AEE framework.
+Given a description, produce a JSON object (no markdown fences) with these exact keys:
+  name         - short title (≤ 60 chars)
+  purpose      - one-sentence purpose
+  activation_rules - list of 2-4 strings describing when to activate
+  input_schema - dict of {field: type description}
+  output_schema - dict of {field: type description}
+  epistemic_contract - one sentence about verifiability guarantees
+  tools_used   - list of tool names (e.g. read_file, run_shell, run_tests)
+  tests_required - list of 1-3 test descriptions
+  stop_conditions - list of 2-3 stop conditions
+  tags         - list of keyword tags
+
+Description: {description}
+
+Respond with ONLY valid JSON. No explanation, no markdown.
+"""
+
+
+def _build_skill_with_llm(description: str, tags: list[str]) -> SkillSpec | None:
+    """Attempt to build a richer skill spec via the LLM provider.
+
+    Returns None if no provider is available or the call fails.
+    """
+    import os
+
+    # Detect whether any provider is configured.
+    has_anthropic = bool(os.environ.get("ANTHROPIC_API_KEY"))
+    has_openai = bool(os.environ.get("OPENAI_API_KEY"))
+    has_ollama = bool(os.environ.get("OLLAMA_HOST") or os.environ.get("SPECSMITH_PROVIDER") == "ollama")
+
+    if not (has_anthropic or has_openai or has_ollama):
+        return None  # No provider — skip LLM, fall through to stub
+
+    try:
+        from specsmith.agent.runner import AgentRunner  # type: ignore[import]
+
+        runner = AgentRunner(project_dir=".")
+        prompt = _SKILL_PROMPT.format(description=description)
+        raw = runner.run_task(prompt)
+        if not raw:
+            return None
+
+        # Strip accidental markdown fences
+        raw = raw.strip()
+        if raw.startswith("```"):
+            raw = "\n".join(raw.splitlines()[1:])
+        if raw.endswith("```"):
+            raw = raw[: raw.rfind("```")]
+        raw = raw.strip()
+
+        data = json.loads(raw)
+        skill_id = _generate_skill_id(data.get("name", description))
+        return SkillSpec(
+            id=skill_id,
+            name=data.get("name", description[:60]),
+            purpose=data.get("purpose", description),
+            activation_rules=data.get("activation_rules", []),
+            input_schema=data.get("input_schema", {}),
+            output_schema=data.get("output_schema", {}),
+            epistemic_contract=data.get("epistemic_contract", ""),
+            tools_used=data.get("tools_used", []),
+            tests_required=data.get("tests_required", []),
+            stop_conditions=data.get("stop_conditions", []),
+            tags=tags + data.get("tags", []),
+        )
+    except Exception:  # noqa: BLE001 — always fall back to stub
+        return None
+
+
 def build_skill(
     description: str,
     project_dir: str = ".",
     tags: list[str] | None = None,
 ) -> SkillSpec:
     """Build a skill from a natural-language description.
 
-    Currently generates a deterministic skill spec from the description.
-    When an AI provider is configured, this will use the LLM to generate
-    richer skill content.
+    When an AI provider is configured (ANTHROPIC_API_KEY, OPENAI_API_KEY,
+    or Ollama), uses the LLM to generate a richer skill spec.
+    Falls back to a deterministic stub when no provider is available or
+    the LLM call fails.
     """
-    # Deterministic generation (no LLM required)
-    name = description.strip()[:60]
-    skill_id = _generate_skill_id(name)
-
-    spec = SkillSpec(
-        id=skill_id,
-        name=name,
-        purpose=description.strip(),
-        activation_rules=[f"User requests: {description[:80]}"],
-        input_schema={"task": "string", "context": "string (optional)"},
-        output_schema={"result": "string", "confidence": "number"},
-        epistemic_contract="Output must be verifiable against the input task.",
-        tools_used=["read_file", "run_shell"],
-        tests_required=[f"Verify {name} produces correct output"],
-        stop_conditions=["Confidence below 0.3", "Timeout exceeded"],
-        tags=tags or [],
-    )
+    tags = tags or []
+
+    # Try LLM-enriched generation first.
+    spec = _build_skill_with_llm(description, tags)
+
+    if spec is None:
+        # Deterministic fallback — no LLM required.
+        name = description.strip()[:60]
+        spec = SkillSpec(
+            id=_generate_skill_id(name),
+            name=name,
+            purpose=description.strip(),
+            activation_rules=[f"User requests: {description[:80]}"],
+            input_schema={"task": "string", "context": "string (optional)"},
+            output_schema={"result": "string", "confidence": "number"},
+            epistemic_contract="Output must be verifiable against the input task.",
+            tools_used=["read_file", "run_shell"],
+            tests_required=[f"Verify {name} produces correct output"],
+            stop_conditions=["Confidence below 0.3", "Timeout exceeded"],
+            tags=tags,
+        )
 
     # Save to disk
-    skill_dir = Path(project_dir).resolve() / ".specsmith" / "skills" / skill_id
+    skill_dir = Path(project_dir).resolve() / ".specsmith" / "skills" / spec.id
     skill_dir.mkdir(parents=True, exist_ok=True)
     (skill_dir / "SKILL.md").write_text(spec.to_markdown(), encoding="utf-8")