feat(skill): deepen compile pipeline + design-consistency cleanup

Two rounds of review fixes on top of the skill factory.

Design consistency (from PR-level review):
- workspace: restore_iteration now saves the current skill before
  overwriting, matching skill new's reversibility invariant — a user who
  edits files in chat then rolls back keeps those edits as a new iteration
- generator: validate_skill moved inside Generator.run() so /skill new in
  chat gets the same quality gate as openkb skill new (was CLI-only)
- skill/__init__: single-source path helpers (skills_root / skill_dir /
  skill_workspace_dir) and frontmatter parser (extract_frontmatter /
  extract_description). Removes duplicated path construction across 6+
  sites and four divergent frontmatter implementations
- cli/chat: route every "output/skills/<name>" construction through the
  helper; add missing "Run openkb init first." hint to skill validate /
  skill eval; capitalize /skill autocomplete; fix stale comment

Skills domain quality (the compile pipeline can actually distill now):
- creator/tools: skill agent gets the query agent's deep-retrieval
  toolset — get_page_content for page-range source reads on PageIndex
  docs, get_image for figures. query_wiki demoted to narrow follow-ups
  only; primary traversal is direct file reads
- skill_create.md: rewritten end-to-end. Working method now mirrors
  query's 6-step strategy (survey -> summaries -> sources via full_text
  pointer -> concepts -> draft -> review-and-revise). Required output
  adds a "Core decision rules" section (>=5 if-X-then-Y rules) and a
  "Known gaps" section. Description-writing rules optimize for trigger
  predicate (situations, keywords, exclusions), not topic accuracy
- evaluator: was a tautology (generator and grader both saw only the
  description -> a LOREM IPSUM body could pass 100%). Now the generator
  reads body + reference excerpts so prompts reflect actual claims, and
  a second grader (grade_coverage) checks whether the body has substance
  to support what the description promises. CLI surfaces both Trigger
  accuracy and Body coverage
- validator: foreign-wikilink gate. SKILL.md and references/*.md cannot
  contain [[concepts/]] / [[summaries/]] / [[sources/]] — those point at
  the producer's wiki, which doesn't ship; on the consumer's machine
  they are dead links plus wasted context tokens. Only
  [[references/<slug>]] (which ships with the skill) is valid
- prompt's source-use rules: paraphrase, short quotes <=40 words, no
  bulk copying; provenance audit is the producer's responsibility at
  compile time, not something to ship in the artifact

Tests: +9 new (rollback preservation, body-coverage grader, foreign
wikilink detection in body and references). 504 passing.

Author: KylinMountain

openkb/agent/chat.py

@@ -215,7 +215,7 @@ def _bottom_toolbar(session: ChatSession) -> FormattedText:
     ("/list",   "List all documents"),
     ("/lint",   "Lint the knowledge base"),
     ("/add",    "Add a document or directory"),
-    ("/skill",  "compile a skill (try `/skill new <name> \"intent\"`)"),
+    ("/skill",  "Compile a skill (try `/skill new <name> \"intent\"`)"),
 ]
 
 
@@ -530,7 +530,8 @@ async def _handle_slash_skill(arg: str, kb_dir: Path, style: Style) -> None:
         _fmt(style, ("class:error", f"[ERROR] {err}\n"))
         return
 
-    target = kb_dir / "output" / "skills" / name
+    from openkb.skill import skill_dir
+    target = skill_dir(kb_dir, name)
     if target.exists():
         _fmt(style, ("class:error",
             f"[ERROR] output/skills/{name}/ already exists. Remove it first "
@@ -544,19 +545,31 @@ async def _handle_slash_skill(arg: str, kb_dir: Path, style: Style) -> None:
 
     from openkb.skill.generator import Generator
     _fmt(style, ("class:slash.help", f"Compiling skill '{name}'...\n"))
+    gen = Generator(
+        target_type="skill",
+        name=name,
+        intent=intent,
+        kb_dir=kb_dir,
+        model=model,
+    )
     try:
-        gen = Generator(
-            target_type="skill",
-            name=name,
-            intent=intent,
-            kb_dir=kb_dir,
-            model=model,
-        )
         await gen.run()
     except RuntimeError as exc:
         _fmt(style, ("class:error", f"[ERROR] {exc}\n"))
         return
 
+    # Surface validation issues from Generator.run (same gate as CLI).
+    result = gen.validation
+    if result is not None and (result.errors or result.warnings):
+        _fmt(style, ("class:error", "[WARN] Validation found issues:\n"))
+        for err in result.errors:
+            _fmt(style, ("class:error", f"  ERROR:   {err}\n"))
+        for warn in result.warnings:
+            _fmt(style, ("class:error", f"  WARN:    {warn}\n"))
+        _fmt(style, ("class:slash.help",
+            f"Run `openkb skill validate {name}` to re-check, or "
+            f"`openkb skill rollback {name}` to revert.\n"))
+
     _fmt(style, ("class:slash.ok", f"Saved: output/skills/{name}/\n"))
     _fmt(style, ("class:slash.help",
         f"Iterate: ask follow-up questions in this chat and the agent can "

openkb/cli.py

@@ -206,7 +206,9 @@ def _preflight_skill_new(kb_dir: Path, name: str) -> str | None:
 
 def _clear_existing_skill_dir(kb_dir: Path, name: str) -> None:
     """Delete an existing ``<kb>/output/skills/<name>/`` directory."""
-    target = kb_dir / "output" / "skills" / name
+    from openkb.skill import skill_dir
+
+    target = skill_dir(kb_dir, name)
     if target.exists():
         shutil.rmtree(target)
 
@@ -1465,10 +1467,11 @@ def skill_new(ctx, name, intent, yes_flag):
     # When overwriting, we don't destroy the old skill — we copy it
     # into <kb>/output/skills/<name>-workspace/iteration-N/ first, so
     # the user can roll back via `openkb skill rollback`. See
-    # ``openkb/skill_workspace.py``.
+    # ``openkb/skill/workspace.py``.
+    from openkb.skill import skill_dir
     from openkb.skill.workspace import save_iteration, write_diff
 
-    target = kb_dir / "output" / "skills" / name
+    target = skill_dir(kb_dir, name)
     saved_iteration: Path | None = None
     if target.exists():
         if yes_flag:
@@ -1491,17 +1494,18 @@ def skill_new(ctx, name, intent, yes_flag):
             )
             ctx.exit(1)
 
-    # Run the generator
+    # Run the generator. Generator.run handles compile -> validate ->
+    # marketplace publish, so both CLI and chat get the same quality gate.
     from openkb.skill.generator import Generator
     click.echo(f"Compiling skill '{name}'...")
+    gen = Generator(
+        target_type="skill",
+        name=name,
+        intent=intent,
+        kb_dir=kb_dir,
+        model=model,
+    )
     try:
-        gen = Generator(
-            target_type="skill",
-            name=name,
-            intent=intent,
-            kb_dir=kb_dir,
-            model=model,
-        )
         asyncio.run(gen.run())
     except RuntimeError as exc:
         click.echo(f"[ERROR] {exc}", err=True)
@@ -1517,12 +1521,10 @@ def skill_new(ctx, name, intent, yes_flag):
                 "diff generation failed: %s", exc, exc_info=True
             )
 
-    # Auto-validate the freshly compiled skill. Surface issues but don't
-    # block — files are on disk and the user can fix or rollback.
-    from openkb.skill.validator import validate_skill
-    skill_dir = kb_dir / "output" / "skills" / name
-    result = validate_skill(skill_dir)
-    if result.errors or result.warnings:
+    # Surface validation issues. Don't block — files are on disk and
+    # the user can fix or rollback.
+    result = gen.validation
+    if result is not None and (result.errors or result.warnings):
         click.echo("\n[WARN] Validation found issues:")
         for err in result.errors:
             click.echo(f"  ERROR:   {err}")
@@ -1581,7 +1583,8 @@ def skill_history(ctx, name):
             stamp = "-"
         click.echo(f"  {n}  {rel}  {stamp}")
 
-    current = kb_dir / "output" / "skills" / name
+    from openkb.skill import skill_dir
+    current = skill_dir(kb_dir, name)
     if current.is_dir():
         rel_curr = current.relative_to(kb_dir)
         click.echo(f"\n  Current: {rel_curr}/")
@@ -1642,7 +1645,8 @@ def skill_rollback(ctx, name, to_n, yes_flag):
         )
         ctx.exit(1)
 
-    current = kb_dir / "output" / "skills" / name
+    from openkb.skill import skill_dir
+    current = skill_dir(kb_dir, name)
     if current.exists():
         prompt = (
             f"This will overwrite output/skills/{name}/ with {target_label}. Continue?"
@@ -1681,27 +1685,28 @@ def skill_rollback(ctx, name, to_n, yes_flag):
 @click.pass_context
 def skill_validate(ctx, name, strict):
     """Validate one skill (by name) or all compiled skills in this KB."""
+    from openkb.skill import skill_dir, skills_root
     from openkb.skill.validator import validate_skill
 
     kb_dir = _find_kb_dir(ctx.obj.get("kb_dir_override"))
     if kb_dir is None:
-        click.echo("No knowledge base found.", err=True)
+        click.echo("No knowledge base found. Run `openkb init` first.", err=True)
         ctx.exit(1)
 
-    skills_root = kb_dir / "output" / "skills"
-    if not skills_root.is_dir():
+    root = skills_root(kb_dir)
+    if not root.is_dir():
         click.echo("No skills found. Compile one with `openkb skill new`.")
         return
 
     if name:
-        target = skills_root / name
+        target = skill_dir(kb_dir, name)
         if not target.is_dir():
             click.echo(f"[ERROR] Skill '{name}' not found.", err=True)
             ctx.exit(1)
         targets = [target]
     else:
         targets = sorted(
-            d for d in skills_root.iterdir()
+            d for d in root.iterdir()
             if d.is_dir() and not d.name.endswith("-workspace")
         )
 
@@ -1748,12 +1753,14 @@ def skill_eval(ctx, name, save_flag, eval_set_path, count):
         run_eval, save_eval_set, load_eval_set, EvalPrompt,
     )
 
+    from openkb.skill import skill_dir as _skill_dir
+
     kb_dir = _find_kb_dir(ctx.obj.get("kb_dir_override"))
     if kb_dir is None:
-        click.echo("No knowledge base found.", err=True)
+        click.echo("No knowledge base found. Run `openkb init` first.", err=True)
         ctx.exit(1)
 
-    skill_dir = kb_dir / "output" / "skills" / name
+    skill_dir = _skill_dir(kb_dir, name)
     if not skill_dir.is_dir():
         click.echo(f"[ERROR] Skill '{name}' not found.", err=True)
         ctx.exit(1)
@@ -1783,16 +1790,29 @@ def skill_eval(ctx, name, save_flag, eval_set_path, count):
 
     click.echo(f"\nEval set: {result.total} prompts")
     click.echo(
-        f"Pass rate: {result.passed}/{result.total} "
-        f"({result.pass_rate * 100:.0f}%)"
+        f"Trigger accuracy: {result.passed}/{result.total} "
+        f"({result.pass_rate * 100:.0f}%)  "
+        f"— does the description fire on the right questions?"
+    )
+    click.echo(
+        f"Body coverage:    {result.coverage_passed}/{result.trigger_questions} "
+        f"({result.coverage_rate * 100:.0f}%)  "
+        f"— does SKILL.md actually support what the description promises?"
     )
 
     if result.misses:
-        click.echo(f"\nMisses ({len(result.misses)}):")
+        click.echo(f"\nTrigger misses ({len(result.misses)}):")
         for miss in result.misses:
             click.echo(f"  - {miss.label} {miss.prompt.question}")
-    else:
-        click.echo("\nAll prompts graded correctly.")
+
+    if result.coverage_misses:
+        click.echo(f"\nCoverage gaps ({len(result.coverage_misses)}):")
+        for gap in result.coverage_misses:
+            tail = f" — {gap.reason}" if gap.reason else ""
+            click.echo(f"  - {gap.prompt.question}{tail}")
+
+    if not result.misses and not result.coverage_misses:
+        click.echo("\nAll prompts graded correctly with full body support.")
 
     if save_flag and eval_set is None:
         path = save_eval_set(kb_dir, name, result.prompts)