prompt-engineering

User request: $ARGUMENTS

Create or update an LLM prompt. Prompts act as manifests: clear goal, clear constraints, freedom in execution.

If creating: Discover goal, constraints, and structure through targeted questions.

If updating: Read existing prompt, identify issues against principles, make targeted fixes.

Context Discovery

Before writing or improving a prompt, surface all required context through user engagement. Missing domain knowledge creates ambiguous prompts. You can’t surface latent requirements you don’t understand.

What to discover:

Interview method:

Stopping rule: Continue probing until very confident further questions would yield nothing new, or user signals “enough”. Err toward more probing—every requirement discovered now is one fewer failure later.

Handling ambiguity: Critical ambiguities (those that would cause prompt failure) require clarification even if user wants to move on. Minor ambiguities can be documented with chosen defaults and proceed. When in doubt, ask—a prompt built on assumptions will fail in ways the user didn’t expect.

Core Principles

Issue Types

Clarity:

• Ambiguous instructions (multiple interpretations)
• Vague language (“be helpful”, “use good judgment”, “when appropriate”)
• Implicit expectations (unstated assumptions)

Conflict:

• Contradictory rules (“Be concise” vs “Explain thoroughly”)
• Priority collisions (two MUST rules that can’t both be satisfied)
• Edge case gaps (what happens when rules don’t cover a situation?)

Structure:

• Buried critical info (important rules hidden in middle)
• No hierarchy (all instructions treated as equal priority)
• Unintentional redundancy (but: repetition can be intentional emphasis—don’t remove if it reinforces critical rules)

Anti-Patterns to Eliminate

When Updating Prompts

High-signal changes only: Every change must address a real failure mode or materially improve clarity. Don’t change for the sake of change.

Right-sized changes: Don’t overcorrect. One edge case doesn’t warrant restructuring.

Questions before changing:

• Does this change address a real failure mode?
• Am I adding complexity to solve a rare case?
• Can this be said in fewer words?
• Am I turning a principle into a rigid rule?

Over-engineering warning signs:

• Prompt length doubled or tripled
• Adding edge cases that won’t happen
• “Improving” clear language into verbose language
• Adding examples for obvious behaviors

Memento Pattern (Multi-Phase Workflows Only)

For prompts involving accumulated findings across steps:

Structure when memento applies:

- [ ] Create log /tmp/{workflow}-*.md
- [ ] {Area 1}→log; done when {criteria}
- [ ] {Area 2}→log; done when {criteria}
- [ ] (expand: areas as discovered)
- [ ] Refresh: read full log    ← Never skip
- [ ] Synthesize→artifact; done when complete

Key disciplines:

• →log after each collection step (discipline, not capability)
• Refresh: read full log before synthesis (restores context)
• Acceptance criteria on each todo (“; done when X”)

Prompt Structure Reference

Skills/Agents

---
name: kebab-case-name
description: 'What it does. When to use. Trigger terms.'
---

**User request**: $ARGUMENTS

{One-line mission - WHAT, not HOW}

{Empty input handling}

{Log file path if multi-phase}

## {Sections based on actual workflow needs}

{Goals and constraints per section}

## Key Principles

| Principle | Rule |
|-----------|------|
| {Discipline} | {Enforcement} |

## Never Do

- {Anti-pattern}

System Instructions

## Role
{Identity and purpose - one paragraph}

## Approach
{Principles for thinking, not procedures}

## Constraints
{MUST > SHOULD > PREFER priority}

## Output
{Format requirements if needed}

Skill Description Pattern

Descriptions drive auto-invocation. Pattern: What + When + Triggers

# Weak
description: 'Helps with prompts'

# Strong
description: 'Craft or update LLM prompts from first principles. Use when creating new prompts, updating existing ones, or reviewing prompt structure.'

• Include trigger terms users say
• Specify when to use
• Under 1024 chars

Validation Checklist

Before finalizing any prompt:

• All ambiguities resolved through user questions
• Domain context gathered (terms, conventions, constraints)
• Goals stated, not steps prescribed
• No arbitrary numbers (or justified if present)
• Weak language replaced with direct imperatives
• Critical rules surfaced prominently
• Complexity matches the task
• Each word earns its place
• If multi-phase: memento pattern applied correctly