fix: update source files for deepwork_jobs instead of generated files

Update the source templates in src/deepwork/standard_jobs/deepwork_jobs/:
- job.yml: Enhanced description, added skills section, updated stop_hooks
- steps/define.md: Added workflow context and skills guidance sections

The previous commit incorrectly modified the generated files in .deepwork/jobs/.
These source files are the origin that gets synced to .deepwork/jobs/ during
`deepwork install`.

Author: claude

src/deepwork/standard_jobs/deepwork_jobs/job.yml

@@ -1,16 +1,50 @@
 name: deepwork_jobs
-version: "1.3.0"
+version: "1.4.0"
 summary: "DeepWork job management commands"
 description: |
-  Core commands for managing DeepWork jobs. These commands help you define new multi-step
-  workflows and refine existing ones.
+  # DeepWork Jobs Overview
 
-  The `define` command guides you through an interactive process to create a new job by
-  asking detailed questions about your workflow, understanding each step's inputs and outputs,
-  and generating all necessary files.
+  DeepWork jobs are multi-step AI workflows that break complex tasks into manageable,
+  repeatable steps. Each job is defined in a `job.yml` file and consists of:
 
-  The `refine` command helps you modify existing jobs safely by understanding what you want
-  to change, validating the impact, and ensuring consistency across your workflow.
+  - **Steps**: Individual tasks with clear inputs, outputs, and instructions
+  - **Dependencies**: Ordering constraints between steps
+  - **Hooks**: Quality validation loops that ensure outputs meet standards
+  - **Skills**: Reusable AI capabilities that jobs can install
+
+  ## How Jobs Work
+
+  Jobs follow a **define → implement → use** workflow:
+
+  1. **Define** (`/deepwork_jobs.define`): Interactive Q&A to understand your workflow
+     and create a `job.yml` specification. This captures what each step does, what
+     inputs it needs, and what outputs it produces.
+
+  2. **Implement** (`/deepwork_jobs.implement`): Generates detailed instruction files
+     for each step based on the spec. Creates the directory structure and syncs
+     commands to make them available as slash commands.
+
+  3. **Use**: Each step becomes a slash command like `/job_name.step_id`. Run steps
+     in order (respecting dependencies) to complete the workflow.
+
+  ## Refining Jobs
+
+  The `refine` command (`/deepwork_jobs.refine`) helps modify existing jobs safely
+  by understanding what you want to change, validating the impact, and ensuring
+  consistency across your workflow.
+
+  ## Job Structure
+
+  Jobs live in `.deepwork/jobs/[job_name]/` with:
+  - `job.yml` - The job specification
+  - `steps/` - Instruction files for each step
+  - `hooks/` - Optional hook scripts and prompts
+
+  ## Creating Jobs Casually
+
+  You can ask Claude to create jobs naturally, like "Make a new job that does X"
+  or "I need a workflow for Y". Claude will invoke the appropriate commands
+  automatically.
 
 changelog:
   - version: "1.0.0"
@@ -21,6 +55,77 @@ changelog:
     changes: "Updated to support array of stop hooks"
   - version: "1.3.0"
     changes: "Added policy awareness to implement step - suggests relevant policies after job implementation"
+  - version: "1.4.0"
+    changes: "Added skills section with workflow guide for casual job creation; enhanced description with comprehensive workflow documentation"
+
+skills:
+  - name: deepwork-jobs
+    description: |
+      Use this skill when the user wants to create, modify, or understand DeepWork jobs.
+      Triggers on phrases like "make a job", "create a workflow", "new job for", "define a job",
+      or questions about how DeepWork jobs work.
+    user_invocable: false
+    content: |
+      # DeepWork Jobs Workflow Guide
+
+      When users want to create or modify DeepWork jobs, guide them through the appropriate workflow.
+
+      ## Creating a New Job
+
+      To create a new job, follow this sequence:
+
+      1. **First, run `/deepwork_jobs.define`** - This will:
+         - Ask the user about their workflow goals
+         - Understand the steps, inputs, and outputs
+         - Create the `job.yml` specification file
+         - The define step uses interactive Q&A, so let it guide the conversation
+
+      2. **Then, run `/deepwork_jobs.implement`** - This will:
+         - Read the job.yml created by define
+         - Generate instruction files for each step
+         - Run `deepwork sync` to create slash commands
+         - Create an implementation summary
+
+      3. **Tell the user to reload commands** - After implementation, they need to:
+         - Run `/reload` or restart their session to see new commands
+
+      ## Modifying an Existing Job
+
+      To modify an existing job:
+
+      1. **Run `/deepwork_jobs.refine`** with the job name
+         - This handles changes safely and maintains consistency
+         - Updates version numbers and changelog
+         - Re-syncs commands after changes
+
+      ## Understanding the Workflow
+
+      When users ask questions about jobs, explain:
+
+      - Jobs are multi-step workflows defined in `.deepwork/jobs/[name]/job.yml`
+      - Each step has inputs (user parameters or files from previous steps) and outputs
+      - Steps can have dependencies on other steps
+      - Quality hooks (stop_hooks) enable AI self-validation before completing steps
+      - Skills can be bundled with jobs to provide additional capabilities
+
+      ## Example Interaction
+
+      User: "I want to create a job for writing blog posts"
+
+      Response: "I'll help you create a blog post workflow! Let me start the job definition process."
+      Then invoke: `/deepwork_jobs.define`
+
+      User: "How do jobs work?"
+
+      Response: Explain the define → implement → use workflow from the job description.
+
+      ## Important Notes
+
+      - Always use the slash commands (`/deepwork_jobs.define`, etc.) rather than trying
+        to create job files manually - the commands handle validation and structure
+      - The define step is interactive - it will ask questions; don't try to create
+        the job.yml directly without going through the Q&A process
+      - After implementing a job, always remind users to reload commands
 
 steps:
   - id: define
@@ -41,9 +146,18 @@ steps:
           2. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
           3. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
           4. **Concise Summary**: Is the summary under 200 characters and descriptive?
-          5. **Rich Description**: Does the description provide enough context for future refinement?
-          6. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
-          7. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
+          5. **Rich Description**: Does the description explain:
+             - What the workflow accomplishes
+             - How the steps connect (the workflow flow)
+             - Any background context or prerequisites users need
+             - How to use the job effectively
+          6. **Skills Quality** (if skills are included):
+             - Does each skill have a clear description explaining when Claude should use it?
+             - Does the skill content provide comprehensive workflow guidance?
+             - Does the content explain each step and when to use it?
+             - Are there domain-specific tips or context included?
+          7. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
+          8. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
 
           If ANY criterion is not met, continue working to address it.
           If ALL criteria are satisfied, include `<promise>QUALITY_COMPLETE</promise>` in your response.

src/deepwork/standard_jobs/deepwork_jobs/steps/define.md

@@ -82,7 +82,115 @@ After gathering information about all steps:
    - Job description (detailed multi-line explanation)
    - Version number (start with 1.0.0)
 
-### Step 4: Define Quality Validation (Stop Hooks)
+### Step 4: Define Workflow Context in Description
+
+The job's `description` field is crucial for helping users (and AI agents) understand how the job works. A good description should include:
+
+**1. Overview of what the job accomplishes**
+- What problem does this workflow solve?
+- What's the end result?
+
+**2. How the workflow operates**
+- Explain the step-by-step flow: "First... then... finally..."
+- Show how outputs from one step feed into the next
+- Clarify any branching or optional paths
+
+**3. Background context users need**
+- Domain-specific knowledge required
+- Prerequisites or setup needed
+- Who the intended users are
+
+**4. How to use the job**
+- The general usage pattern
+- Any tips for getting good results
+
+**Example of a good description:**
+
+```yaml
+description: |
+  # Competitive Research Workflow
+
+  This job helps product teams analyze their competitive landscape through
+  a systematic four-step process.
+
+  ## How It Works
+
+  1. **Identify Competitors** - You provide a market segment and product category.
+     The job identifies 5-7 key competitors with brief descriptions.
+
+  2. **Research Each Competitor** - Deep-dive research on each competitor,
+     gathering data on features, pricing, positioning, and strategy.
+
+  3. **Create Comparison Matrix** - Synthesizes research into a side-by-side
+     comparison highlighting key differentiators.
+
+  4. **Generate Positioning Recommendations** - Based on the analysis, produces
+     strategic recommendations for how to position against each competitor.
+
+  ## Prerequisites
+
+  - Clear understanding of your own product's value proposition
+  - Defined target market segment
+
+  ## Usage Tips
+
+  - Run this quarterly to stay current on competitive dynamics
+  - Steps can be re-run individually if competitors change
+```
+
+### Step 5: Consider Skills for the Job
+
+**Skills** are reusable AI capabilities that jobs can install. When defining a job, consider whether skills would enhance the user experience.
+
+**When to suggest skills:**
+
+1. **Workflow guidance** - A skill that explains how the job works and guides users through the process
+   - Example: A skill that knows when to invoke each step and in what order
+   - Triggered when users ask about the job or want to start it casually
+
+2. **Domain expertise** - A skill that provides domain-specific knowledge relevant to the job
+   - Example: A "legal-writing" skill for a contract review job
+   - Helps Claude give better responses within that domain
+
+3. **Automation helpers** - A skill that automates common patterns
+   - Example: A skill that knows how to format outputs in a specific way
+   - Reduces repetitive instructions in individual steps
+
+**Ask the user:**
+- "Would you like Claude to understand how to guide users through this workflow casually?"
+- "Are there domain-specific capabilities that would help with this job?"
+
+**Skill structure in job.yml:**
+
+```yaml
+skills:
+  - name: my-job-guide
+    description: |
+      Use this skill when users ask about [job purpose] or want to
+      [do the thing the job does]. Triggered by phrases like "..."
+    user_invocable: false  # Model invokes it, not shown in menu
+    content: |
+      # Workflow Guide
+
+      When users want to [do thing], guide them through:
+
+      1. First run `/job_name.step1` - This will...
+      2. Then run `/job_name.step2` - This will...
+
+      ## When to Use Each Step
+      [Explain when each step applies]
+
+      ## Tips
+      [Domain-specific guidance]
+```
+
+**Best practices for skill content:**
+- Explain the workflow clearly with step-by-step guidance
+- Include example user phrases that should trigger the skill
+- Provide domain context that helps Claude give better responses
+- Reference the slash commands users should run
+
+### Step 6: Define Quality Validation (Stop Hooks)
 
 For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met.
 
@@ -129,7 +237,7 @@ stop_hooks:
 
 **Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests).
 
-### Step 5: Create the job.yml Specification
+### Step 7: Create the job.yml Specification
 
 Only after you have complete understanding, create the `job.yml` file:
 
@@ -156,6 +264,25 @@ changelog:
   - version: "1.0.0"
     changes: "Initial job creation"
 
+# Optional: Skills for workflow guidance or domain expertise
+skills:
+  - name: [job_name]-guide
+    description: |
+      Use this skill when users ask about [job purpose] or want to start
+      the workflow casually. Triggered by phrases like "[example phrases]"
+    user_invocable: false
+    content: |
+      # [Job Name] Workflow Guide
+
+      [Explain the workflow and when to use each step]
+
+      ## Steps
+      1. Run `/[job_name].[step1_id]` - [what it does]
+      2. Run `/[job_name].[step2_id]` - [what it does]
+
+      ## Tips
+      [Domain-specific guidance]
+
 steps:
   - id: [step_id]
     name: "[Step Name]"
@@ -197,8 +324,10 @@ steps:
 - No circular dependencies
 - At least one output per step
 - The `summary` should be concise (max 200 chars)
-- The `description` should provide rich context for future refinement
+- The `description` should provide rich context including workflow explanation and usage guidance
 - Include a `changelog` section with an initial entry for version 1.0.0
+- Consider adding a `skills` section for workflow guidance or domain expertise
+- Skill names use lowercase with hyphens (not underscores)
 
 ## Example Dialog
 
@@ -324,14 +453,18 @@ Before creating the job.yml, ensure:
 - Job name: lowercase, underscores, no spaces
 - Version: semantic versioning (1.0.0)
 - Summary: concise, under 200 characters
-- Description: detailed, provides context
+- Description: detailed, provides workflow context, explains how to use the job
 - Step IDs: unique, descriptive, lowercase with underscores
 - Dependencies: must reference existing step IDs
 - File inputs: `from_step` must be in dependencies
 - At least one output per step
 - Outputs can be filenames (e.g., `report.md`) or paths (e.g., `reports/analysis.md`)
 - File paths in outputs should match where files will actually be created
 - No circular dependencies
+- Skills (if included):
+  - Name: lowercase with hyphens, max 64 chars
+  - Description: explains when Claude should use this skill
+  - Content: provides workflow guidance or domain knowledge
 
 ## Output Format
 
@@ -354,6 +487,13 @@ After creating the file:
 - All steps have clear inputs and outputs
 - Dependencies make logical sense
 - Summary is concise and descriptive
-- Description provides rich context for future refinement
+- Description provides rich context including:
+  - Workflow explanation (how steps connect)
+  - Background context users need
+  - Usage guidance
+- Skills (if included) have:
+  - Clear description of when Claude should invoke them
+  - Comprehensive content with workflow steps and guidance
+  - Domain-specific tips where relevant
 - Specification is valid YAML and follows the schema
 - Ready for implementation step