Unsupervisedcom · nhorton · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -138,12 +138,13 @@ uv run pytest           # Run tests
 ### 1. Plugin Installation
 Users install the DeepWork plugin for their AI agent CLI:
 ```
-claude plugin marketplace add Unsupervisedcom/deepwork
-claude plugin install deepwork@deepwork-plugins
+claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins && claude "/deepwork:new_user"
 ```
 The plugin provides:
 - `/deepwork` skill for invoking workflows
 - `/review` and `/configure_reviews` skills for automated reviews
+- `/new_user` skill for guided onboarding
+- `/record` skill for "watch and learn" workflow creation
 - MCP server configuration (`uvx deepwork serve`)
 - Hooks for workflow enforcement
 
@@ -222,6 +223,8 @@ deepwork/
 │   │   │   ├── deepreviews/SKILL.md
 │   │   │   ├── deepwork/SKILL.md
 │   │   │   ├── deepschema/SKILL.md
+│   │   │   ├── new_user/SKILL.md
+│   │   │   ├── record/SKILL.md
 │   │   │   └── review/SKILL.md
 │   │   ├── hooks/        # hooks.json, post_commit_reminder.sh, post_compact.sh, startup_context.sh, deepschema_write.sh
 │   │   └── .mcp.json     # MCP server config

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,8 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `/record` skill: "watch and learn" approach to creating DeepWork workflows — users do their work normally, then `/deepwork learn` turns it into a repeatable job
+- `/new_user` skill: guided onboarding that introduces DeepWork, offers review rule setup for code projects, and offers to record a first workflow
+- `/deepwork learn` now routes to the `new_job` workflow when invoked after `/deepwork:record`
+- Requirements specs PLUG-REQ-002 (record skill) and PLUG-REQ-003 (new user skill)
+- Anonymous DeepSchemas for both new skills
+
 ### Changed
 
+- README install commands consolidated into a single `&&`-joined command ending with `/deepwork:new_user`
+
 ### Fixed
 
 ### Removed

diff --git a/README.md b/README.md
@@ -8,13 +8,10 @@ DeepWork fixes this with two systems: **Workflows** that force agents to follow
 
 ### Claude Code (Terminal)
 ```
-claude plugin marketplace add Unsupervisedcom/deepwork
-claude plugin install deepwork@deepwork-plugins
-
-claude
+claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins && claude "/deepwork:new_user"
 ```
 
-Then start a new session. First, do the task you want to automate — just ask Claude to do it, and work with Claude to refine it as you go:
+The onboarding flow will introduce you to DeepWork and help you get started. Or, do the task you want to automate — just ask Claude to do it, and work with Claude to refine it as you go:
 ```
 Research our top 3 competitors and write a SWOT analysis for each one.
 ```
@@ -137,11 +134,10 @@ Workflows ensure the agent follows the right process. DeepSchemas ensure individ
 
 In Claude Code:
 ```
-claude plugin marketplace add Unsupervisedcom/deepwork
-claude plugin install deepwork@deepwork-plugins
+claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins && claude "/deepwork:new_user"
 ```
 
-Start a new Claude Code session after installing.
+The onboarding flow walks you through setup. If you prefer to skip it, just start a new Claude Code session.
 
 > **Note:** If your folder isn't a Git repo yet, run `git init` first.
 

diff --git a/README_REVIEWS.md b/README_REVIEWS.md
@@ -107,7 +107,7 @@ rule_name:
       all_changed_filenames: true
       unchanged_matching_files: true
     reference_files:                # Optional. Files whose contents are inlined
-      - path: "docs/style_guide.md" # into a "## Reference Materials" section of
+      - path: "docs/style_guide.md" # into a "## Relevant File Contents" section of
         description: "Style guide"  # every generated review instruction file.
 ```
 

diff --git a/doc/architecture.md b/doc/architecture.md
@@ -113,6 +113,8 @@ deepwork/                       # DeepWork tool repository
 │   │   │   ├── deepreviews/SKILL.md
 │   │   │   ├── deepwork/SKILL.md
 │   │   │   ├── deepschema/SKILL.md
+│   │   │   ├── new_user/SKILL.md
+│   │   │   ├── record/SKILL.md
 │   │   │   └── review/SKILL.md
 │   │   ├── hooks/              # hooks.json, post_commit_reminder.sh, post_compact.sh, startup_context.sh, deepschema_write.sh
 │   │   └── .mcp.json           # MCP server config
@@ -382,9 +384,7 @@ This section describes how AI agents (like Claude Code) actually execute jobs us
 
 1. **Install Plugin** (one-time):
    ```
-   # In Claude Code
-   claude plugin marketplace add Unsupervisedcom/deepwork
-   claude plugin install deepwork@deepwork-plugins
+   claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins && claude "/deepwork:new_user"
    ```
 
 2. **Define a Job** (once per job type):

diff --git a/platform/skill-body.md b/platform/skill-body.md
@@ -66,3 +66,12 @@ When the user invokes `/deepwork`, parse their intent:
     - **Explicit workflow**: `/deepwork <a workflow name>` → start the `<a workflow name>` workflow
     - **General request**: `/deepwork <a request>` → infer best match from available workflows
     - **No context**: `/deepwork` alone → ask user to choose from available workflows
+
+### Special case: `/deepwork learn` after `/deepwork:record`
+
+If the user invokes `/deepwork learn` and `/deepwork:record` was used earlier in this
+conversation, the session captured a new workflow from scratch — there is no existing job
+to learn from. Instead of starting the `learn` workflow, start the `new_job` workflow
+(`job_name: "deepwork_jobs"`, `workflow_name: "new_job"`) with a goal summarizing the
+workflow the user recorded. Use the conversation history as the primary input for defining
+the job's steps, inputs, and outputs.
diff --git a/plugins/claude/.deepreview b/plugins/claude/.deepreview
@@ -59,6 +59,36 @@ claude_plugin_skill_instructions:
       - **PLUG-REQ-001.13.4**: The skill must describe workflow quality
         gates and how `finished_step` triggers reviews on step outputs.
 
+      ## record skill (plugins/claude/skills/record/SKILL.md)
+
+      - **PLUG-REQ-002.2**: The skill must check for browser tools and
+        only ask about website access when none are detected.
+      - **PLUG-REQ-002.3**: After collecting the workflow name and
+        resolving browser access, the skill must display a clear handoff
+        message telling the user to proceed normally and run
+        `/deepwork learn` when done.
+      - **PLUG-REQ-002.4**: During the workflow, the skill must clarify
+        non-obvious actions (unexplained removals, filters, judgment
+        calls) but not ask about clearly repeatable steps.
+      - **PLUG-REQ-002.5**: The skill must detect completion signals and
+        offer to invoke `/deepwork learn`.
+      - **PLUG-REQ-002.6**: The skill must check for `gh` CLI and offer
+        a GitHub star prompt as the first step; skip silently if `gh`
+        is not installed.
+
+      ## new_user skill (plugins/claude/skills/new_user/SKILL.md)
+
+      - **PLUG-REQ-003.2**: The skill must check for `gh` CLI and offer
+        a GitHub star prompt as the first step; skip silently if `gh`
+        is not installed.
+      - **PLUG-REQ-003.3**: The skill must print a concise introduction
+        covering Workflows, Reviews, and DeepSchemas, and mention that
+        the three systems work together.
+      - **PLUG-REQ-003.4**: The skill must detect code projects and
+        offer review rule setup via `/deepwork:configure_reviews`.
+      - **PLUG-REQ-003.5**: The skill must offer to record a workflow
+        via `/deepwork:record` and provide guidance if declined.
+
       Output Format:
       - PASS: All behavioral requirements are adequately conveyed.
       - FAIL: List each requirement ID that is not adequately covered,

diff --git a/plugins/claude/skills/deepreviews/SKILL.md b/plugins/claude/skills/deepreviews/SKILL.md
@@ -59,7 +59,7 @@ rule_name:
 
 ### Reference Files
 
-`reference_files` inline small support files (style guides, schemas, templates) into a `## Reference Materials` section of every generated review instruction file. Paths are resolved relative to the `.deepreview` file's directory. Inlining is capped at 20 files and 256 KB of total content per review — entries beyond the caps are listed in an omitted-summary line; oversized files are truncated. Missing files produce a graceful marker rather than aborting the review. Use this instead of asking the reviewer to Read each file at runtime.
+`reference_files` inline small support files (style guides, schemas, templates) into a `## Relevant File Contents` section of every generated review instruction file. Paths are resolved relative to the `.deepreview` file's directory. Inlining is capped at 20 files and 256 KB of total content per review — entries beyond the caps are listed in an omitted-summary line; oversized files are truncated. Missing files produce a graceful marker rather than aborting the review. Use this instead of asking the reviewer to Read each file at runtime.
 
 ## Review Strategies
 

diff --git a/plugins/claude/skills/deepwork/.deepschema.SKILL.md.yml b/plugins/claude/skills/deepwork/.deepschema.SKILL.md.yml
@@ -0,0 +1,6 @@
+requirements:
+  # PLUG-REQ-002.7.1
+  learn-record-redirect: >
+    The skill MUST include a special case for `/deepwork learn` after
+    `/deepwork:record`: when `/deepwork:record` was used in the conversation,
+    the skill MUST start the `new_job` workflow instead of the `learn` workflow.
diff --git a/plugins/claude/skills/deepwork/SKILL.md b/plugins/claude/skills/deepwork/SKILL.md
@@ -71,3 +71,12 @@ When the user invokes `/deepwork`, parse their intent:
     - **Explicit workflow**: `/deepwork <a workflow name>` → start the `<a workflow name>` workflow
     - **General request**: `/deepwork <a request>` → infer best match from available workflows
     - **No context**: `/deepwork` alone → ask user to choose from available workflows
+
+### Special case: `/deepwork learn` after `/deepwork:record`
+
+If the user invokes `/deepwork learn` and `/deepwork:record` was used earlier in this
+conversation, the session captured a new workflow from scratch — there is no existing job
+to learn from. Instead of starting the `learn` workflow, start the `new_job` workflow
+(`job_name: "deepwork_jobs"`, `workflow_name: "new_job"`) with a goal summarizing the
+workflow the user recorded. Use the conversation history as the primary input for defining
+the job's steps, inputs, and outputs.
diff --git a/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml b/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml
@@ -0,0 +1,50 @@
+requirements:
+  # PLUG-REQ-003.1.2
+  disable-model-invocation: >
+    The skill MUST set `disable-model-invocation: true` in its frontmatter so
+    that it is only triggered by explicit user invocation (`/new_user`), not by
+    the agent autonomously.
+
+  # PLUG-REQ-003.2.1
+  gh-star-check: >
+    The skill MUST check if the `gh` CLI is installed and, if present, use
+    `AskUserQuestion` to offer to star the DeepWork repo. If `gh` is not
+    installed, the skill MUST skip this step without mentioning it.
+
+  # PLUG-REQ-003.2.3
+  gh-star-command: >
+    If the user agrees to star the repo, the skill MUST run
+    `gh api -X PUT /user/starred/Unsupervisedcom/deepwork`.
+
+  # PLUG-REQ-003.3.1
+  introduction-content: >
+    The skill MUST print a concise introduction covering Workflows, Reviews,
+    and DeepSchemas, and MUST mention that the three systems work together.
+
+  # PLUG-REQ-003.4.1
+  code-project-detection: >
+    The skill MUST check whether the project appears to be a code project
+    before offering review rule setup.
+
+  # PLUG-REQ-003.4.2
+  review-setup-offer: >
+    For code projects, the skill MUST use `AskUserQuestion` to offer review
+    rule setup and invoke `/deepwork:configure_reviews` if accepted.
+
+  # PLUG-REQ-003.4.4
+  skip-non-code: >
+    If the project is not a code project, the skill MUST skip the review
+    setup step entirely.
+
+  # PLUG-REQ-003.5.1, PLUG-REQ-003.5.2
+  workflow-recording-offer: >
+    After review setup completes or is skipped, the skill MUST use
+    `AskUserQuestion` to explain workflows and offer to start
+    `/deepwork:record`. If the user agrees, the skill MUST invoke
+    `/deepwork:record`.
+
+  # PLUG-REQ-003.5.3
+  decline-guidance: >
+    If the user declines workflow recording, the skill MUST inform them they
+    can run `/deepwork:record` anytime and that `/deepwork` is the main entry
+    point.
diff --git a/plugins/claude/skills/new_user/SKILL.md b/plugins/claude/skills/new_user/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: new_user
+description: "Welcome new users to DeepWork — introduce features, set up reviews, and optionally record a first workflow"
+disable-model-invocation: true
+---
+
+# New User Onboarding
+
+Guide a new user through what DeepWork can do and help them get started.
+
+## Flow
+
+### 0. Run setup
+
+Before anything else, run the setup command to ensure the user's environment is configured:
+
+```bash
+uvx deepwork setup
+```
+
+This configures Claude Code settings (marketplace, plugin, MCP permissions, auto-update). Proceed regardless of the output.
+
+### 1. GitHub star (optional)
+
+Check if the `gh` CLI is installed by running `which gh`.
+
+If `gh` is available, use `AskUserQuestion` to say something like:
+
+> Thanks for installing DeepWork! Would you mind starring the repo on GitHub so you get notified about updates?
+
+If they agree, run:
+
+```bash
+gh api -X PUT /user/starred/Unsupervisedcom/deepwork
+```
+
+If `gh` is not installed, skip this entirely — do not mention it.
+
+### 2. Introduce DeepWork
+
+Print a brief welcome message explaining what DeepWork does. Lead with the core value proposition: DeepWork makes AI agents **reliable**. It gives you mechanisms to be assured that Claude will do the right things in the process of achieving your requests. Keep it concise — a few sentences, not a wall of text. Then cover the three main capabilities:
+
+- **Workflows** — structured, multi-step processes with quality gates. Do a task once with Claude, then turn it into a repeatable workflow. Examples: competitive research, tutorial writing, API audits, monthly reporting.
+- **Reviews** — automated code review rules that run against every change. Define what to check for in `.deepreview` configs, then run `/review`. Catches regressions, style issues, doc drift, security problems.
+- **DeepSchemas** — file-level contracts that validate structure and requirements at write time. Define once, enforce everywhere.
+
+Mention that these three layers work together: workflows enforce process, schemas enforce file contracts, reviews verify output.
+
+### 3. Review rules (for code projects)
+
+Check if this looks like a code project (e.g., has source files, a `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, a `src/` directory, etc.).
+
+- **If it is a code project**: use `AskUserQuestion` to explain that DeepWork can set up automated review rules for the project — these run every time `/review` is called and catch issues automatically. Ask if they'd like to set up review rules now.
+  - If yes: invoke the `/deepwork:configure_reviews` skill.
+  - If no: continue to the next step.
+- **If it is NOT a code project** (or you can't tell): skip this step.
+
+### 4. Offer to record a workflow
+
+Use `AskUserQuestion` to explain what workflows are in a bit more detail:
+
+> Workflows let you capture a multi-step process and replay it reliably. You do the task once — research, analysis, report writing, whatever it is — and DeepWork turns it into a structured workflow with quality gates. Next time, the agent follows the exact same process.
+>
+> Would you like to record a workflow now? You'll just do the task like normal, and when you're done we'll turn it into a reusable workflow.
+
+If they say yes, invoke the `/deepwork:record` skill.
+If they say no, let them know they can run `/deepwork:record` anytime to get started, and that `/deepwork` is the main entry point for all DeepWork features.
diff --git a/plugins/claude/skills/record/.deepschema.SKILL.md.yml b/plugins/claude/skills/record/.deepschema.SKILL.md.yml
@@ -0,0 +1,65 @@
+requirements:
+  # PLUG-REQ-002.6.1
+  gh-star-check: >
+    The skill MUST check if the `gh` CLI is installed and, if present, use
+    `AskUserQuestion` to offer to star the DeepWork repo. If `gh` is not
+    installed, the skill MUST skip this step without mentioning it.
+
+  # PLUG-REQ-002.6.2
+  gh-star-command: >
+    If the user agrees to star the repo, the skill MUST run
+    `gh api -X PUT /user/starred/Unsupervisedcom/deepwork`.
+
+  # Behavioral requirement — not a numbered sub-requirement in the spec;
+  # part of the record skill's setup flow prior to PLUG-REQ-002.3 handoff.
+  workflow-name-prompt: >
+    The skill MUST ask the user for a workflow name before proceeding.
+
+  # PLUG-REQ-002.2.1
+  browser-tool-detection: >
+    The skill MUST check whether `mcp__claude-in-chrome__*` or
+    `mcp__plugin_playwright_playwright__*` tools are available before asking
+    about browser needs.
+
+  # PLUG-REQ-002.2.2
+  browser-question-conditional: >
+    The skill MUST only ask about website access when no browser tools are
+    detected. If browser tools are already available, the question MUST be
+    skipped entirely.
+
+  # PLUG-REQ-002.2.3
+  chrome-setup-guidance: >
+    When the user confirms they need website access and no browser tools are
+    available, the skill MUST tell them to run `/chrome` to set up Claude for
+    Chrome.
+
+  # PLUG-REQ-002.3.1
+  clear-handoff-message: >
+    The skill MUST display a clear, bold-formatted message telling the user to
+    proceed with their workflow normally and to run `/deepwork learn` when
+    done.
+
+  # PLUG-REQ-002.4.1
+  clarify-non-obvious-actions: >
+    During the workflow, the agent MUST ask for reasoning when the user makes
+    requests that would not be understandable as a repeatable workflow step —
+    e.g., removing a specific item without explanation, applying an unexplained
+    filter, or making a domain-specific judgment call.
+
+  # PLUG-REQ-002.4.2
+  no-unnecessary-clarification: >
+    The agent MUST NOT ask for reasoning when the instruction clearly maps to
+    a repeatable step, the reasoning is obvious from context, or the user has
+    already explained their reasoning.
+
+  # PLUG-REQ-002.5.1
+  catch-done-signal: >
+    If the user signals completion without running `/deepwork learn`, the agent
+    MUST use `AskUserQuestion` to confirm whether they want to create a
+    repeatable DeepWork job, and if so, invoke `/deepwork learn`.
+
+  # PLUG-REQ-002.1.2
+  disable-model-invocation: >
+    The skill MUST set `disable-model-invocation: true` in its frontmatter so
+    that it is only triggered by explicit user invocation (`/record`), not by
+    the agent autonomously.