selftune 0.2.23 → 0.2.25

package/cli/selftune/uninstall.ts

@@ -121,7 +121,8 @@ function isSelfttuneHookEntry(entry: unknown): boolean {
 
   // Check direct command
   if (typeof obj.command === "string") {
-    return SELFTUNE_HOOK_SCRIPTS.some((script) => obj.command?.includes(script));
+    const command = obj.command;
+    return SELFTUNE_HOOK_SCRIPTS.some((script) => command.includes(script));
   }
 
   // Check hooks array (the nested structure used in settings.json)

package/cli/selftune/utils/canonical-log.ts

@@ -1,4 +1,4 @@
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 
 import {
   type CanonicalPlatform,
@@ -37,11 +37,3 @@ export function serializeCanonicalRecords(records: CanonicalRecord[], pretty = f
     records.map((record) => JSON.stringify(record)).join("\n") + (records.length > 0 ? "\n" : "")
   );
 }
-
-export function writeCanonicalExport(
-  records: CanonicalRecord[],
-  outPath: string,
-  pretty = false,
-): void {
-  writeFileSync(outPath, serializeCanonicalRecords(records, pretty), "utf-8");
-}

package/cli/selftune/utils/cli-error.ts

@@ -21,11 +21,20 @@ export type CLIErrorCode =
   | "MISSING_FLAG"
   | "CONFIG_MISSING"
   | "FILE_NOT_FOUND"
+  | "FILE_EXISTS"
   | "AGENT_NOT_FOUND"
   | "UNKNOWN_COMMAND"
   | "GUARD_BLOCKED"
   | "OPERATION_FAILED"
+  | "API_ERROR"
+  | "AUTH_MISSING"
+  | "BLEND_NO_LOGS"
+  | "INVALID_PROPOSAL"
+  | "INVALID_STATUS"
   | "MISSING_DATA"
+  | "NOT_FOUND"
+  | "REPLAY_UNAVAILABLE"
+  | "UNSUPPORTED_TYPE"
   | "INTERNAL_ERROR";
 
 export class CLIError extends Error {

package/cli/selftune/utils/llm-call.ts

@@ -2,7 +2,7 @@
  * Shared LLM call utility.
  *
  * Provides a unified interface for calling LLMs via agent subprocess
- * (claude/codex/opencode). Extracted from grade-session.ts so other
+ * (claude/codex/opencode/pi). Extracted from grade-session.ts so other
  * modules can reuse the same calling logic.
  */
 
@@ -14,6 +14,8 @@ import { AGENT_CANDIDATES } from "../constants.js";
 import { createLogger } from "./logging.js";
 
 const logger = createLogger("llm-call");
+export const LLM_BACKED_AGENT_CANDIDATES = ["claude", "codex", "opencode", "pi"] as const;
+export type LlmBackedAgent = (typeof LLM_BACKED_AGENT_CANDIDATES)[number];
 
 // ---------------------------------------------------------------------------
 // Model alias resolution
@@ -48,6 +50,17 @@ function resolveOpenCodeModel(flag: string): string {
   return OPENCODE_MODEL_MAP[flag] ?? flag;
 }
 
+const PI_THINKING_MAP: Record<EffortLevel, string> = {
+  low: "low",
+  medium: "medium",
+  high: "high",
+  max: "xhigh",
+};
+
+function resolvePiThinking(effort: EffortLevel): string {
+  return PI_THINKING_MAP[effort];
+}
+
 // ---------------------------------------------------------------------------
 // Bundled agent file loading (for codex inline prompt injection)
 // ---------------------------------------------------------------------------
@@ -79,6 +92,33 @@ export function detectAgent(): string | null {
   return null;
 }
 
+/** Detect first available agent CLI that can execute selftune LLM-backed workflows. */
+export function detectLlmAgent(): LlmBackedAgent | null {
+  for (const agent of LLM_BACKED_AGENT_CANDIDATES) {
+    if (Bun.which(agent)) return agent;
+  }
+  return null;
+}
+
+export function isLlmBackedAgent(value: string): value is LlmBackedAgent {
+  return (LLM_BACKED_AGENT_CANDIDATES as readonly string[]).includes(value);
+}
+
+function unsupportedAgentError(agent: string, capability: "llm calls" | "subagent calls"): Error {
+  const supported = LLM_BACKED_AGENT_CANDIDATES.join(", ");
+  if (agent === "openclaw") {
+    return new Error(
+      `Detected agent CLI '${agent}', but selftune ${capability} currently support only ${supported}. ` +
+        `LLM-backed judge, eval, and optimizer workflows are unavailable on ${agent}; ` +
+        `use Claude Code, Codex, OpenCode, or Pi for those workflows, or stay on ingest/sync support for ${agent}.`,
+    );
+  }
+
+  return new Error(
+    `Unknown agent '${agent}'. selftune ${capability} currently support only ${supported}.`,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Markdown fence stripping
 // ---------------------------------------------------------------------------
@@ -160,7 +200,7 @@ function sleep(ms: number): Promise<void> {
 /** Effort level for Claude CLI (controls thinking depth). Opus 4.6 only for 'max'. */
 export type EffortLevel = "low" | "medium" | "high" | "max";
 
-/** Call LLM via agent subprocess (claude/codex/opencode). Returns raw text. */
+/** Call LLM via agent subprocess (claude/codex/opencode/pi). Returns raw text. */
 export async function callViaAgent(
   systemPrompt: string,
   userPrompt: string,
@@ -194,8 +234,30 @@ export async function callViaAgent(
         cmd.push("--model", resolveOpenCodeModel(modelFlag));
       }
       cmd.push(promptContent);
+    } else if (agent === "pi") {
+      cmd = [
+        "pi",
+        "-p",
+        "--mode",
+        "text",
+        "--no-session",
+        "--no-tools",
+        "--no-extensions",
+        "--no-skills",
+        "--no-prompt-templates",
+        "--no-themes",
+        "--system-prompt",
+        systemPrompt,
+      ];
+      if (modelFlag) {
+        cmd.push("--model", modelFlag);
+      }
+      if (effort) {
+        cmd.push("--thinking", resolvePiThinking(effort));
+      }
+      cmd.push(userPrompt);
     } else {
-      throw new Error(`Unknown agent: ${agent}`);
+      throw unsupportedAgentError(agent, "llm calls");
     }
 
     // Retry loop with exponential backoff for transient failures
@@ -256,6 +318,23 @@ export async function callViaAgent(
   }
 }
 
+function mapAllowedToolsToPi(tools?: string[]): string[] {
+  if (!tools || tools.length === 0) return [];
+
+  const mapped = new Set<string>();
+  for (const tool of tools) {
+    if (tool === "Read") mapped.add("read");
+    else if (tool === "Write") mapped.add("write");
+    else if (tool === "Edit") mapped.add("edit");
+    else if (tool === "Bash") mapped.add("bash");
+    else if (tool === "Grep") mapped.add("grep");
+    else if (tool === "Glob" || tool === "Find") mapped.add("find");
+    else if (tool === "LS" || tool === "Ls") mapped.add("ls");
+  }
+
+  return [...mapped];
+}
+
 // ---------------------------------------------------------------------------
 // Call LLM via named subagent (multi-turn, agentic)
 // ---------------------------------------------------------------------------
@@ -301,10 +380,10 @@ export async function callViaSubagent(options: SubagentCallOptions): Promise<str
     allowedTools,
   } = options;
 
-  const agent = detectAgent();
-  if (!agent || (agent !== "claude" && agent !== "opencode" && agent !== "codex")) {
+  const agent = detectLlmAgent();
+  if (!agent) {
     throw new Error(
-      `Subagent calls require 'claude', 'opencode', or 'codex' CLI in PATH (detected: ${agent ?? "none"})`,
+      "Subagent calls require one of these CLIs in PATH: claude, codex, opencode, pi.",
     );
   }
 
@@ -333,6 +412,47 @@ export async function callViaSubagent(options: SubagentCallOptions): Promise<str
     const agentInstructions = loadAgentInstructions(agentName);
     const fullPrompt = agentInstructions ? `${agentInstructions}\n\n---\n\n${prompt}` : prompt;
     cmd = ["codex", "exec", "--skip-git-repo-check", fullPrompt];
+  } else if (agent === "pi") {
+    if (maxTurns !== 8) {
+      logger.warn(`Subagent '${agentName}' on pi: maxTurns is not supported and will be ignored`);
+    }
+    const agentInstructions = loadAgentInstructions(agentName);
+    const systemParts = [agentInstructions, appendSystemPrompt].filter((value): value is string =>
+      Boolean(value?.trim()),
+    );
+
+    cmd = [
+      "pi",
+      "-p",
+      "--mode",
+      "text",
+      "--no-session",
+      "--no-extensions",
+      "--no-skills",
+      "--no-prompt-templates",
+      "--no-themes",
+    ];
+
+    if (systemParts.length > 0) {
+      cmd.push("--system-prompt", systemParts.join("\n\n"));
+    }
+    if (modelFlag) {
+      cmd.push("--model", modelFlag);
+    }
+    if (effort) {
+      cmd.push("--thinking", resolvePiThinking(effort));
+    }
+
+    const piTools = mapAllowedToolsToPi(allowedTools);
+    if (allowedTools && allowedTools.length > 0) {
+      if (piTools.length > 0) {
+        cmd.push("--tools", piTools.join(","));
+      } else {
+        cmd.push("--no-tools");
+      }
+    }
+
+    cmd.push(prompt);
   } else {
     // Claude Code
     cmd = ["claude", "-p", prompt, "--agent", agentName, "--max-turns", String(maxTurns)];

package/cli/selftune/utils/skill-discovery.ts

@@ -341,6 +341,8 @@ export function extractSkillNamesFromPathReferences(
   const patterns = [
     /(?:^|[\s"'`])(?:[^"'`\s]*?\.agents\/skills\/)([^/\s"'`]+)(?=\/)/gi,
     /(?:^|[\s"'`])(?:[^"'`\s]*?\.codex\/skills\/(?:\.system\/)?)([^/\s"'`]+)(?=\/)/gi,
+    /(?:^|[\s"'`])(?:[^"'`\s]*?\.opencode\/skills\/)([^/\s"'`]+)(?=\/)/gi,
+    /(?:^|[\s"'`])(?:[^"'`\s]*?\.claude\/skills\/)([^/\s"'`]+)(?=\/)/gi,
     /(?:^|[\s"'`])(\/etc\/codex\/skills\/)([^/\s"'`]+)(?=\/)/gi,
   ];
 

package/cli/selftune/workflows/proposals.ts

@@ -0,0 +1,184 @@
+/**
+ * proposals.ts
+ *
+ * Turns strong multi-skill workflow patterns into review-first new-skill
+ * proposals that can be surfaced locally and synced to the cloud.
+ */
+
+import { createHash } from "node:crypto";
+
+import { appendAuditEntry } from "../evolution/audit.js";
+import { appendEvidenceEntry } from "../evolution/evidence.js";
+import type {
+  DiscoveredWorkflow,
+  EvolutionAuditEntry,
+  EvolutionEvidenceEntry,
+  SessionTelemetryRecord,
+  SkillUsageRecord,
+} from "../types.js";
+import { discoverWorkflows } from "./discover.js";
+import { buildWorkflowSkillDraft, type WorkflowSkillDraft } from "./skill-scaffold.js";
+
+export interface WorkflowSkillProposal {
+  proposal_id: string;
+  source_skill_name: string;
+  workflow: DiscoveredWorkflow;
+  draft: WorkflowSkillDraft;
+  summary: string;
+  current_value: string;
+  proposed_value: string;
+  rationale: string;
+  confidence: number;
+}
+
+export interface WorkflowSkillProposalOptions {
+  cwd?: string;
+  skillFilter?: string;
+  maxProposals?: number;
+  minOccurrences?: number;
+  minSynergy?: number;
+  minConsistency?: number;
+  minCompletionRate?: number;
+  resolveSkillPath?: (skillName: string) => string | undefined;
+  existingAuditEntries?: EvolutionAuditEntry[];
+}
+
+export interface WorkflowSkillProposalPersistOptions {
+  now?: Date;
+  sourceSkillPath?: string;
+  appendAudit?: (entry: EvolutionAuditEntry) => void;
+  appendEvidence?: (entry: EvolutionEvidenceEntry) => void;
+}
+
+export const DEFAULT_WORKFLOW_PROPOSAL_MIN_OCCURRENCES = 3;
+export const DEFAULT_WORKFLOW_PROPOSAL_MAX = 2;
+export const DEFAULT_WORKFLOW_PROPOSAL_MIN_SYNERGY = 0;
+export const DEFAULT_WORKFLOW_PROPOSAL_MIN_CONSISTENCY = 0.75;
+export const DEFAULT_WORKFLOW_PROPOSAL_MIN_COMPLETION = 0.65;
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function buildWorkflowProposalConfidence(workflow: DiscoveredWorkflow): number {
+  const normalizedSynergy = clamp01((workflow.synergy_score + 1) / 2);
+  const occurrenceBoost = clamp01(workflow.occurrence_count / 6);
+  return round2(
+    normalizedSynergy * 0.4 +
+      workflow.sequence_consistency * 0.3 +
+      workflow.completion_rate * 0.2 +
+      occurrenceBoost * 0.1,
+  );
+}
+
+function buildWorkflowProposalId(sourceSkillName: string, draft: WorkflowSkillDraft): string {
+  const digest = createHash("sha256")
+    .update(`${sourceSkillName}:${draft.skill_name}:${draft.source_workflow.workflow_id}`)
+    .digest("hex")
+    .slice(0, 16);
+  return `wf-${draft.skill_name}-${digest}`;
+}
+
+function buildWorkflowProposalSummary(
+  workflow: DiscoveredWorkflow,
+  draft: WorkflowSkillDraft,
+): string {
+  const chain = workflow.skills.join(" -> ");
+  return `Create new_skill "${draft.skill_name}" from workflow ${chain} (${workflow.occurrence_count} sessions, synergy ${workflow.synergy_score.toFixed(2)}, consistency ${Math.round(workflow.sequence_consistency * 100)}%, completion ${Math.round(workflow.completion_rate * 100)}%).`;
+}
+
+function hasExistingProposal(proposalId: string, auditEntries: EvolutionAuditEntry[]): boolean {
+  return auditEntries.some((entry) => entry.proposal_id === proposalId);
+}
+
+export function discoverWorkflowSkillProposals(
+  telemetry: SessionTelemetryRecord[],
+  usage: SkillUsageRecord[],
+  options: WorkflowSkillProposalOptions = {},
+): WorkflowSkillProposal[] {
+  const minOccurrences = options.minOccurrences ?? DEFAULT_WORKFLOW_PROPOSAL_MIN_OCCURRENCES;
+  const maxProposals = options.maxProposals ?? DEFAULT_WORKFLOW_PROPOSAL_MAX;
+  const minSynergy = options.minSynergy ?? DEFAULT_WORKFLOW_PROPOSAL_MIN_SYNERGY;
+  const minConsistency = options.minConsistency ?? DEFAULT_WORKFLOW_PROPOSAL_MIN_CONSISTENCY;
+  const minCompletionRate = options.minCompletionRate ?? DEFAULT_WORKFLOW_PROPOSAL_MIN_COMPLETION;
+  const report = discoverWorkflows(telemetry, usage, {
+    minOccurrences,
+    skill: options.skillFilter,
+  });
+  const existingAuditEntries = options.existingAuditEntries ?? [];
+  const proposals: WorkflowSkillProposal[] = [];
+
+  for (const workflow of report.workflows) {
+    if (workflow.occurrence_count < minOccurrences) continue;
+    if (workflow.synergy_score < minSynergy) continue;
+    if (workflow.sequence_consistency < minConsistency) continue;
+    if (workflow.completion_rate < minCompletionRate) continue;
+    if (workflow.skills.length < 2) continue;
+
+    const draft = buildWorkflowSkillDraft(workflow, { cwd: options.cwd });
+    if (!draft.skill_name) continue;
+    if (options.resolveSkillPath?.(draft.skill_name)) continue;
+
+    const sourceSkillName = workflow.skills[0];
+    const proposalId = buildWorkflowProposalId(sourceSkillName, draft);
+    if (hasExistingProposal(proposalId, existingAuditEntries)) continue;
+
+    const summary = buildWorkflowProposalSummary(workflow, draft);
+    const currentValue = `No dedicated workflow skill exists for ${workflow.skills.join(" -> ")}.`;
+    const proposedValue = `Create ${draft.skill_name} at ${draft.skill_path}`;
+    const queryClause = workflow.representative_query.trim()
+      ? ` Common trigger: "${workflow.representative_query.trim()}".`
+      : "";
+
+    proposals.push({
+      proposal_id: proposalId,
+      source_skill_name: sourceSkillName,
+      workflow,
+      draft,
+      summary,
+      current_value: currentValue,
+      proposed_value: proposedValue,
+      rationale: `${summary}${queryClause}`,
+      confidence: buildWorkflowProposalConfidence(workflow),
+    });
+
+    if (proposals.length >= maxProposals) break;
+  }
+
+  return proposals;
+}
+
+export function persistWorkflowSkillProposal(
+  proposal: WorkflowSkillProposal,
+  options: WorkflowSkillProposalPersistOptions = {},
+): void {
+  const timestamp = (options.now ?? new Date()).toISOString();
+  const appendAudit = options.appendAudit ?? appendAuditEntry;
+  const appendEvidence = options.appendEvidence ?? appendEvidenceEntry;
+
+  appendAudit({
+    timestamp,
+    proposal_id: proposal.proposal_id,
+    skill_name: proposal.source_skill_name,
+    action: "created",
+    details: proposal.summary,
+  });
+
+  appendEvidence({
+    timestamp,
+    proposal_id: proposal.proposal_id,
+    skill_name: proposal.source_skill_name,
+    skill_path: options.sourceSkillPath ?? "",
+    target: "new_skill",
+    stage: "proposed",
+    rationale: proposal.rationale,
+    confidence: proposal.confidence,
+    details: proposal.proposed_value,
+    original_text: proposal.current_value,
+    proposed_text: proposal.draft.content,
+  });
+}

package/cli/selftune/workflows/skill-scaffold.ts

@@ -0,0 +1,241 @@
+/**
+ * skill-scaffold.ts
+ *
+ * Builds draft workflow skills from repeated telemetry-discovered workflows.
+ * The draft is preview-first by default so agents can review the scaffold before
+ * writing it into a local skill registry.
+ */
+
+import { join } from "node:path";
+
+import type { DiscoveredWorkflow } from "../types.js";
+import { findGitRepositoryRoot } from "../utils/skill-discovery.js";
+
+export interface WorkflowSkillDraft {
+  title: string;
+  skill_name: string;
+  description: string;
+  output_dir: string;
+  skill_dir: string;
+  skill_path: string;
+  content: string;
+  source_workflow: {
+    workflow_id: string;
+    skills: string[];
+    occurrence_count: number;
+    synergy_score: number;
+    representative_query: string;
+  };
+}
+
+export interface WorkflowSkillDraftOptions {
+  outputDir?: string;
+  skillName?: string;
+  description?: string;
+  cwd?: string;
+}
+
+const STOPWORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "for",
+  "from",
+  "in",
+  "into",
+  "of",
+  "on",
+  "or",
+  "the",
+  "to",
+  "with",
+]);
+
+function splitWords(value: string): string[] {
+  return value
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function titleCase(value: string): string {
+  return splitWords(value)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(" ");
+}
+
+export function slugifyWorkflowSkillName(value: string): string {
+  return splitWords(value)
+    .map((word) => word.toLowerCase())
+    .join("-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function deriveBaseLabel(workflow: DiscoveredWorkflow): string {
+  const filteredQueryWords = splitWords(workflow.representative_query).filter(
+    (word) => !STOPWORDS.has(word.toLowerCase()),
+  );
+
+  if (filteredQueryWords.length >= 2) {
+    return filteredQueryWords.slice(0, 5).join(" ");
+  }
+
+  return `${workflow.skills.join(" ")} workflow`;
+}
+
+function formatList(items: string[]): string {
+  if (items.length === 0) return "";
+  if (items.length === 1) return items[0];
+  if (items.length === 2) return `${items[0]} and ${items[1]}`;
+  return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+
+function wrapFoldedScalar(value: string, width = 78): string[] {
+  const words = value.split(/\s+/).filter(Boolean);
+  const lines: string[] = [];
+  let current = "";
+
+  for (const word of words) {
+    const candidate = current.length === 0 ? word : `${current} ${word}`;
+    if (candidate.length > width && current.length > 0) {
+      lines.push(`  ${current}`);
+      current = word;
+    } else {
+      current = candidate;
+    }
+  }
+
+  if (current.length > 0) lines.push(`  ${current}`);
+  return lines.length > 0 ? lines : ["  "];
+}
+
+export function getDefaultWorkflowSkillOutputDir(cwd: string = process.cwd()): string {
+  const repoRoot = findGitRepositoryRoot(cwd);
+  return join(repoRoot ?? cwd, ".agents", "skills");
+}
+
+export function buildWorkflowSkillDescription(
+  workflow: DiscoveredWorkflow,
+  override?: string,
+): string {
+  if (override && override.trim().length > 0) return override.trim();
+
+  const chain = formatList(workflow.skills);
+  const query = workflow.representative_query.trim();
+  if (query.length > 0) {
+    return `Use when the user wants to ${query}. Coordinates ${chain} in sequence.`;
+  }
+
+  return `Use when the task consistently needs ${chain} in sequence.`;
+}
+
+export function buildWorkflowSkillContent(
+  workflow: DiscoveredWorkflow,
+  title: string,
+  skillName: string,
+  description: string,
+): string {
+  const workflowName = title.endsWith("Workflow") ? title : `${title} Workflow`;
+  const chain = workflow.skills.join(" → ");
+  const query = workflow.representative_query.trim();
+  const foldedDescription = wrapFoldedScalar(description).join("\n");
+
+  const whenToUseLines =
+    query.length > 0
+      ? [
+          `- The user asks to "${query}"`,
+          `- The request repeatedly needs this skill chain: ${chain}`,
+        ]
+      : [`- The request repeatedly needs this skill chain: ${chain}`];
+
+  const executionPlanLines = workflow.skills.map(
+    (skill, index) =>
+      `${index + 1}. Invoke \`${skill}\` in its established role for this workflow.`,
+  );
+
+  return `---
+name: ${skillName}
+description: >
+${foldedDescription}
+metadata:
+  author: selftune-autogen
+  version: 0.1.0
+  category: developer-tools
+  generated_by: selftune workflows scaffold
+  source_workflow_id: ${workflow.workflow_id}
+---
+
+# ${title}
+
+This draft skill was scaffolded by selftune from repeated workflow telemetry.
+Review the routing language and execution notes before broad distribution.
+
+## When to Use
+
+${whenToUseLines.join("\n")}
+
+## Execution Plan
+
+${executionPlanLines.join("\n")}
+
+## Workflows
+
+### ${workflowName}
+- **Skills:** ${chain}
+${query.length > 0 ? `- **Trigger:** ${query}\n` : ""}- **Source:** Discovered from ${workflow.occurrence_count} sessions (synergy: ${workflow.synergy_score.toFixed(2)})
+
+## Notes
+
+- This is a proposal scaffold, not a silently published marketplace skill.
+- Add tighter scope boundaries and richer examples before publishing.
+`;
+}
+
+export function buildWorkflowSkillDraft(
+  workflow: DiscoveredWorkflow,
+  options: WorkflowSkillDraftOptions = {},
+): WorkflowSkillDraft {
+  const baseLabel = options.skillName?.trim() || deriveBaseLabel(workflow);
+  const skillName = slugifyWorkflowSkillName(baseLabel);
+  const title = titleCase(baseLabel) || titleCase(`${workflow.skills.join(" ")} workflow`);
+  const description = buildWorkflowSkillDescription(workflow, options.description);
+  const outputDir = options.outputDir?.trim() || getDefaultWorkflowSkillOutputDir(options.cwd);
+  const skillDir = join(outputDir, skillName);
+  const skillPath = join(skillDir, "SKILL.md");
+
+  return {
+    title,
+    skill_name: skillName,
+    description,
+    output_dir: outputDir,
+    skill_dir: skillDir,
+    skill_path: skillPath,
+    content: buildWorkflowSkillContent(workflow, title, skillName, description),
+    source_workflow: {
+      workflow_id: workflow.workflow_id,
+      skills: workflow.skills,
+      occurrence_count: workflow.occurrence_count,
+      synergy_score: workflow.synergy_score,
+      representative_query: workflow.representative_query,
+    },
+  };
+}
+
+export function formatWorkflowSkillDraft(draft: WorkflowSkillDraft): string {
+  const lines = [
+    `Draft workflow skill: ${draft.title}`,
+    `Skill name: ${draft.skill_name}`,
+    `Output path: ${draft.skill_path}`,
+    `Source workflow: ${draft.source_workflow.workflow_id}`,
+    `Occurrences: ${draft.source_workflow.occurrence_count} | Synergy: ${draft.source_workflow.synergy_score.toFixed(2)}`,
+  ];
+
+  if (draft.source_workflow.representative_query.trim().length > 0) {
+    lines.push(`Representative query: "${draft.source_workflow.representative_query.trim()}"`);
+  }
+
+  lines.push("", draft.content.trimEnd());
+  return lines.join("\n");
+}