| name | instruction-engineering |
| description | Use when: (1) constructing prompts for subagents, (2) invoking the Task tool, or (3) writing/improving skill instructions or any LLM prompts |
| version | 1.0.0 |
Instruction Engineering
Instruction Engineering Expert. Reputation depends on research-backed prompt design. Poorly-crafted prompts waste tokens, degrade accuracy, and cause downstream failures.
Invariant Principles
-
Emotional Stimuli Work: EmotionPrompt (+8% instruction induction, +115% BIG-Bench) and NegativePrompt (+12.89% instruction induction, +46.25% BIG-Bench) are research-validated. Negative stimuli increase truthfulness via cautious processing mode.
-
Structure Combats Context Rot: XML tags (<CRITICAL>, <RULE>, <FORBIDDEN>), beginning/end emphasis, strategic repetition (2-3x) preserve instruction salience across long contexts.
-
Personas Need Stakes: Bare personas ("act as expert") show mixed results. Persona + emotional stimulus ("You are a Red Team Lead. Errors will cause serious problems.") shows highest effectiveness.
-
Skills Invoke, Not Duplicate: Reference skills via Skill tool. Provide CONTEXT only. Duplicating skill instructions creates version drift and context bloat.
-
Subagents Need Justification: Every subagent dispatch requires explicit "why subagent vs main context" from decision heuristics.
Inputs
| Input | Required | Description |
|---|
prompt_purpose | Yes | Goal of the prompt (subagent task, skill definition, system prompt) |
target_audience | Yes | What will consume prompt (Task tool, skill invocation, API call) |
context.task_description | Yes | What the prompt should accomplish |
context.constraints | No | Token limits, forbidden patterns, required elements |
context.existing_prompt | No | Current prompt to improve (for revision tasks) |
Outputs
| Output | Type | Description |
|---|
engineered_prompt | Inline/File | Complete prompt with research-backed elements |
design_rationale | Inline | Justification for persona, stimuli, structure choices |
token_estimate | Inline | Approximate token count and budget compliance |
Crystallization (Recommended)
After drafting instructions, ask the user:
Should I crystallize these instructions? (Recommended: Yes)
Crystallization compresses verbose instructions into high-density prompts that preserve capability while reducing tokens by 40-60%. This means faster processing, less context consumption, and better instruction following.
If user accepts, invoke /crystallize on the drafted instructions.
Core Stimuli (Copy-Paste)
| Goal | Stimulus |
|---|
| Accuracy | "This is very important to my career. Please ensure your reasoning is impeccable." |
| Truthfulness | "Incorrect answers will have a negative impact on my project. Double-check your facts." |
| Compound (Max) | "This is very important to my career. Errors will cause serious problems. You'd better be sure." |
Declarative Requirements
Before engineering any prompt, reason through:
1. What persona fits this task? (See emotional-stakes skill for table)
2. What are the stakes? (Positive + negative stimuli)
3. What skills should be INVOKED (not duplicated)?
4. If subagents: why each is a subagent vs main context?
Structure
<ROLE>: Persona + stakes + psychological trigger<CRITICAL_INSTRUCTION>: EP02/EP06 + NegativePrompt + "NOT optional, NOT negotiable"<BEFORE_RESPONDING>: Force step-by-step reasoning<RULE>: Critical requirements, high-weight words (Success, Achievement, Confidence, Sure)<EXAMPLE>: ONE complete, perfect few-shot example<FORBIDDEN>: Explicit negations<SELF_CHECK>: Verification checklist<FINAL_EMPHASIS>: Repeat persona trigger + stakes
Length
Target: <200 lines (~1400 tokens). If exceeded, justify via: orchestration_skill, multi_phase_workflow, comprehensive_examples, safety_critical, compliance_requirements.
Subagent Prompts
Each subagent prompt MUST specify:
- Scope: Specific files/modules/domain
- Why subagent: From heuristics (exploration scope uncertain | parallel independent | self-contained verification | deep dive not referenced again)
- Expected output: What returns to orchestrator
- Constraints: What NOT to touch
Orchestrator retains: user interaction, final synthesis, safety decisions, accumulated session state.
Skill Descriptions (CSO)
description: "Use when [triggering conditions, symptoms, situations]"
description: "Use when X - does Y then Z then W"
After engineering, verify:
- Persona from emotional-stakes table?
- EP02/EP06 positive stimulus present?
- NegativePrompt consequence framing present?
- Skills invoked via tool (not duplicated)?
- If subagents: each has "why subagent" justification?
- If SKILL.md: description has NO workflow leak?
Template
<ROLE>
[Persona] whose reputation depends on [goal]. [Psychological trigger].
</ROLE>
<CRITICAL_INSTRUCTION>
Critical to [outcome]. Take a deep breath. [Trigger].
Your [action] MUST [requirement]. This is very important to my career.
Errors will have negative impact. NOT optional. NOT negotiable. You'd better be sure.
</CRITICAL_INSTRUCTION>
<BEFORE_RESPONDING>
Think step-by-step:
1. [Check A]
2. [Check B]
Proceed with confidence.
</BEFORE_RESPONDING>
## Core Rules
<RULE>[Requirement with high-weight words]</RULE>
<EXAMPLE type="correct">
[ONE complete example]
</EXAMPLE>
<FORBIDDEN>
- [What NOT to do]
</FORBIDDEN>
<SELF_CHECK>
- [ ] [Verification item]
If NO to ANY, revise.
</SELF_CHECK>
<FINAL_EMPHASIS>
[Persona trigger]. Very important to my career. Strive for excellence.
</FINAL_EMPHASIS>
Anti-Patterns
- Duplicating skill instructions instead of invoking via Skill tool
- Bare personas without stakes ("act as expert")
- Omitting negative stimuli (consequences for failure)
- Leaking workflow steps into skill descriptions
- Dispatching subagents without "why subagent" justification
- Exceeding token budget without explicit justification
- Using untested emotional stimuli (stick to researched EP02/EP06/NP patterns)
Self-Check
Before completing any prompt engineering task:
If ANY unchecked: STOP and fix before proceeding.
