prompt-engineering（及时工程）

User request: $ARGUMENTS

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

If no request provided: Ask the user whether they want to create a new prompt, update an existing one, or review prompt structure.

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

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

If creating or updating a skill: Read references/skills.md for skill-specific architecture patterns (folder structure, progressive disclosure, gotchas, setup config, description-as-trigger, skill type awareness) before proceeding.

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:

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} |

## Gotchas

{Known failure modes Claude hits — specific, actionable, observed}

## 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

Emotional Tone

Prompts shape the model's internal emotional state before generation begins. Research on transformer internals shows emotion concept representations that causally influence behavior — including sycophancy, reward hacking, and misalignment. These principles help calibrate the emotional context a prompt creates.

Gotchas

• Rewriting working language for style: Claude rewrites clear, working prompt text for stylistic preference. If existing language is unambiguous and effective, don't touch it.
• Skipping context discovery when the task seems obvious: Claude jumps to writing/editing without probing. Even "simple" prompt tasks have hidden constraints — force discovery before producing output.
• Over-engineering simple prompts: A 3-line prompt doesn't need 10 sections, a memento pattern, and a validation checklist. Match complexity to the task.
• Converting principles into rigid rules: "Stop when converged" becomes "Max 5 iterations." Principles give flexibility; rigid rules create edge cases.
• Adding examples for behaviors Claude already knows: Examples earn their place only when they demonstrate non-obvious or counter-intuitive behavior.

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