feat: add follow-up suggestions after skill completion to reduce first-run churn

Telemetry analysis showed 78% of users churn after a single 2.4-minute session,
mostly dbt developers who run one skill and leave. Users who reach warehouse/schema
tools retain at 24.8% vs 3.3% for those who don't.

This adds contextual "What's Next?" suggestions after skill execution:
- Maps each skill to relevant follow-up skills (e.g., `dbt-develop` → `dbt-test`, `dbt-docs`)
- Includes a warehouse discovery nudge to bridge non-warehouse users
- Appended after `</skill_content>` so it doesn't interfere with skill parsing
- Covers all dbt skills, SQL skills, and data quality skills (12 skills total)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anandgupta42

packages/opencode/src/skill/followups.ts

@@ -0,0 +1,183 @@
+// altimate_change start — skill follow-up suggestions for conversational engagement
+export namespace SkillFollowups {
+  export interface Suggestion {
+    skill: string // skill name to suggest
+    label: string // short display label
+    description: string // why this is a good next step
+    condition?: string // optional: when this suggestion applies
+  }
+
+  // Map from skill name to follow-up suggestions
+  const FOLLOWUPS: Record<string, Suggestion[]> = {
+    "dbt-develop": [
+      {
+        skill: "dbt-test",
+        label: "Add tests",
+        description: "Write schema tests and unit tests for the model you just created to ensure data quality.",
+      },
+      {
+        skill: "dbt-docs",
+        label: "Document your model",
+        description: "Add descriptions to your model and columns in schema.yml for discoverability.",
+      },
+      {
+        skill: "dbt-analyze",
+        label: "Check downstream impact",
+        description: "Analyze the blast radius of your changes on downstream models before merging.",
+      },
+      {
+        skill: "sql-review",
+        label: "Review SQL quality",
+        description: "Run a quality gate on your SQL — lint for anti-patterns and grade readability.",
+      },
+    ],
+    "dbt-troubleshoot": [
+      {
+        skill: "dbt-test",
+        label: "Add regression tests",
+        description: "Now that the bug is fixed, add tests to prevent it from recurring.",
+      },
+      {
+        skill: "dbt-analyze",
+        label: "Check downstream impact",
+        description: "Verify your fix didn't break downstream models.",
+      },
+      {
+        skill: "dbt-develop",
+        label: "Improve the model",
+        description: "Refactor or extend the model now that it's working correctly.",
+      },
+    ],
+    "dbt-test": [
+      {
+        skill: "dbt-develop",
+        label: "Build more models",
+        description: "Continue building new models in your dbt project.",
+      },
+      {
+        skill: "dbt-docs",
+        label: "Document tested models",
+        description: "Add documentation to the models you just tested.",
+      },
+    ],
+    "dbt-docs": [
+      {
+        skill: "dbt-test",
+        label: "Add tests",
+        description: "Add data quality tests for the models you just documented.",
+      },
+      {
+        skill: "dbt-analyze",
+        label: "Analyze lineage",
+        description: "Review column-level lineage to ensure documentation matches data flow.",
+      },
+    ],
+    "dbt-analyze": [
+      {
+        skill: "dbt-test",
+        label: "Add tests for affected models",
+        description: "Add tests to downstream models that could be impacted by changes.",
+      },
+      {
+        skill: "dbt-develop",
+        label: "Make the changes",
+        description: "Proceed with implementing the changes now that you understand the impact.",
+      },
+    ],
+    "sql-review": [
+      {
+        skill: "query-optimize",
+        label: "Optimize performance",
+        description: "Improve query performance based on the review findings.",
+      },
+      {
+        skill: "sql-translate",
+        label: "Translate to another dialect",
+        description: "Port this SQL to a different database dialect.",
+      },
+    ],
+    "sql-translate": [
+      {
+        skill: "sql-review",
+        label: "Review translated SQL",
+        description: "Run a quality check on the translated SQL to catch dialect-specific issues.",
+      },
+    ],
+    "query-optimize": [
+      {
+        skill: "sql-review",
+        label: "Review optimized query",
+        description: "Run a quality gate on the optimized SQL.",
+      },
+      {
+        skill: "cost-report",
+        label: "Check cost impact",
+        description: "Analyze how the optimization affects query costs.",
+      },
+    ],
+    "cost-report": [
+      {
+        skill: "query-optimize",
+        label: "Optimize expensive queries",
+        description: "Optimize the most expensive queries identified in the report.",
+      },
+    ],
+    "pii-audit": [
+      {
+        skill: "sql-review",
+        label: "Review SQL for PII exposure",
+        description: "Check specific queries for PII leakage.",
+      },
+    ],
+    "lineage-diff": [
+      {
+        skill: "dbt-analyze",
+        label: "Full impact analysis",
+        description: "Run a comprehensive impact analysis on the changed models.",
+      },
+      {
+        skill: "dbt-test",
+        label: "Add tests for changed paths",
+        description: "Add tests covering the changed data flow paths.",
+      },
+    ],
+    "schema-migration": [
+      {
+        skill: "dbt-develop",
+        label: "Update dbt models",
+        description: "Update your dbt models to reflect the schema changes.",
+      },
+    ],
+  }
+
+  // A special warehouse nudge for users who haven't connected yet
+  const WAREHOUSE_NUDGE = "**Tip:** Connect a warehouse to validate against real data. Run `/discover` to auto-detect your connections."
+
+  export function get(skillName: string): Suggestion[] {
+    return FOLLOWUPS[skillName] ?? []
+  }
+
+  export function format(skillName: string): string {
+    const suggestions = get(skillName)
+    if (suggestions.length === 0) return ""
+
+    const lines = [
+      "",
+      "---",
+      "",
+      "## What's Next?",
+      "",
+      "Now that this task is complete, here are suggested next steps:",
+      "",
+      ...suggestions.map(
+        (s, i) => `${i + 1}. **${s.label}** — ${s.description} → Use \`/skill ${s.skill}\` or just ask me.`,
+      ),
+      "",
+      WAREHOUSE_NUDGE,
+      "",
+      "*You can continue this conversation — just type your next request.*",
+    ]
+    return lines.join("\n")
+  }
+}
+// altimate_change end

packages/opencode/src/tool/skill.ts

@@ -5,6 +5,9 @@ import { Tool } from "./tool"
 import { Skill } from "../skill"
 import { Ripgrep } from "../file/ripgrep"
 import { iife } from "@/util/iife"
+// altimate_change start — import follow-up suggestions for conversational engagement
+import { SkillFollowups } from "../skill/followups"
+// altimate_change end
 // altimate_change start - import for LLM-based dynamic skill selection
 import { Fingerprint } from "../altimate/fingerprint"
 import { Config } from "../config/config"
@@ -156,6 +159,10 @@ export const SkillTool = Tool.define("skill", async (ctx) => {
       }
       // altimate_change end
 
+      // altimate_change start — append follow-up suggestions after skill content
+      const followups = SkillFollowups.format(skill.name)
+      // altimate_change end
+
       return {
         title: `Loaded skill: ${skill.name}`,
         output: [
@@ -172,6 +179,7 @@ export const SkillTool = Tool.define("skill", async (ctx) => {
           files,
           "</skill_files>",
           "</skill_content>",
+          followups,
         ].join("\n"),
         metadata: {
           name: skill.name,

packages/opencode/test/skill/followups.test.ts

@@ -0,0 +1,131 @@
+import { describe, test, expect } from "bun:test"
+import { SkillFollowups } from "../../src/skill/followups"
+
+describe("SkillFollowups", () => {
+  describe("get", () => {
+    test("returns suggestions for known dbt skills", () => {
+      const suggestions = SkillFollowups.get("dbt-develop")
+      expect(suggestions.length).toBeGreaterThan(0)
+      expect(suggestions[0]).toHaveProperty("skill")
+      expect(suggestions[0]).toHaveProperty("label")
+      expect(suggestions[0]).toHaveProperty("description")
+    })
+
+    test("returns suggestions for dbt-troubleshoot", () => {
+      const suggestions = SkillFollowups.get("dbt-troubleshoot")
+      expect(suggestions.length).toBeGreaterThan(0)
+      // First suggestion should be to add regression tests
+      expect(suggestions[0].skill).toBe("dbt-test")
+    })
+
+    test("returns suggestions for sql-review", () => {
+      const suggestions = SkillFollowups.get("sql-review")
+      expect(suggestions.length).toBeGreaterThan(0)
+    })
+
+    test("returns empty array for unknown skill", () => {
+      const suggestions = SkillFollowups.get("nonexistent-skill")
+      expect(suggestions).toEqual([])
+    })
+
+    test("returns empty array for skills without followups", () => {
+      const suggestions = SkillFollowups.get("teach")
+      expect(suggestions).toEqual([])
+    })
+  })
+
+  describe("format", () => {
+    test("returns formatted follow-up section for dbt-develop", () => {
+      const output = SkillFollowups.format("dbt-develop")
+      expect(output).toContain("## What's Next?")
+      expect(output).toContain("Add tests")
+      expect(output).toContain("dbt-test")
+      expect(output).toContain("Document your model")
+      expect(output).toContain("dbt-docs")
+      expect(output).toContain("/discover")
+      expect(output).toContain("You can continue this conversation")
+    })
+
+    test("returns formatted follow-up section for dbt-troubleshoot", () => {
+      const output = SkillFollowups.format("dbt-troubleshoot")
+      expect(output).toContain("## What's Next?")
+      expect(output).toContain("regression tests")
+      expect(output).toContain("downstream")
+    })
+
+    test("returns empty string for skill without followups", () => {
+      const output = SkillFollowups.format("nonexistent-skill")
+      expect(output).toBe("")
+    })
+
+    test("format includes numbered suggestions", () => {
+      const output = SkillFollowups.format("dbt-develop")
+      expect(output).toContain("1.")
+      expect(output).toContain("2.")
+      expect(output).toContain("3.")
+    })
+
+    test("format includes warehouse nudge", () => {
+      const output = SkillFollowups.format("dbt-develop")
+      expect(output).toContain("Connect a warehouse")
+      expect(output).toContain("/discover")
+    })
+
+    test("all dbt skills have follow-ups defined", () => {
+      const dbtSkills = ["dbt-develop", "dbt-troubleshoot", "dbt-test", "dbt-docs", "dbt-analyze"]
+      for (const skill of dbtSkills) {
+        const suggestions = SkillFollowups.get(skill)
+        expect(suggestions.length).toBeGreaterThan(0)
+      }
+    })
+
+    test("follow-up suggestions reference valid skill names", () => {
+      const KNOWN_SKILLS = [
+        "dbt-develop",
+        "dbt-troubleshoot",
+        "dbt-test",
+        "dbt-docs",
+        "dbt-analyze",
+        "sql-review",
+        "sql-translate",
+        "query-optimize",
+        "cost-report",
+        "pii-audit",
+        "lineage-diff",
+        "schema-migration",
+        "data-viz",
+        "altimate-setup",
+        "teach",
+        "train",
+        "training-status",
+      ]
+      // Check all follow-up skills point to known skills
+      for (const skillName of KNOWN_SKILLS) {
+        const suggestions = SkillFollowups.get(skillName)
+        for (const s of suggestions) {
+          expect(KNOWN_SKILLS).toContain(s.skill)
+        }
+      }
+    })
+
+    test("no skill suggests itself as a follow-up", () => {
+      const skills = [
+        "dbt-develop",
+        "dbt-troubleshoot",
+        "dbt-test",
+        "dbt-docs",
+        "dbt-analyze",
+        "sql-review",
+        "sql-translate",
+        "query-optimize",
+        "cost-report",
+      ]
+      for (const skillName of skills) {
+        const suggestions = SkillFollowups.get(skillName)
+        for (const s of suggestions) {
+          expect(s.skill).not.toBe(skillName)
+        }
+      }
+    })
+  })
+})