dflow-sdd-ddd 0.12.0 → 0.13.0

package/docs/using-with-claude-code.en.md

@@ -213,18 +213,23 @@ re-projects adapters from the **new registry**, but an existing
 adapters" is not the same as "migrating the canonical guide." Re-project with
 the **same dflow CLI version** to avoid a registry / guide version mismatch.
 
-### Optional Skill Adapter (Restore Natural-Language Auto-Trigger)
+### Skill Adapter (Natural-Language Auto-Trigger, Installed by Default)
 
 Command adapters give you a `/` menu entry, but they **do not auto-trigger** —
-you have to invoke the command yourself. If you want to restore the "say 'I want
-to add a feature' and it shows up automatically" experience, run this in an
-initialized project:
+you have to invoke the command yourself. Auto-trigger comes from the
+project-level skill, and it now installs **by default**: `dflow init` installs
+it when AI tools were selected (interactive runs ask one question — press Enter
+to install; non-interactive runs never read an extra answer and install by
+default), and `dflow configure-agents` asks the same question for newly
+selected tools that have no skill yet. If you answered `n` back then, or want
+to force-regenerate (for example to refresh after upgrading Dflow), run:
 
 ```bash
 dflow configure-agents --skills
 ```
 
-After you select Claude Code, Dflow generates a thin skill:
+After you select Claude Code (in init or configure-agents), Dflow generates a
+thin skill:
 
 - `.claude/skills/dflow/SKILL.md`
 
@@ -233,8 +238,8 @@ This skill does not copy workflow steps; its body points to the canonical
 `dflow/specs/shared/dflow-workflows/` (vendored bundle with executable step
 definitions).
 
-The same edition-neutral skill source is now also projected by `--skills` as a
-project-level skill for Codex (`.agents/skills/dflow/SKILL.md`) and GitHub Copilot
+The same edition-neutral skill source is also projected as a project-level
+skill for Codex (`.agents/skills/dflow/SKILL.md`) and GitHub Copilot
 (`.github/skills/dflow/SKILL.md`); all three follow the same cross-tool
 agentskills.io standard.
 
@@ -249,14 +254,14 @@ Its behavior:
   judges the intent, **suggests the matching `/dflow:` command, and waits for
   your confirmation** before proceeding.
 
-**The four combinations** (command adapters and the skill are each independently
-opt-in):
+**The four combinations** (command adapters stay opt-in; the skill installs by
+default — answer `n` at init to skip it, or delete it later):
 
 | Installed | Entry behavior |
 |---|---|
-| Neither | Root shim only (CLAUDE.md points to the guide); no `/` menu, no auto-trigger |
+| Neither (skill skipped with `n`, no adapters) | Root shim only (CLAUDE.md points to the guide); no `/` menu, no auto-trigger |
 | Command adapters only | `/dflow:*` appears in the `/` menu; no natural-language auto-trigger |
-| Skill only | Natural-language auto-trigger (suggest-and-wait); no `/` menu |
+| Skill only (init's default outcome) | Natural-language auto-trigger (suggest-and-wait); no `/` menu |
 | Both | `/` menu + natural-language safety net **may coexist** |
 
 **Both may coexist with no mutex needed** (validated in a real Claude Code
@@ -307,11 +312,13 @@ spec locations, or SDD constraints to `CLAUDE.md`, those belong in
 `dflow/specs/shared/AI-AGENT-GUIDE.md` instead. The shim stays small so
 that other tools' shims don't drift away from it.
 
-**`/dflow:*` is not a Claude Code Skill installation.** `init` does not
-install anything into Claude Code's skill system. Without command adapters,
-Dflow names are text triggers the AI recognizes from the workflow table. After
-you run `dflow configure-agents --command-adapters`, the added files are thin
-command wrappers, not a second workflow definition.
+**The `/dflow:*` command names are not the skill.** `init` does install the
+auto-trigger skill into Claude Code's skill system by default
+(`.claude/skills/dflow/SKILL.md`; answer `n` at the skill question to skip),
+but the `/dflow:*` **command names** themselves are not a skill. Without
+command adapters, those names are text triggers the AI recognizes from the
+workflow table. After you run `dflow configure-agents --command-adapters`, the
+added files are thin command wrappers, not a second workflow definition.
 
 **Choose either legacy Claude skills or the installed adapter.** If the
 project still has legacy `.claude/skills/sdd-ddd-*` skills, choose either

package/docs/using-with-claude-code.md

@@ -187,16 +187,19 @@ git rm --cached -r .claude/commands/dflow/
 重投影；但既有 `dflow/specs/shared/AI-AGENT-GUIDE.md` **不會**被覆寫——「重投影 adapter」不等於
 「升級 canonical guide」。請以**相同的 dflow CLI 版本**重投影，避免 registry 與 guide 版本錯位。
 
-### 選配 Skill Adapter（找回自然語言自動觸發）
+### Skill Adapter（自然語言自動觸發，init 預設安裝）
 
-Command adapter 提供 `/` 選單入口，但**不會自動觸發**——你得主動打命令。若想找回
-「講『我要加一個功能』就自動現身」的體驗，可在已初始化的專案中執行：
+Command adapter 提供 `/` 選單入口，但**不會自動觸發**——你得主動打命令。自動觸發
+來自 project-level skill，而它現在是**預設安裝**：`dflow init` 有選 AI 工具時就會裝
+（互動模式問一題、直接按 Enter = 裝；非互動不多讀答案、直接預設裝），
+`dflow configure-agents` 對「新選且尚無 skill」的工具也補問同一題。若當時答 `n`
+略過、或想強制重生成（例如升級 Dflow 後刷新），執行：
 
 ```bash
 dflow configure-agents --skills
 ```
 
-選擇 Claude Code 後，Dflow 會產生一份薄 skill：
+選擇 Claude Code 後（init 或 configure-agents 皆同），Dflow 會產生一份薄 skill：
 
 - `.claude/skills/dflow/SKILL.md`
 
@@ -204,7 +207,7 @@ dflow configure-agents --skills
 `dflow/specs/shared/AI-AGENT-GUIDE.md`（命令登錄表與路由規則）以及
 `dflow/specs/shared/dflow-workflows/`（含可執行步驟定義的 vendored bundle）。
 
-同一份 edition-neutral skill source，現在也會由 `--skills` 為 Codex
+同一份 edition-neutral skill source，也會為 Codex
 （`.agents/skills/dflow/SKILL.md`）與 GitHub Copilot（`.github/skills/dflow/SKILL.md`）
 投影 project-level skill，三家沿用相同的跨工具 agentskills.io 標準。
 
@@ -216,14 +219,15 @@ dflow configure-agents --skills
 - 由自然語言觸發時，**不會直接進 workflow**：它會判斷意圖、**建議對應的 `/dflow:`
   命令並等待你確認**，再進入流程。
 
-**四種組合**（command adapter 與 skill 各自獨立 opt-in）：
+**四種組合**（command adapter 維持 opt-in；skill 預設安裝，可在 init 答 `n`
+略過或事後刪除）：
 
 | 安裝組合 | 入口行為 |
 |---|---|
-| 都不裝 | 只有根目錄 shim（CLAUDE.md 指向 guide）；無 `/` 選單、無自動觸發 |
-| 只裝 command adapters | `/dflow:*` 出現在 `/` 選單；無自然語言自動觸發 |
-| 只裝 skill | 自然語言自動觸發（suggest-and-wait）；無 `/` 選單 |
-| 兩者都裝 | `/` 選單 + 自然語言 safety net **可共存** |
+| 都沒有（skill 題答 `n`、未裝 adapters） | 只有根目錄 shim（CLAUDE.md 指向 guide）；無 `/` 選單、無自動觸發 |
+| 只有 command adapters | `/dflow:*` 出現在 `/` 選單；無自然語言自動觸發 |
+| 只有 skill（init 預設結果） | 自然語言自動觸發（suggest-and-wait）；無 `/` 選單 |
+| 兩者都有 | `/` 選單 + 自然語言 safety net **可共存** |
 
 **兩者可共存、無需互斥**（已在真實 Claude Code 環境驗證）：skill 名稱 `dflow` 與
 command adapter 的 `dflow:<id>` 不撞名，明確命令各自精準載入、不會雙觸發；skill 當
@@ -266,10 +270,12 @@ SDD 約束加入 `CLAUDE.md`，這些內容應該放到
 `dflow/specs/shared/AI-AGENT-GUIDE.md`。shim 保持精簡，其他工具的 shim 才不會
 與它產生漂移（drift）。
 
-**`/dflow:*` 不是安裝 Claude Code Skill。** `init` 不會在 Claude Code 的
-skill 系統中安裝任何東西。未安裝 command adapters 時，Dflow 名稱只是 AI 從
-workflow 表識別的文字 trigger；安裝 `dflow configure-agents --command-adapters`
-後，新增的是薄 command wrapper，不是 workflow 的第二份定義。
+**`/dflow:*` 命令名不等於 skill。** init 預設會在 Claude Code 的 skill 系統
+裝一份自動觸發 skill（`.claude/skills/dflow/SKILL.md`，skill 題答 `n` 可略過），
+但 `/dflow:*` 這組**命令名**本身不是 skill——未安裝 command adapters 時，它們
+只是 AI 從 workflow 表識別的文字 trigger；安裝
+`dflow configure-agents --command-adapters` 後，新增的是薄 command wrapper，
+不是 workflow 的第二份定義。
 
 **legacy Claude skill 與 installed adapter 擇一。** 如果專案仍保留舊的
 `.claude/skills/sdd-ddd-*` skill，請在 legacy skill 與 `--command-adapters`

package/docs/using-with-codex.en.md

@@ -179,8 +179,9 @@ triggers only. It does not create Codex command files. Codex v1 has no Dflow
 command-file adapter equivalent to Claude `.claude/commands` or Copilot
 `.github/prompts`.
 
-**Auto-trigger skills come from `--skills`, not `--command-adapters`.** See
-"Codex Behavior With Optional Skills" below.
+**Auto-trigger skills come from the skill install (init's default, or
+`--skills`), not `--command-adapters`.** See "Codex Behavior With Skills"
+below.
 
 When you select `AGENTS.md - Codex / Copilot coding agent` in
 `--command-adapters` mode, Dflow writes a trigger list generated from the
@@ -219,10 +220,16 @@ Both snippets appear only on a marker conflict. A clean custom `AGENTS.md` with
 no conflicting markers does not produce a snippet at all — Dflow just appends the
 adjacent marked block in place.
 
-### Codex Behavior With Optional Skills (Auto-Trigger)
+### Codex Behavior With Skills (Auto-Trigger, Installed by Default)
 
-`dflow configure-agents --skills` projects a thin, tool-neutral skill to
-`.agents/skills/dflow/SKILL.md` — Codex's project-level skill path. This gives
+Dflow projects a thin, tool-neutral skill to
+`.agents/skills/dflow/SKILL.md` — Codex's project-level skill path. The skill
+now installs **by default**: `dflow init` installs it when Codex was selected
+(interactive runs ask one default-yes question; non-interactive runs install
+without reading extra stdin), and `dflow configure-agents` asks the same
+question when Codex is newly selected without a skill;
+`dflow configure-agents --skills` backfills a previously skipped skill or
+force-regenerates it. This gives
 Codex **natural-language auto-trigger on par with Claude Code**: when you
 describe intent like "help me start a new feature", Codex can judge relevance
 from the skill's `description`, suggest the matching `dflow:<id>` workflow, and
@@ -320,9 +327,9 @@ workflow by reading `AI-AGENT-GUIDE.md`.
 Codex only strengthens text-trigger guidance in marked blocks inside
 `AGENTS.md`; fallback merge snippets are created only on marker conflicts. Do
 not expect Codex-specific **command** files under `.claude/commands` or
-`.github/prompts`. (Auto-trigger **skills** are separate: `--skills` projects
-one to `.agents/skills/dflow/SKILL.md`, see "Codex Behavior With Optional
-Skills" above.)
+`.github/prompts`. (Auto-trigger **skills** are separate: init installs one to
+`.agents/skills/dflow/SKILL.md` by default and `--skills` regenerates it, see
+"Codex Behavior With Skills" above.)
 
 **Do not confuse Codex `/init` with Dflow `init`.** Codex `/init` creates a
 generic `AGENTS.md` scaffold for Codex. Dflow setup is `dflow init` (or

package/docs/using-with-codex.md

@@ -158,8 +158,8 @@ guide 中記為 `/dflow:*`）。
 Codex 命令檔。Codex v1 沒有與 Claude `.claude/commands` 或 Copilot `.github/prompts`
 對等的 Dflow command-file adapter。
 
-**自動觸發 skill 走的是 `--skills`（非 `--command-adapters`）。** 見下方
-〈選配 Skill 的 Codex 行為〉。
+**自動觸發 skill 走的是 skill 安裝（init 預設、或 `--skills`），非
+`--command-adapters`。** 見下方〈Skill 的 Codex 行為〉。
 
 當你在 `--command-adapters` 模式下選擇 `AGENTS.md - Codex / Copilot coding agent`
 時，Dflow 會把從 canonical command registry 產生的 trigger 清單寫進 `AGENTS.md`。
@@ -189,10 +189,13 @@ marker」分成兩種小抄：
 兩種小抄都只在 marker conflict 時出現。乾淨、沒有 marker 衝突的自訂 `AGENTS.md` 不會
 產生任何小抄——Dflow 會直接把相鄰 marked block append 進去。
 
-### 選配 Skill 的 Codex 行為（自動觸發）
+### Skill 的 Codex 行為（自動觸發，init 預設安裝）
 
-`dflow configure-agents --skills` 會把一份精簡、工具中立的 skill 投影到
-`.agents/skills/dflow/SKILL.md`——Codex 的專案層 skill 路徑。這讓 Codex 取得與
+Dflow 會把一份精簡、工具中立的 skill 投影到
+`.agents/skills/dflow/SKILL.md`——Codex 的專案層 skill 路徑。這份 skill 現在
+**預設安裝**：`dflow init` 有選 Codex 就裝（互動問一題預設 Y、非互動直接裝）、
+`dflow configure-agents` 對新選且尚無 skill 的 Codex 也補問；
+`dflow configure-agents --skills` 用於補裝先前略過的、或強制重生成。這讓 Codex 取得與
 Claude Code **對等的自然語言自動觸發**：你用「help me start a new feature」這類描述
 時，Codex 可依該 skill 的 `description` 自動判斷是否相關，建議對應的 `dflow:<id>`
 workflow，而不必每次都記得手打命令。
@@ -272,8 +275,8 @@ canonical `/dflow:<id>` workflow。
 **Codex 不產生命令檔。** 即使使用 `--command-adapters`，Codex 也只強化
 `AGENTS.md` 中 marked block 的文字 trigger 說明；只有 marker conflict 才會產生
 fallback merge snippet。不要期待 `.claude/commands` 或 `.github/prompts` 形式的
-Codex 專屬**命令**檔。（自動觸發 **skill** 是另一回事，由 `--skills` 投影到
-`.agents/skills/dflow/SKILL.md`，見上方〈選配 Skill 的 Codex 行為〉。）
+Codex 專屬**命令**檔。（自動觸發 **skill** 是另一回事，init 預設安裝、`--skills`
+可重生成，路徑 `.agents/skills/dflow/SKILL.md`，見上方〈Skill 的 Codex 行為〉。）
 
 **不要混淆 Codex `/init` 與 Dflow `init`。** Codex `/init` 為 Codex 建立
 通用的 `AGENTS.md` scaffold。Dflow 的設定是 `dflow init`（或免安裝路徑的

package/docs/using-with-github-copilot.en.md

@@ -142,11 +142,16 @@ steps. Note the command syntax uses the **hyphen** `/dflow-<id>`, not the
 canonical **colon** `/dflow:<id>` — the colon form is Claude / Codex's command
 syntax and in Copilot can only be a text reference, never typed as a command.
 
-### The `--skills` Flag and Skill Triggering on Copilot
+### Skill Triggering on Copilot (Installed by Default)
 
-`dflow configure-agents --skills` projects the same tool-neutral thin skill for
+Dflow projects the same tool-neutral thin skill for
 **Claude Code, Codex, and GitHub Copilot**, each at its own project-level skill
-path; Copilot's is `.github/skills/dflow/SKILL.md`. Testing (2026-06-05) confirmed
+path; Copilot's is `.github/skills/dflow/SKILL.md`. The skill now installs **by
+default**: `dflow init` installs it when Copilot was selected (interactive runs
+ask one default-yes question; non-interactive runs install without reading
+extra stdin), `dflow configure-agents` asks the same question when Copilot is
+newly selected without a skill, and `dflow configure-agents --skills` backfills
+or force-regenerates it. Testing (2026-06-05) confirmed
 Copilot discovers and runs the skill from its own native `.github/skills/` path
 (it still works with the cross-read `.claude`/`.agents` paths removed); the
 trigger differs by surface — **VS Code Chat auto-triggers on natural language**,

package/docs/using-with-github-copilot.md

@@ -137,11 +137,14 @@ dflow configure-agents --command-adapters
 **連字號** `/dflow-<id>`，不是 canonical 的**冒號** `/dflow:<id>`——後者是
 Claude / Codex 的命令寫法，在 Copilot 只能當文字稱呼、不能當命令輸入。
 
-### `--skills` flag 與 Copilot 的 skill 觸發
+### Copilot 的 skill 觸發（init 預設安裝）
 
-`dflow configure-agents --skills` 會為 **Claude Code、Codex 與 GitHub Copilot**
+Dflow 會為 **Claude Code、Codex 與 GitHub Copilot**
 各自投影同一份工具中立的 thin skill 到它們的 project-level skill 路徑；Copilot 的是
-`.github/skills/dflow/SKILL.md`。實測（2026-06-05）確認 Copilot 會從**自己原生的
+`.github/skills/dflow/SKILL.md`。這份 skill 現在**預設安裝**：`dflow init` 有選
+Copilot 就裝（互動問一題預設 Y、非互動直接裝）、`dflow configure-agents` 對新選且
+尚無 skill 的 Copilot 也補問；`dflow configure-agents --skills` 用於補裝或強制
+重生成。實測（2026-06-05）確認 Copilot 會從**自己原生的
 `.github/skills/`** 探索並運作（即使移除 `.claude`/`.agents` 的跨讀路徑也成立），
 觸發方式依介面而異——**VS Code Chat 自然語言自動觸發**、**Copilot CLI 需打 `/dflow`
 手動喚起**（細節見上方介面 A / B）。

package/lib/init.js

@@ -250,6 +250,14 @@ async function runInit(options = {}) {
 
     const detection = await detectProjectSignals(cwd);
     const answers = await promptForAnswers(rl, stdout, stderr, detection);
+    // PROPOSAL-074: skill question sits after the AI-agents question and before the
+    // preview; asked only when a skill-capable agent was selected, and only on TTY.
+    answers.skills = await resolveSkillInstall(
+      rl,
+      stdout,
+      Boolean(stdin.isTTY && stdout.isTTY),
+      answers.aiAgents.some((agent) => SKILL_ADAPTER_TARGETS[agent])
+    );
     const plan = await buildFilePlan(cwd, answers);
     const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection), ...(plan.warnings || []), ...(plan.bundleWarnings || [])];
 
@@ -268,7 +276,7 @@ async function runInit(options = {}) {
     result.warnings.push(...collectUnresolvedPlaceholderWarnings(plan, result.created));
 
     printResultReport(stdout, result, plan.deferred);
-    printNextSteps(stdout);
+    printNextSteps(stdout, answers.skills);
     return 0;
   } catch (error) {
     if (rl) {
@@ -331,11 +339,40 @@ async function runConfigureAgents(options = {}) {
       throw new UserAbort('No AI agents selected. Nothing changed.');
     }
 
+    // PROPOSAL-074 (OQ2 branch b): without --skills, a selected agent that has no
+    // project-level skill yet gets the same default-yes install contract as init
+    // (TTY asks, non-TTY installs without reading stdin). Agents whose skill file
+    // already exists — Dflow-generated or user-owned — never re-ask and are NOT
+    // regenerated (skillAgents carries only the missing ones); explicit --skills
+    // keeps its original regenerate-all meaning.
+    let skillAgents = [];
+    if (options.skills) {
+      skillAgents = aiAgents;
+    } else {
+      const missingSkillAgents = [];
+      for (const agent of aiAgents) {
+        const target = SKILL_ADAPTER_TARGETS[agent];
+        if (target && !(await pathExists(path.join(cwd, target.relativePath)))) {
+          missingSkillAgents.push(agent);
+        }
+      }
+      const install = await resolveSkillInstall(
+        rl,
+        stdout,
+        Boolean(stdin.isTTY && stdout.isTTY),
+        missingSkillAgents.length > 0
+      );
+      if (install) {
+        skillAgents = missingSkillAgents;
+      }
+    }
+
     const plan = await buildConfigureAgentsPlan(cwd, {
       ...projectContext,
       aiAgents,
       commandAdapters: Boolean(options.commandAdapters),
-      skills: Boolean(options.skills)
+      skills: Boolean(options.skills),
+      skillAgents
     });
 
     const warnings = plan.warnings || [];
@@ -355,7 +392,7 @@ async function runConfigureAgents(options = {}) {
 
     printResultReport(stdout, result, plan.deferred);
     const usedSnippetFallback = plan.items.some((item) => item.snippetFallback);
-    printConfigureAgentsNextSteps(stdout, Boolean(options.commandAdapters), usedSnippetFallback);
+    printConfigureAgentsNextSteps(stdout, Boolean(options.commandAdapters), usedSnippetFallback, skillAgents.length > 0);
     return 0;
   } catch (error) {
     if (rl) {
@@ -978,6 +1015,38 @@ async function askConfirmation(rl, prompt) {
   return answer === 'y' || answer === 'yes';
 }
 
+// PROPOSAL-074: dedicated default-yes contract for the skill-install question.
+// askConfirmation treats blank as false (final-confirmation semantics), so reusing
+// it under a `(Y/n)` prompt would invert the advertised default.
+async function askYesNoDefaultYes(rl, prompt) {
+  const answer = (await askLine(rl, prompt)).trim().toLowerCase();
+  return answer === '' || answer === 'y' || answer === 'yes';
+}
+
+// PROPOSAL-074: the project-level skill installs by default. Ask only on an
+// interactive terminal; a non-TTY run never consumes a stdin slot — existing piped
+// answer sequences end with the final confirmation `y`, and a new question before
+// it would swallow that `y` and turn the run into a silent no-op abort — so
+// non-TTY installs by default without reading stdin.
+async function resolveSkillInstall(rl, stdout, interactive, hasSkillTargets) {
+  if (!hasSkillTargets) {
+    return false;
+  }
+
+  if (!interactive) {
+    return true;
+  }
+
+  const install = await askYesNoDefaultYes(
+    rl,
+    '\nInstall the project-level Dflow skill for natural-language auto-trigger? (Y/n) '
+  );
+  if (!install) {
+    stdout.write('Skipped the project-level skill; add it later with `dflow configure-agents --skills`.\n');
+  }
+  return install;
+}
+
 function parseSelectAnswer(answer, options, defaultKey) {
   const trimmed = answer.trim();
   if (!trimmed && defaultKey) {
@@ -1124,6 +1193,11 @@ async function buildFilePlan(cwd, answers) {
 
   await finalizePlanItems(cwd, items);
 
+  // PROPOSAL-074: init projects the project-level skill by default; answers.skills
+  // carries the Q-flow / non-TTY resolution from runInit (absent = false, which
+  // keeps buildFilePlan backward-compatible for direct callers).
+  await addSkillAdapterItems(cwd, items, answers.aiAgents, answers.skills, warnings);
+
   // Always project the workflow bundle (required for /dflow:* workflows to be reachable).
   const bundleWarnings = [];
   await addWorkflowBundleItems(cwd, items, bundleWarnings, answers.edition);
@@ -1172,7 +1246,11 @@ async function buildConfigureAgentsPlan(cwd, answers) {
     await addLegacyCommandAdapterCleanupItems(cwd, items, answers.aiAgents, warnings);
   }
 
-  await addSkillAdapterItems(cwd, items, answers.aiAgents, answers.skills, warnings);
+  // PROPOSAL-074: skillAgents is the projection subset — all selected agents under
+  // --skills, only the missing ones on a flagless default install (existing skills
+  // are never regenerated without the flag).
+  const skillAgents = answers.skillAgents || (answers.skills ? answers.aiAgents : []);
+  await addSkillAdapterItems(cwd, items, skillAgents, skillAgents.length > 0, warnings);
 
   // Project the workflow bundle on configure-agents too, so pre-039 projects (no bundle)
   // and edition-switch repairs get the runtime references/templates reachable. The function
@@ -2991,7 +3069,12 @@ function printResultReport(stdout, result, deferred) {
   }
 }
 
-function printNextSteps(stdout) {
+// PROPOSAL-074 / PROPOSAL-037: generated skill files are Dflow-managed derivatives;
+// the recommended default is gitignore + re-project after clone.
+const SKILL_VERSION_CONTROL_STEP = '- Project-level skill files (.claude/skills/, .agents/skills/, .github/skills/) are Dflow-managed derivatives: the recommended default is to gitignore them and re-run `dflow configure-agents --skills` after cloning; committing them also works if the team prefers.\n';
+
+function printNextSteps(stdout, skillsInstalled = false) {
+  const skillStep = skillsInstalled ? SKILL_VERSION_CONTROL_STEP : '';
   stdout.write(`
 Dflow init complete.
 
@@ -3000,10 +3083,10 @@ Recommended next steps:
 - For brownfield changes, use the Dflow modify-existing workflow when it becomes available as a CLI command.
 - Before generating more specs, make sure dflow/specs/shared/_conventions.md has the correct Prose Language section.
 - For stack-specific examples (.NET, Java/Spring, Node/TypeScript, Python, Go, PHP/Laravel), see docs/examples-by-stack.md in the Dflow repo.
-`);
+${skillStep}`);
 }
 
-function printConfigureAgentsNextSteps(stdout, commandAdapters = false, snippetFallback = false) {
+function printConfigureAgentsNextSteps(stdout, commandAdapters = false, snippetFallback = false, skillsInstalled = false) {
   const commandAdapterStep = commandAdapters
     ? '- Command adapters use tool-specific invocation names: Claude Code `/dflow:<id>`; GitHub Copilot prompt menu `/dflow-<id>` or canonical `/dflow:<id>` as text; Codex CLI plain text without a slash, such as `dflow:status`. Canonical `/dflow:*` names remain defined in dflow/specs/shared/AI-AGENT-GUIDE.md. If upgrading from Dflow 0.5.0, stale `.claude/commands/dflow/dflow-*.md` files generated by 0.5.0 are detected and listed for removal in the confirmation preview, so Claude Code does not show both old and new command names; edited or non-Dflow files are kept with a warning.\n'
     : '';
@@ -3015,13 +3098,15 @@ function printConfigureAgentsNextSteps(stdout, commandAdapters = false, snippetF
     ? '- A merge snippet was written because an existing agent file had conflicting Dflow markers; review it, fix or remove the stray markers, then merge the Dflow block into that file (or re-run to let Dflow manage it).\n'
     : '';
 
+  const skillStep = skillsInstalled ? SKILL_VERSION_CONTROL_STEP : '';
+
   stdout.write(`
 Dflow AI agent configuration complete.
 
 Recommended next steps:
 - Keep AI-agent-specific root files small.
 - Put durable workflow changes in dflow/specs/shared/AI-AGENT-GUIDE.md.
-${snippetStep}${commandAdapterStep}`);
+${snippetStep}${skillStep}${commandAdapterStep}`);
 }
 
 function printList(stdout, values) {