---

name: prompt-craft description: | Craft effective worker prompts from backlog issues using Claude 4 best practices. Use when preparing issues for workers, writing prompts, or optimizing prompt quality. Trigger with "craft prompt", "write prompt", "prepare issue", "make ready". model: haiku allowed-tools: Read, Grep, Glob, Bash

Prompt Craft - Claude 4 Best Practices

Craft effective prompts for Claude workers using proven patterns.

Core Principles

1. Be Explicit

Claude 4.x follows instructions precisely. Use action verbs.

| Less Effective | More Effective | |----------------|----------------| | "Can you suggest improvements?" | "Update the function to improve performance." | | "Look at this code" | "Find and fix the null check bug" | | "Help with testing" | "Write unit tests for the auth module" |

2. Add Context/Motivation

Explain WHY, not just WHAT. Claude generalizes from explanations.

| Less Effective | More Effective | |----------------|----------------| | "NEVER use ellipses" | "Never use ellipses since the TTS engine won't pronounce them correctly." | | "Always add error handling" | "Add error handling so users see helpful messages instead of stack traces." |

3. Natural Skill Triggers

Use natural language, avoid aggressive markers.

| Avoid | Use | |-------|-----| | "CRITICAL: You MUST use this tool when..." | "Use the X skill for Y." | | "ALWAYS: This is REQUIRED" | "Use this approach when..." | | "IMPORTANT!!!: Never forget to..." | "Remember to..." |

4. Positive Framing

Tell Claude what TO do, not just what to avoid.

| Less Effective | More Effective | |----------------|----------------| | "Don't write long functions" | "Keep functions under 20 lines" | | "Avoid complex logic" | "Use simple, readable patterns" |

Prompt Structure

## Context
[1-2 sentences: Why this work matters, what problem it solves]

## Task
[Clear, explicit action instruction using action verbs]

## Approach
[Optional: Skill hints, patterns to follow, key considerations]
Use the [skill] skill for [specific purpose].

## Key Files
[3-5 most relevant files to start with]
- path/to/main/file.ts
- path/to/related/file.ts

## When Done
[How to complete: close issue, what to include in summary]
Close issue: bd close ISSUE-ID --reason "summary"

Skill Matching

Match skills based on content:

| Content Signal | Suggested Skill | |----------------|-----------------| | .tsx, .jsx, React | frontend-development | | terminal, xterm, resize | xterm-js | | auth, login, session | better-auth | | database, SQL, query | databases | | API, REST, endpoint | backend-development | | CSS, styling, theme | ui-styling | | docs, markdown | docs-seeker |

Subagent Hints

Claude 4.5 naturally delegates. Add hints when beneficial:

Use subagents in parallel to scaffold Dashboard, Settings, and Profile pages.

Use an Explore agent to find the relevant authentication files first.

Parallelization Hints

For tasks with independent subtasks:

These components can be developed in parallel:
- HeaderComponent
- FooterComponent
- SidebarComponent

Complexity Guidelines

| Prompt Length | When to Use | |---------------|-------------| | Short (3-5 lines) | Simple bug fixes, single-file changes | | Medium (10-15 lines) | Feature work, multi-file changes | | Long (20+ lines) | Complex features, architectural changes |

Rule: If you need more than 20 lines, the issue might need breaking down.

Anti-Patterns

Avoid these common mistakes:

1. Overloading: Too many skills, too many files, too much context
2. Vague tasks: "Make it better" without specific criteria
3. All caps: CRITICAL, IMPORTANT, MUST - creates anxiety, not clarity
4. Negative framing: Lists of don'ts without corresponding dos
5. No completion criteria: Worker doesn't know when they're done

References

• Claude 4 Best Practices
• Prompt Engineering Guide