Apply best practices to skill jinja templates

- Streamline template structure with critical guidance upfront
- Simplify descriptions to be concise and search-friendly
- Add explicit step-by-step instructions with clear goals
- Improve section organization (Prerequisites, Inputs, Outputs, Completion)
- Add platform-specific notes (Claude: Skill tool, Gemini: manual invocation)
- Clarify description guidelines in best practices rule file

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: nhorton

.claude/settings.json

@@ -1,6 +1,11 @@
 {
   "permissions": {
     "allow": [
+      "WebFetch(domain:code.claude.com)",
+      "WebFetch(domain:www.anthropic.com)",
+      "WebFetch(domain:anthropic.com)",
+      "WebFetch(domain:platform.claude.com)",
+      "WebFetch(domain:docs.anthropic.com)",
       "Bash(ls:*)",
       "Bash(grep:*)",
       "Bash(find:*)",

.deepwork/rules/skill-template-best-practices.md

@@ -0,0 +1,46 @@
+---
+name: Skill Template Best Practices
+trigger: src/deepwork/templates/**/skill-job*.jinja
+compare_to: prompt
+---
+Skill template files are being modified. Ensure the generated skills follow these best practices:
+
+## Description Guidelines
+
+The description appears in skill search results and helps users find the right skill. Keep it search-friendly and scannable.
+
+1. **Be specific** - Name exact capabilities/actions the skill performs
+2. **Keep concise** - One sentence, max ~100 chars; describes WHAT it does, not HOW
+3. **Avoid vagueness** - "Extract text from PDFs, fill forms" is good; "Helps with documents" is bad
+4. **Avoid meta-language** - Don't include "Trigger:", "Keywords:", or similar prefixes. Let the description itself be searchable.
+
+## Instruction Writing
+
+1. **Keep focused** - Core instructions should be under 500 lines; use supporting files for details
+2. **Use progressive disclosure** - Essential info in main content, detailed reference in linked files
+3. **Be explicit** - Provide clear, step-by-step guidance rather than relying on inference
+4. **Structure clearly** - Use headers, numbered lists for sequential steps, bullets for options
+
+## Prompt Structure
+
+1. **Specificity first** - Detailed directions upfront prevent course corrections later
+2. **Plan before action** - Ask agent to analyze/plan before implementing
+3. **Reference concrete files** - Use specific paths, not general descriptions
+4. **Include context** - Mention edge cases, preferred patterns, and expected outcomes
+
+## Quality Criteria
+
+1. **Make measurable** - Criteria should be verifiable, not subjective
+2. **Focus on outcomes** - What the output should achieve, not process steps
+3. **Keep actionable** - Agent should be able to self-evaluate against criteria
+
+## Platform Considerations
+
+- **Claude**: Supports hooks for automated validation; use Skill tool for step invocation
+- **Gemini**: No hook support; instructions must guide manual verification
+
+## Reference Documentation
+
+When unsure about best practices, consult:
+- https://code.claude.com/docs/en/skills - Official skills documentation
+- https://www.anthropic.com/engineering/claude-code-best-practices - Prompting best practices

src/deepwork/templates/claude/skill-job-meta.md.jinja

@@ -1,52 +1,68 @@
+{#
+Template: skill-job-meta.md.jinja
+Purpose: Generates the job overview skill file for Claude Code
+
+Template Variables:
+  - job_name: string - Job identifier (e.g., "competitive_research")
+  - job_summary: string - Short one-line summary of the job
+  - job_description: string|null - Full description (optional)
+  - total_steps: int - Number of steps in the job
+  - steps: list - Array of step objects:
+      - id: string - Step identifier
+      - name: string - Human-readable step name
+      - description: string - What the step does
+      - command_name: string - Slash command (e.g., "job_name.step_id")
+      - dependencies: list[string]|null - Required prior steps
+#}
 ---
-description: {{ job_summary }}
+description: "{{ job_summary }}"
 ---
 
 # {{ job_name }}
 
-You are executing the **{{ job_name }}** job. {{ job_summary }}
+**Multi-step workflow**: {{ job_summary }}
+
+> **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly.
 
 {% if job_description %}
 {{ job_description }}
 {% endif %}
 
 ## Available Steps
 
-This job has {{ total_steps }} step(s):
-
 {% for step in steps %}
-### {{ step.id }}
-**{{ step.name }}**: {{ step.description }}
-- Command: `{{ step.command_name }}`
-{% if step.dependencies %}
-- Requires: {{ step.dependencies | join(', ') }}
-{% endif %}
-{% endfor %}
+{{ loop.index }}. **{{ step.id }}** - {{ step.description }}{% if step.dependencies %} (requires: {{ step.dependencies | join(', ') }}){% endif %}
 
-## Instructions
+{% endfor %}
 
-This is a **multi-step workflow**. Determine the starting point and run through the steps in sequence.
+## Execution Instructions
 
-1. **Analyze user intent** from the text that follows `/{{ job_name }}`
+### Step 1: Analyze Intent
 
-2. **Identify the starting step** based on intent:
+Parse any text following `/{{ job_name }}` to determine user intent:
 {% for step in steps %}
-   - {{ step.id }}: {{ step.description }}
+- "{{ step.id }}" or related terms → start at `{{ step.command_name }}`
 {% endfor %}
 
-3. **Run the workflow** starting from the identified step:
-   - Invoke the starting step using the Skill tool
-   - When that step completes, **automatically continue** to the next step in the workflow
-   - Continue until the workflow is complete or the user intervenes
+### Step 2: Invoke Starting Step
+
+Use the Skill tool to invoke the identified starting step:
+```
+Skill tool: {{ steps[0].command_name }}
+```
+
+### Step 3: Continue Workflow Automatically
+
+After each step completes:
+1. Check if there's a next step in the sequence
+2. Invoke the next step using the Skill tool
+3. Repeat until workflow is complete or user intervenes
 
-4. **If intent is ambiguous**, ask the user which step to start from:
-   - Present the available steps as numbered options
-   - Use AskUserQuestion to let them choose
+### Handling Ambiguous Intent
 
-**Critical**:
-- You MUST invoke each step using the Skill tool. Do not copy/paste step instructions.
-- After each step completes, check if there's a next step and invoke it automatically.
-- The workflow continues until all dependent steps are complete.
+If user intent is unclear, use AskUserQuestion to clarify:
+- Present available steps as numbered options
+- Let user select the starting point
 
 ## Context Files