From 480835e5bf00cf351d78de9ff817eaac8c611033 Mon Sep 17 00:00:00 2001 From: stack72 Date: Mon, 13 Apr 2026 23:08:37 +0100 Subject: [PATCH] feat: add swamp-getting-started skill with interactive onboarding walkthrough MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a new skill that auto-triggers when Claude starts in a swamp repo with no models. Walks new users through a 5-step state machine: Goals → Create → Run → Inspect → Graduate. Key behaviors: - Asks users what they want to automate, then finds the right model type (local search → extension search → custom extension) - Pre-checks for existing models to skip onboarding on return visits - Early exit for experienced users who describe specific tasks - Teaches plan mode and review workflows in the graduation step - Contextual next-step suggestions tied to what the user actually built - Explicit guard against hallucinating CLI commands Also updates: - CLAUDE.md template to auto-invoke the skill in empty repos - BUNDLED_SKILLS to include the new skill in repo init/upgrade Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/swamp-getting-started/SKILL.md | 231 ++++++++++++++++++ .../evals/trigger_evals.json | 71 ++++++ .../references/tracks.md | 71 ++++++ src/domain/repo/repo_service.ts | 8 +- src/infrastructure/assets/skill_assets.ts | 8 + 5 files changed, 388 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/swamp-getting-started/SKILL.md create mode 100644 .claude/skills/swamp-getting-started/evals/trigger_evals.json create mode 100644 .claude/skills/swamp-getting-started/references/tracks.md diff --git a/.claude/skills/swamp-getting-started/SKILL.md b/.claude/skills/swamp-getting-started/SKILL.md new file mode 100644 index 00000000..c01d7e04 --- /dev/null +++ b/.claude/skills/swamp-getting-started/SKILL.md @@ -0,0 +1,231 @@ +--- +name: swamp-getting-started +description: > + Interactive getting-started walkthrough for new swamp users. Guides through + understanding the user's goals, creating and running a first model, + inspecting output, and choosing next steps. Uses a state-machine checklist + with verification at each step. + Triggers on "getting started", "get started", "new to swamp", "first time", + "tutorial", "walkthrough", "onboarding", "how do I start", "what do I do + first", "quickstart", "quick start", "hello world", "first model", "just + installed swamp", "show me how swamp works", "intro to swamp", "new user", + "set up swamp", "learn swamp". +--- + +# Getting Started with Swamp + +Interactive walkthrough for new users. This skill is a **state machine** — each +state gates the next. You MUST NOT advance to the next state until the current +state's **Verify** step passes. + +## State Machine + +``` +start → goals_understood → model_created → method_run + → output_inspected → graduated +``` + +**Core rule:** If any Verify fails, execute the On Failure action. Never skip a +state. Never reorder states. Each step validates before advancing. + +**Do not guess CLI commands.** If you are unsure whether a subcommand or flag +exists, run `swamp --help` to check before using it. Never invent +commands — only use what the CLI actually provides. + +## Before Starting + +**Pre-check:** Before presenting the walkthrough, run +`swamp model search --json`. If models already exist, the user does not need +onboarding. Skip the entire walkthrough and say: + +> You already have models set up. You're past the getting-started stage — just +> tell me what you'd like to work on and I'll use the right skill. + +Then stop. Do not proceed with the state machine. + +**If no models exist**, present the 5-step checklist (Goals → Create → Run → +Inspect → Graduate) so the user knows what to expect. Also tell the user: + +- They can ask you to **explain your plan** before you execute anything — you'll + research and present an approach for their approval before making changes +- They should **review what you propose** at each step — they're in control and + can steer the direction + +Then begin with State 1. + +## State 1: goals_understood + +Understand what the user wants to accomplish with swamp so the rest of the +walkthrough is tailored to their goals. + +**Gate:** None (first state). + +**Action:** Ask the user what they want to automate. Don't categorize by +implementation (shell vs cloud vs extension) — just ask them to describe their +goal in their own words. Examples: "check disk space on my servers", "manage AWS +EC2 instances", "monitor my API uptime", "deploy to Kubernetes". Let them know +they can skip the walkthrough if they already know swamp. + +**Early exit:** If the user's response indicates they already know swamp (e.g., +"I want to create a model for X", "set up a workflow", or describes a specific +task with swamp terminology), skip the rest of this walkthrough. Instead, +delegate directly to the appropriate skill (`swamp-model`, `swamp-workflow`, +`swamp-vault`, etc.) and proceed with their request. + +**Verify:** The user has described their goal. Find the right model type: + +1. Search local types: `swamp model type search --json` +2. If nothing local matches, search extensions: + `swamp extension search --json` +3. If an extension is found, pull it: `swamp extension pull ` +4. If nothing exists, offer to build a custom extension model using the + `swamp-extension-model` skill. Only use `command/shell` if the user's goal is + genuinely a one-off ad-hoc command (not wrapping a CLI tool or service) + +Store the user's goal description — use it to name models and tailor examples +throughout the remaining steps. + +**On Failure:** If the user is unsure, default to Track A (shell commands). It +works everywhere without credentials and demonstrates the full lifecycle. + +## State 2: model_created + +Create the user's first model, tailored to their stated goal. + +**Gate:** State 1 passed (goals understood, track chosen). + +**Action:** Follow the track-specific steps in +[references/tracks.md](references/tracks.md) to create the model. Use the user's +goal to pick a meaningful model name (e.g., "check disk space" → +`check-disk-space`). + +The general pattern across all tracks: + +1. Find or install the right model type +2. Create the model with `swamp model create --json` +3. Edit the generated YAML to configure arguments matching the user's goal + +### Verify (all tracks) + +```bash +swamp model validate --json +``` + +Validation must pass with no errors. Show any warnings to the user. + +**On Failure:** Read the validation errors. Common fixes: + +- Missing required arguments → edit the model YAML to add them +- Invalid argument values → check the type schema with + `swamp model type describe --json` +- File not found → verify path from `swamp model get --json` + +For detailed model guidance, see the `swamp-model` skill. + +## State 3: method_run + +Execute a method on the model to show swamp in action. + +**Gate:** State 2 passed (model validates). + +**Action:** Tell the user what's about to happen, then run: + +```bash +swamp model method run +``` + +Where `` is: + +- Track A: `execute` +- Track B: the appropriate read-only method first (e.g., `sync`, `get`) — prefer + non-destructive methods for a first run +- Track C: depends on the extension type + +**Verify:** The command completes with a `succeeded` status. + +**On Failure:** + +- **Command failed**: Read the error output and suggest specific fixes +- **Missing secrets**: Guide toward vault setup (delegate to `swamp-vault` + skill) +- **Permission denied**: Check the command exists and is executable +- **Timeout**: Suggest a simpler command for the first run + +After fixing, re-run the method and re-verify. + +## State 4: output_inspected + +Show the user what swamp captured and where data lives. + +**Gate:** State 3 passed (method succeeded). + +**Action:** + +```bash +swamp model output get --json +``` + +**Verify:** The command returns output data. Present the results to the user, +highlighting: + +- **Status**: succeeded +- **Data artifacts**: what was captured (stdout, resource attributes, etc.) +- **Where it lives**: the datastore path for versioned data +- **How to reference it**: the CEL expression path for wiring to other models + +Explain that swamp versions every method run's output, and show the CEL +expression pattern for referencing it from other models: +`${{ data.latest("", "").attributes. }}` + +**On Failure:** If no output is found, check the method run logs: + +```bash +swamp model output search --json +``` + +Look for failed runs and report the error. + +## State 5: graduated + +Celebrate success and show the user where to go next based on their stated +goals. + +**Gate:** State 4 passed (output inspected). + +**Action:** No verification needed. Summarize what they accomplished (model +created, method run, output captured). Then: + +1. Remind the user about working styles they can use going forward: + - **Plan mode**: Ask Claude to plan before acting — it will research the + codebase and present an approach for approval before making changes + - **Review changes**: They can always ask to see what Claude will do before + it does it, and steer the direction at any point + - **Iterate**: They can ask Claude to adjust, undo, or try a different + approach at any time + +2. Suggest 2-3 concrete next steps based on their track and goal — not generic + skill names, but specific actions tied to what they just built (e.g., "store + your AWS credentials in a vault" not "help me create a vault"). Ask which + direction they want to go, then delegate to the appropriate skill with full + context about what they've already built. + +## Delegation + +When the user picks a next step (or asks something outside the walkthrough +scope), delegate to the appropriate skill with context about what they built: + +- User wants another model or to edit the one they made → `swamp-model` +- User wants to chain models together → `swamp-workflow` +- User wants to secure credentials → `swamp-vault` +- User wants to inspect or query their data → `swamp-data-query` +- User wants to build a typed model from scratch → `swamp-extension-model` +- User wants to share their work → `swamp-extension-publish` +- Something is broken → `swamp-troubleshooting` + +Always pass along the user's original goal and what they built so the next skill +doesn't start from zero. + +## References + +See [references/tracks.md](references/tracks.md) for the model type resolution +flow, credential setup, method selection, and CEL reference patterns. diff --git a/.claude/skills/swamp-getting-started/evals/trigger_evals.json b/.claude/skills/swamp-getting-started/evals/trigger_evals.json new file mode 100644 index 00000000..0143a1f7 --- /dev/null +++ b/.claude/skills/swamp-getting-started/evals/trigger_evals.json @@ -0,0 +1,71 @@ +[ + { + "query": "I'm new to swamp, help me get started", + "should_trigger": true + }, + { + "query": "How do I start using swamp?", + "should_trigger": true + }, + { + "query": "Getting started with swamp", + "should_trigger": true + }, + { + "query": "Walk me through swamp for the first time", + "should_trigger": true + }, + { + "query": "Just installed swamp, what do I do?", + "should_trigger": true + }, + { + "query": "Show me a hello world in swamp", + "should_trigger": true + }, + { + "query": "Swamp tutorial", + "should_trigger": true + }, + { + "query": "Swamp quickstart", + "should_trigger": true + }, + { + "query": "I want to learn swamp", + "should_trigger": true + }, + { + "query": "What do I do first with swamp?", + "should_trigger": true + }, + { + "query": "I'm a new user, where do I begin?", + "should_trigger": true + }, + { + "query": "Create a model for me", + "should_trigger": false, + "note": "Model creation -> swamp-model" + }, + { + "query": "How do I publish my extension?", + "should_trigger": false, + "note": "Publishing -> swamp-extension-publish" + }, + { + "query": "Create a vault for my AWS secrets", + "should_trigger": false, + "note": "Vault management -> swamp-vault" + }, + { + "query": "Run my workflow", + "should_trigger": false, + "note": "Workflow execution -> swamp-workflow" + }, + { + "query": "Initialize a swamp repo", + "should_trigger": false, + "note": "Repo init -> swamp-repo" + } +] diff --git a/.claude/skills/swamp-getting-started/references/tracks.md b/.claude/skills/swamp-getting-started/references/tracks.md new file mode 100644 index 00000000..53941cf2 --- /dev/null +++ b/.claude/skills/swamp-getting-started/references/tracks.md @@ -0,0 +1,71 @@ +# Model Type Resolution + +How to find the right model type based on the user's goal. Follow the resolution +steps in order — stop as soon as a match is found. + +## Step 1: Search Local Types + +```bash +swamp model type search --json +``` + +If a matching type is found, use it. Run +`swamp model type describe --json` to understand required arguments. + +## Step 2: Search Extensions + +If no local type matches: + +```bash +swamp extension search --json +``` + +The search results include name, description, and content types. There is no +`extension info` command — the search output is the only way to evaluate +extensions before pulling. Present the results and let the user pick one: + +```bash +swamp extension pull @collective/extension-name +swamp model type search --json +``` + +After pulling, use `swamp model type describe --json` to inspect the +schema and available methods. + +## Step 3: Build a Custom Extension + +If nothing matches locally or in the registry, offer to build a custom extension +model using the `swamp-extension-model` skill. This creates a typed model with +proper Zod schemas for the service the user wants to automate. + +Only use `command/shell` if the user's goal is genuinely a one-off ad-hoc +command (e.g., "check my disk space right now") — never for wrapping CLI tools +or building integrations. This aligns with the CLAUDE.md rule: _"The +`command/shell` model is ONLY for ad-hoc one-off shell commands, NEVER for +wrapping CLI tools or building integrations."_ + +## Credential Setup + +If the chosen model type requires credentials (cloud services, APIs, etc.), set +up a vault before configuring the model. Use the `swamp-vault` skill: + +1. Create a vault: `swamp vault create local_encryption my-secrets --json` +2. Store credentials: `swamp vault put my-secrets KEY=VALUE --json` +3. Reference in model YAML: `${{ vault.get("my-secrets", "KEY") }}` + +## Method Selection + +For a first run, prefer read-only methods that don't create or modify resources: + +- `execute` — for shell models +- `sync` or `get` — for typed models (discovers/reads existing resources) + +Avoid `create`, `update`, or `delete` for the first run. + +## CEL Reference Path + +After a successful run, show the user how to reference the output: + +``` +${{ data.latest("", "").attributes. }} +``` diff --git a/src/domain/repo/repo_service.ts b/src/domain/repo/repo_service.ts index ce88382b..b5fae010 100644 --- a/src/domain/repo/repo_service.ts +++ b/src/domain/repo/repo_service.ts @@ -610,7 +610,13 @@ essential context for working with this repository. ## Getting Started -Always start by using the \`swamp-model\` skill to work with swamp models. +**IMPORTANT:** At the start of every conversation, check if the \`models/\` +directory contains any model YAML files. If it is empty (no models exist yet), +you MUST immediately invoke the \`swamp-getting-started\` skill before doing +anything else. This walks new users through an interactive onboarding tutorial. + +If models already exist, start by using the \`swamp-model\` skill to work with +swamp models. ## Commands diff --git a/src/infrastructure/assets/skill_assets.ts b/src/infrastructure/assets/skill_assets.ts index b38d89d3..e1f8f91c 100644 --- a/src/infrastructure/assets/skill_assets.ts +++ b/src/infrastructure/assets/skill_assets.ts @@ -278,6 +278,14 @@ const BUNDLED_SKILLS: SkillInfo[] = [ relativePath: "swamp-troubleshooting/references/tracing.md", name: "swamp-troubleshooting", }, + { + relativePath: "swamp-getting-started/SKILL.md", + name: "swamp-getting-started", + }, + { + relativePath: "swamp-getting-started/references/tracks.md", + name: "swamp-getting-started", + }, ]; /**