From 5f911dcc91551eb86f32622fcf6937e5f67bd55f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 27 Apr 2026 13:04:45 +0000
Subject: [PATCH] Generated skill nudges agent through cloud-readiness
 bootstrap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a Bootstrap section to the workflow SKILL.md that runs on first
invocation: verify the CLI is on PATH (install via npm link if not),
offer a SessionStart hook so cloud sessions self-install, and offer
to create a GitHub repo if the local repo has no remote. Steps 2
and 3 are nudges — agent asks first, doesn't act unilaterally.

Update scaffold-pipeline.md so generators preserve the Bootstrap
section verbatim during Phase 5 substitute, and so the final
next-steps message points users at the workflow skill for cloud /
publish setup.
---
 .../skills/exemplar-cli-workflow/SKILL.md     | 55 +++++++++++++++++++
 references/scaffold-pipeline.md               |  4 +-
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/examples/exemplar-cli/skills/exemplar-cli-workflow/SKILL.md b/examples/exemplar-cli/skills/exemplar-cli-workflow/SKILL.md
index 0291ae5..54f4d27 100644
--- a/examples/exemplar-cli/skills/exemplar-cli-workflow/SKILL.md
+++ b/examples/exemplar-cli/skills/exemplar-cli-workflow/SKILL.md
@@ -20,6 +20,61 @@ Wrap the (fictional) [Exemplar API](https://docs.exemplar.test/api/v1) via `exem
 - User asks to attach a file to an order
 - User asks the agent to demonstrate a pagination or idempotency workflow
 
+## Bootstrap
+
+Run this checklist the first time this skill is invoked in a session, before any CLI command. It's a no-op once the CLI is installed and the hook is in place, so it's safe to re-run.
+
+### 1. Ensure the CLI is on PATH (auto)
+
+```
+command -v exemplar-cli
+```
+
+If it exits non-zero, install from this repo:
+
+```
+cd <path-to-this-repo> && npm install && npm link
+```
+
+In Claude Code on the web (and other ephemeral cloud sessions), `node_modules` and global links don't persist — so this step runs every fresh session unless a SessionStart hook handles it (see step 2).
+
+### 2. Offer to add a SessionStart hook (nudge)
+
+Check whether `.claude/settings.json` in this repo already has a `SessionStart` hook that installs the CLI. If not, ask the user:
+
+> This CLI isn't auto-installed in fresh / cloud sessions. Want me to add a SessionStart hook to `.claude/settings.json` so it self-installs?
+
+If they say yes, add (or merge into) `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v exemplar-cli >/dev/null 2>&1 || (npm install && npm link)"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The guard (`command -v … || …`) keeps it a no-op when the CLI is already on PATH, so it only does work in fresh environments.
+
+### 3. Offer to publish the repo (nudge)
+
+Check whether the repo has a git remote (`git remote -v`). If empty, ask the user:
+
+> This CLI lives only on your machine. Want me to create a GitHub repo and push, so cloud sessions can clone it?
+
+Only act if they confirm. Use the GitHub MCP tools to create the repo, then `git remote add origin … && git push -u origin <branch>`.
+
+Skip this step entirely if the user has already declined it once in the session.
+
 ## Setup
 
 The CLI needs an API token. Either:
diff --git a/references/scaffold-pipeline.md b/references/scaffold-pipeline.md
index b598c68..2158f8d 100644
--- a/references/scaffold-pipeline.md
+++ b/references/scaffold-pipeline.md
@@ -221,6 +221,8 @@ For `scheme !== none`, include:
 
 Rewrite Triggers, Quick Reference table, Common Workflows. Preserve the YAML frontmatter shape (name, description, allowed-tools). The skill must mention every resource and the `knowledge/` directory.
 
+**Preserve the `## Bootstrap` section verbatim** — only swap `exemplar-cli` for the generated bin name. The three bootstrap steps (PATH check + install, SessionStart-hook nudge, publish nudge) are the contract that makes generated CLIs work in cloud sessions; don't drop or restructure them.
+
 ### `skills/<api-name>-cli-{auth,resources,knowledge}/SKILL.md`
 
 Light edit. Auth: update token storage notes. Resources: regenerate the resource × action table from the parsed registry. Knowledge: list the knowledge files extracted from docs.
@@ -327,4 +329,4 @@ End-of-scaffold summary should include:
 - Validation gate result: pass with N checks
 - Verification subagent result: pass with N items
 - Path to generated repo
-- Next steps: `cd <repo> && npm install && npm link && <bin> --help`
+- Next steps: `cd <repo> && npm install && npm link && <bin> --help`. Then load the workflow skill — it walks the user through a SessionStart hook (for cloud sessions) and an optional GitHub publish.