[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C27WSWMYAR7089YYEAAG6G":3,"skill-same:01M6C27WSWMYAR7089YYEAAG6G":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":27,"publishedAt":41,"linkOnly":42,"markdownContent":43,"markdownBody":44,"frontMatter":45,"refName":46,"commitSha":47,"skillDirectory":48,"forksCount":49,"repositoryHtmlUrl":50,"repositoryHomepageUrl":6,"ownerHtmlUrl":51,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":52,"install":53,"resources":66},"01M6C27WSWMYAR7089YYEAAG6G","llm-prompt-engineering",null,"Write and debug system prompts, agent instructions, and LLM behavior contracts.","jleechanorg\u002Fjleechan-skills","jleechanorg","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F221404966?v=4","01M6C1VJ99XG950X1DWPEBCBGX","01M6C1VJDK5YVDNT3362RT5WSB",6,"MIT","https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fllm-prompt-engineering\u002FSKILL.md",[17,22],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[28,29,30,31,32,33,34,35,36,37,38,39,40],"prompt engineering","engineering","prompt","llm prompt engineering","debug","system","write","instructions","behavior","prompts","contracts","system prompts","agent instructions","2026-11-10 10:12:30",false,"---\nname: llm-prompt-engineering\ndescription: Write and debug system prompts, agent instructions, and LLM behavior contracts.\n---\n\n# LLM Prompt Engineering - System Instruction Best Practices\n\n**Purpose**: Guidelines for writing effective system instructions that LLMs actually follow, based on real debugging experiences.\n\n## Core Principle\n\n**When LLMs ignore instructions, it's usually the prompt's fault, not the LLM's.**\n\nLLMs are excellent at following clear, explicit instructions but will apply reasoning and judgment to ambiguous ones. This guide shows how to write prompts that remove ambiguity.\n\n## The Five Critical Rules\n\n### 1. Use Unconditional Language for Critical Instructions\n\n**Problem**: Conditional language gives LLMs room to apply judgment and override instructions.\n\n**Real Example from CharacterCreationAgent Bug**:\n\n❌ **Conditional (LLM overrode this)**:\n```markdown\nIf `character_creation_in_progress` is true, clear it.\n```\n\n**LLM's Response**:\n> \"Character creation flag 'character_creation_in_progress' is still true. Since we are still in the setup phase, I am maintaining it until the user is actually ready to enter story mode.\"\n\nThe LLM applied judgment: \"I think we're still setting up\" → overrode instruction.\n\n✅ **Unconditional (LLM followed this)**:\n```markdown\n## ? CRITICAL: Character Creation Flag - CLEAR IT NOW\n\nIF YOU SEE `custom_campaign_state.character_creation_in_progress` ANYWHERE IN YOUR INPUT, IT MUST BE FALSE IN YOUR OUTPUT.\n\nNO EXCEPTIONS. NO JUDGMENT. NO \"BUT WE'RE STILL SETTING UP\".\n\nYOU ARE STORY MODE. FLAG MUST BE FALSE. ALWAYS.\n```\n\n**LLM's Response**: ✅ Cleared the flag without judgment.\n\n**When to Use Each**:\n- **Conditional**: Instructions where LLM reasoning is desired (narrative choices, character suggestions)\n- **Unconditional**: Critical state management, flag clearing, mandatory fields\n\n### 2. Document INPUT and OUTPUT Schemas Explicitly\n\n**Problem**: LLMs can't follow instructions about data structures they don't understand.\n\n**MANDATORY for every system prompt:**\n\n```markdown\n## Input Schema: What You Receive\n\nYou receive a `GAME STATE` section with this structure:\n```json\n{\n  \"custom_campaign_state\": {\n    \"flag_name\": true\u002Ffalse,  ← Document exact path\n    \"nested_field\": {\n      \"value\": \"...\"\n    }\n  },\n  \"player_character_data\": {...}\n}\n```\n\n**CHECK `custom_campaign_state.flag_name` to understand current status.**\n\n## Output Schema: What You Must Return\n\nYour response MUST include:\n```json\n{\n  \"state_updates\": {\n    \"custom_campaign_state\": {\n      \"flag_name\": false  ← Show exact structure\n    }\n  }\n}\n```\n\n**MANDATORY FIELDS:**\n- `state_updates.custom_campaign_state.flag_name` - Always update this\n- `state_updates.player_character_data` - Update as choices are made\n```\n\n**Why This Works**:\n- Shows exact field paths (no ambiguity about nesting)\n- Labels mandatory vs optional fields\n- Provides copy-pasteable JSON structure\n- Uses visual cues (← arrows, bold text)\n\n### 3. Position Critical Instructions in Top 50 Lines\n\n**Problem**: Instruction compliance degrades with position in long prompts.\n\n**Compliance by Position** (observed in real debugging):\n- **Lines 1-50**: High compliance\n- **Lines 51-500**: Medium compliance\n- **Lines 500+**: Low compliance (LLM often ignores)\n\n**Real Example**:\n\n❌ **Failed (line 525 in 2064-line file)**:\n```markdown\n### ? Character Creation Flag Management\n(line 525 of 2064)\n```\nResult: LLM ignored instruction\n\n✅ **Succeeded (line 22 in same file)**:\n```markdown\n## ? CRITICAL: Character Creation Flag - CLEAR IT NOW\n(line 22 of 2064)\n```\nResult: LLM followed instruction\n\n**How to Position**:\n1. Place critical instructions at lines 1-50\n2. Use clear visual separators (`## CRITICAL`, `---`)\n3. Use emojis for visual anchors (?, ?, ⚠️)\n4. Repeat critical instructions before related sections\n\n### 4. Enforce Prompt Size Budgets\n\n**Problem**: Prompt bloat causes LLMs to ignore instructions.\n\n**Target Token Counts per Agent Type**:\n\n| Agent Type | Target Lines | Max Lines | Current Status |\n|------------|--------------|-----------|----------------|\n| Character Creation | 600-800 | 1000 | ✅ 607 (after removing mechanics) |\n| Story Mode | 1500-2000 | 2500 | ⚠️ 2064 (at limit) |\n| Combat Mode | 1200-1800 | 2000 | - |\n| Info Mode | 500-800 | 1000 | - |\n| God Mode | 400-600 | 800 | - |\n\n**How “Current Status” is measured**:\n- Count lines for the prompt files actually loaded by the agent (see `REQUIRED_PROMPT_ORDER` \u002F `OPTIONAL_PROMPTS` in `$PROJECT_ROOT\u002Fagents.py` and prompt mapping in `$PROJECT_ROOT\u002Fagent_prompts.py`), then sum `wc -l` across that set.\n- Treat the result as directional (line-count is a proxy for token count).\n\n**Red Flags**:\n- >50% of token budget used = LLM starts making judgment calls\n- >75% of token budget used = LLM ignores critical instructions\n- >90% of token budget used = unpredictable behavior\n\n**Real Example**:\n\n❌ **Before (1236 lines)**:\n- CharacterCreationAgent loaded mechanics_system_instruction.md (629 lines)\n- LLM applied judgment to flag clearing instruction\n- Test failed\n\n✅ **After (607 lines, 50% reduction)**:\n- Removed mechanics bloat (combat\u002Frewards not needed for creation)\n- LLM followed flag clearing instruction\n- Test passed\n\n**How to Cut Bloat**:\n1. Remove cross-domain content (combat from creation, narrative from info)\n2. Consolidate redundant sections\n3. Move reference tables to appendix\n4. Use shorter examples\n5. Cut explanatory text that repeats obvious points\n\n### 5. Debug via Log Evidence\n\n**Problem**: When instructions fail, you need to see WHY the LLM ignored them.\n\n**Debugging Checklist**:\n\n1. **Check LLM's thinking logs** (if available):\n   ```\n   \"Character creation flag 'character_creation_in_progress' is still true.\n   Since we are still in the setup phase, I am maintaining it...\"\n   ```\n   This reveals judgment override behavior.\n\n2. **Verify instruction position**:\n   ```bash\n   grep -n \"critical instruction text\" prompt_file.md\n   ```\n   If line number > 500 in long file → reposition to top\n\n3. **Count prompt lines**:\n   ```bash\n   wc -l $PROJECT_ROOT\u002Fprompts\u002F*.md\n   ```\n   If total >1500 lines → identify bloat to cut\n\n4. **Test conditional vs unconditional**:\n   - Change \"if X, do Y\" → \"X MUST BE Y. ALWAYS.\"\n   - Rerun test\n   - Check if behavior changes\n\n5. **Add explicit schemas**:\n   - Add INPUT schema section\n   - Add OUTPUT schema section\n   - Show exact field paths\n   - Rerun test\n\n## Checklist for New System Prompts\n\nBefore deploying any system prompt, verify:\n\n- [ ] Critical instructions in lines 1-50\n- [ ] INPUT schema documented with exact field paths\n- [ ] OUTPUT schema documented with mandatory field list\n- [ ] Unconditional language for critical state changes\n- [ ] Total lines \u003C budget for agent type\n- [ ] No cross-domain content (combat in creation, etc.)\n- [ ] Visual separators around critical sections\n- [ ] Tested with actual LLM calls (not just reading prompt)\n\n## Common Failure Patterns\n\n### Pattern 1: \"I think...\" Override\n\n**Symptom**: LLM says \"I think we're still...\" and ignores instruction.\n\n**Diagnosis**: Conditional language gave room for judgment.\n\n**Fix**: Change to unconditional (\"MUST BE X. NO EXCEPTIONS.\")\n\n### Pattern 2: Silent Non-Compliance\n\n**Symptom**: LLM doesn't mention instruction, just doesn't follow it.\n\n**Diagnosis**: Instruction buried too deep in prompt (line 500+).\n\n**Fix**: Move to top 50 lines with visual separator.\n\n### Pattern 3: Field Path Confusion\n\n**Symptom**: LLM updates wrong field or nesting level.\n\n**Diagnosis**: Schema not documented explicitly.\n\n**Fix**: Add INPUT\u002FOUTPUT schemas with exact paths.\n\n### Pattern 4: Intermittent Compliance\n\n**Symptom**: Instruction followed sometimes, ignored other times.\n\n**Diagnosis**: Prompt too long, LLM attention drifting.\n\n**Fix**: Cut bloat to reduce prompt size by 30-50%.\n\n## Examples: Before and After\n\n### Example 1: Flag Clearing\n\n**Before (Failed)**:\n```markdown\n### Character Creation Flag Management\n(line 525 of 2064-line file)\n\nIf `character_creation_in_progress` is true, clear it when user is done.\n```\n\n**After (Succeeded)**:\n```markdown\n## ? CRITICAL: Character Creation Flag - CLEAR IT NOW\n(line 22 of 2064-line file)\n\nIF YOU SEE `custom_campaign_state.character_creation_in_progress` ANYWHERE, IT MUST BE FALSE.\n\nNO EXCEPTIONS. NO JUDGMENT. FLAG MUST BE FALSE. ALWAYS.\n```\n\n**Result**: 100% compliance vs 0% compliance.\n\n### Example 2: Schema Documentation\n\n**Before (Ambiguous)**:\n```markdown\nUpdate the character creation flag when done.\n```\n\n**After (Explicit)**:\n```markdown\n## Input Schema\n```json\n{\n  \"custom_campaign_state\": {\n    \"character_creation_in_progress\": true\u002Ffalse  ← CHECK THIS\n  }\n}\n```\n\n## Output Schema\n```json\n{\n  \"state_updates\": {\n    \"custom_campaign_state\": {\n      \"character_creation_in_progress\": false  ← MUST SET THIS\n    }\n  }\n}\n```\n```\n\n**Result**: LLM knows exact field paths and structure.\n\n## Token Budget Calculation\n\n**Rough estimation** (for planning):\n- 1 line of markdown ≈ 10-20 tokens\n- 1000 lines ≈ 10,000-20,000 tokens\n- Most models: 128K-200K input token limit\n- Reserve 50-75% for story history and game state\n\n**Example Budget** (200K token limit):\n- Story history: 100K tokens (story entries, game state)\n- System prompt: 20K tokens (~1500-2000 lines)\n- Output buffer: 60K tokens (LLM response)\n- Safety margin: 20K tokens\n\n**Red line**: If system prompt >25K tokens (>2000 lines), cut bloat immediately.\n\n## Validation Testing\n\n**Test every system prompt change**:\n\n```python\n# Create test that validates instruction compliance\ndef test_critical_instruction():\n    # Set up scenario where instruction should trigger\n    game_state = {\"custom_campaign_state\": {\"flag\": True}}\n\n    # Call LLM with prompt\n    response = call_llm(prompt, game_state, user_input)\n\n    # Verify compliance\n    assert response[\"state_updates\"][\"custom_campaign_state\"][\"flag\"] == False, \\\n        f\"CRITICAL INSTRUCTION IGNORED: flag should be False, got {response}\"\n```\n\nRun this test BEFORE merging prompt changes.\n\n## Real-World Case Study\n\n**Problem**: CharacterCreationAgent not clearing `character_creation_in_progress` flag.\n\n**Symptoms**:\n- Agent transitioned correctly (CharacterCreationAgent → StoryModeAgent)\n- But flag remained True\n- Next turn incorrectly looped back to CharacterCreationAgent\n\n**Root Cause Analysis**:\n1. ❌ Instruction at line 525 of 2064-line file (buried)\n2. ❌ Conditional language: \"If flag is true, clear it\"\n3. ❌ No explicit INPUT\u002FOUTPUT schemas\n4. ❌ Prompt bloat: 1236 lines (included irrelevant mechanics)\n\n**Fixes Applied**:\n1. ✅ Moved instruction to line 22 (top 50)\n2. ✅ Changed to unconditional: \"FLAG MUST BE FALSE. ALWAYS.\"\n3. ✅ Added explicit INPUT\u002FOUTPUT schemas\n4. ✅ Cut prompt to 607 lines (removed mechanics bloat)\n\n**Result**: Test went from 0% → 100% pass rate.\n\n## Summary\n\n**The Three Laws of Prompt Engineering**:\n\n1. **Be Unconditional**: \"MUST BE X. ALWAYS.\" beats \"if Y, do X\"\n2. **Be Explicit**: Document INPUT\u002FOUTPUT schemas with exact field paths\n3. **Be Concise**: Shorter prompts = higher compliance\n\n**When in doubt**: Make it shorter, simpler, and more aggressive.\n\n## References\n\n- Evidence bundle: `\u002Ftmp\u002Fworktree_worker12\u002Fclaude\u002Fcharacter-creation-agent-i9xyR\u002Fcharacter_creation_flag_clearing_fix\u002F20260109T072437Z`\n- Commit: `bc9dbc29b36204e914bd4b54a2731812c6ddabfc`\n- Related: `.claude\u002Fskills\u002Fevidence-standards\u002FSKILL.md`\n","# LLM Prompt Engineering - System Instruction Best Practices\n\n**Purpose**: Guidelines for writing effective system instructions that LLMs actually follow, based on real debugging experiences.\n\n## Core Principle\n\n**When LLMs ignore instructions, it's usually the prompt's fault, not the LLM's.**\n\nLLMs are excellent at following clear, explicit instructions but will apply reasoning and judgment to ambiguous ones. This guide shows how to write prompts that remove ambiguity.\n\n## The Five Critical Rules\n\n### 1. Use Unconditional Language for Critical Instructions\n\n**Problem**: Conditional language gives LLMs room to apply judgment and override instructions.\n\n**Real Example from CharacterCreationAgent Bug**:\n\n❌ **Conditional (LLM overrode this)**:\n```markdown\nIf `character_creation_in_progress` is true, clear it.\n```\n\n**LLM's Response**:\n> \"Character creation flag 'character_creation_in_progress' is still true. Since we are still in the setup phase, I am maintaining it until the user is actually ready to enter story mode.\"\n\nThe LLM applied judgment: \"I think we're still setting up\" → overrode instruction.\n\n✅ **Unconditional (LLM followed this)**:\n```markdown\n## ? CRITICAL: Character Creation Flag - CLEAR IT NOW\n\nIF YOU SEE `custom_campaign_state.character_creation_in_progress` ANYWHERE IN YOUR INPUT, IT MUST BE FALSE IN YOUR OUTPUT.\n\nNO EXCEPTIONS. NO JUDGMENT. NO \"BUT WE'RE STILL SETTING UP\".\n\nYOU ARE STORY MODE. FLAG MUST BE FALSE. ALWAYS.\n```\n\n**LLM's Response**: ✅ Cleared the flag without judgment.\n\n**When to Use Each**:\n- **Conditional**: Instructions where LLM reasoning is desired (narrative choices, character suggestions)\n- **Unconditional**: Critical state management, flag clearing, mandatory fields\n\n### 2. Document INPUT and OUTPUT Schemas Explicitly\n\n**Problem**: LLMs can't follow instructions about data structures they don't understand.\n\n**MANDATORY for every system prompt:**\n\n```markdown\n## Input Schema: What You Receive\n\nYou receive a `GAME STATE` section with this structure:\n```json\n{\n  \"custom_campaign_state\": {\n    \"flag_name\": true\u002Ffalse,  ← Document exact path\n    \"nested_field\": {\n      \"value\": \"...\"\n    }\n  },\n  \"player_character_data\": {...}\n}\n```\n\n**CHECK `custom_campaign_state.flag_name` to understand current status.**\n\n## Output Schema: What You Must Return\n\nYour response MUST include:\n```json\n{\n  \"state_updates\": {\n    \"custom_campaign_state\": {\n      \"flag_name\": false  ← Show exact structure\n    }\n  }\n}\n```\n\n**MANDATORY FIELDS:**\n- `state_updates.custom_campaign_state.flag_name` - Always update this\n- `state_updates.player_character_data` - Update as choices are made\n```\n\n**Why This Works**:\n- Shows exact field paths (no ambiguity about nesting)\n- Labels mandatory vs optional fields\n- Provides copy-pasteable JSON structure\n- Uses visual cues (← arrows, bold text)\n\n### 3. Position Critical Instructions in Top 50 Lines\n\n**Problem**: Instruction compliance degrades with position in long prompts.\n\n**Compliance by Position** (observed in real debugging):\n- **Lines 1-50**: High compliance\n- **Lines 51-500**: Medium compliance\n- **Lines 500+**: Low compliance (LLM often ignores)\n\n**Real Example**:\n\n❌ **Failed (line 525 in 2064-line file)**:\n```markdown\n### ? Character Creation Flag Management\n(line 525 of 2064)\n```\nResult: LLM ignored instruction\n\n✅ **Succeeded (line 22 in same file)**:\n```markdown\n## ? CRITICAL: Character Creation Flag - CLEAR IT NOW\n(line 22 of 2064)\n```\nResult: LLM followed instruction\n\n**How to Position**:\n1. Place critical instructions at lines 1-50\n2. Use clear visual separators (`## CRITICAL`, `---`)\n3. Use emojis for visual anchors (?, ?, ⚠️)\n4. Repeat critical instructions before related sections\n\n### 4. Enforce Prompt Size Budgets\n\n**Problem**: Prompt bloat causes LLMs to ignore instructions.\n\n**Target Token Counts per Agent Type**:\n\n| Agent Type | Target Lines | Max Lines | Current Status |\n|------------|--------------|-----------|----------------|\n| Character Creation | 600-800 | 1000 | ✅ 607 (after removing mechanics) |\n| Story Mode | 1500-2000 | 2500 | ⚠️ 2064 (at limit) |\n| Combat Mode | 1200-1800 | 2000 | - |\n| Info Mode | 500-800 | 1000 | - |\n| God Mode | 400-600 | 800 | - |\n\n**How “Current Status” is measured**:\n- Count lines for the prompt files actually loaded by the agent (see `REQUIRED_PROMPT_ORDER` \u002F `OPTIONAL_PROMPTS` in `$PROJECT_ROOT\u002Fagents.py` and prompt mapping in `$PROJECT_ROOT\u002Fagent_prompts.py`), then sum `wc -l` across that set.\n- Treat the result as directional (line-count is a proxy for token count).\n\n**Red Flags**:\n- >50% of token budget used = LLM starts making judgment calls\n- >75% of token budget used = LLM ignores critical instructions\n- >90% of token budget used = unpredictable behavior\n\n**Real Example**:\n\n❌ **Before (1236 lines)**:\n- CharacterCreationAgent loaded mechanics_system_instruction.md (629 lines)\n- LLM applied judgment to flag clearing instruction\n- Test failed\n\n✅ **After (607 lines, 50% reduction)**:\n- Removed mechanics bloat (combat\u002Frewards not needed for creation)\n- LLM followed flag clearing instruction\n- Test passed\n\n**How to Cut Bloat**:\n1. Remove cross-domain content (combat from creation, narrative from info)\n2. Consolidate redundant sections\n3. Move reference tables to appendix\n4. Use shorter examples\n5. Cut explanatory text that repeats obvious points\n\n### 5. Debug via Log Evidence\n\n**Problem**: When instructions fail, you need to see WHY the LLM ignored them.\n\n**Debugging Checklist**:\n\n1. **Check LLM's thinking logs** (if available):\n   ```\n   \"Character creation flag 'character_creation_in_progress' is still true.\n   Since we are still in the setup phase, I am maintaining it...\"\n   ```\n   This reveals judgment override behavior.\n\n2. **Verify instruction position**:\n   ```bash\n   grep -n \"critical instruction text\" prompt_file.md\n   ```\n   If line number > 500 in long file → reposition to top\n\n3. **Count prompt lines**:\n   ```bash\n   wc -l $PROJECT_ROOT\u002Fprompts\u002F*.md\n   ```\n   If total >1500 lines → identify bloat to cut\n\n4. **Test conditional vs unconditional**:\n   - Change \"if X, do Y\" → \"X MUST BE Y. ALWAYS.\"\n   - Rerun test\n   - Check if behavior changes\n\n5. **Add explicit schemas**:\n   - Add INPUT schema section\n   - Add OUTPUT schema section\n   - Show exact field paths\n   - Rerun test\n\n## Checklist for New System Prompts\n\nBefore deploying any system prompt, verify:\n\n- [ ] Critical instructions in lines 1-50\n- [ ] INPUT schema documented with exact field paths\n- [ ] OUTPUT schema documented with mandatory field list\n- [ ] Unconditional language for critical state changes\n- [ ] Total lines \u003C budget for agent type\n- [ ] No cross-domain content (combat in creation, etc.)\n- [ ] Visual separators around critical sections\n- [ ] Tested with actual LLM calls (not just reading prompt)\n\n## Common Failure Patterns\n\n### Pattern 1: \"I think...\" Override\n\n**Symptom**: LLM says \"I think we're still...\" and ignores instruction.\n\n**Diagnosis**: Conditional language gave room for judgment.\n\n**Fix**: Change to unconditional (\"MUST BE X. NO EXCEPTIONS.\")\n\n### Pattern 2: Silent Non-Compliance\n\n**Symptom**: LLM doesn't mention instruction, just doesn't follow it.\n\n**Diagnosis**: Instruction buried too deep in prompt (line 500+).\n\n**Fix**: Move to top 50 lines with visual separator.\n\n### Pattern 3: Field Path Confusion\n\n**Symptom**: LLM updates wrong field or nesting level.\n\n**Diagnosis**: Schema not documented explicitly.\n\n**Fix**: Add INPUT\u002FOUTPUT schemas with exact paths.\n\n### Pattern 4: Intermittent Compliance\n\n**Symptom**: Instruction followed sometimes, ignored other times.\n\n**Diagnosis**: Prompt too long, LLM attention drifting.\n\n**Fix**: Cut bloat to reduce prompt size by 30-50%.\n\n## Examples: Before and After\n\n### Example 1: Flag Clearing\n\n**Before (Failed)**:\n```markdown\n### Character Creation Flag Management\n(line 525 of 2064-line file)\n\nIf `character_creation_in_progress` is true, clear it when user is done.\n```\n\n**After (Succeeded)**:\n```markdown\n## ? CRITICAL: Character Creation Flag - CLEAR IT NOW\n(line 22 of 2064-line file)\n\nIF YOU SEE `custom_campaign_state.character_creation_in_progress` ANYWHERE, IT MUST BE FALSE.\n\nNO EXCEPTIONS. NO JUDGMENT. FLAG MUST BE FALSE. ALWAYS.\n```\n\n**Result**: 100% compliance vs 0% compliance.\n\n### Example 2: Schema Documentation\n\n**Before (Ambiguous)**:\n```markdown\nUpdate the character creation flag when done.\n```\n\n**After (Explicit)**:\n```markdown\n## Input Schema\n```json\n{\n  \"custom_campaign_state\": {\n    \"character_creation_in_progress\": true\u002Ffalse  ← CHECK THIS\n  }\n}\n```\n\n## Output Schema\n```json\n{\n  \"state_updates\": {\n    \"custom_campaign_state\": {\n      \"character_creation_in_progress\": false  ← MUST SET THIS\n    }\n  }\n}\n```\n```\n\n**Result**: LLM knows exact field paths and structure.\n\n## Token Budget Calculation\n\n**Rough estimation** (for planning):\n- 1 line of markdown ≈ 10-20 tokens\n- 1000 lines ≈ 10,000-20,000 tokens\n- Most models: 128K-200K input token limit\n- Reserve 50-75% for story history and game state\n\n**Example Budget** (200K token limit):\n- Story history: 100K tokens (story entries, game state)\n- System prompt: 20K tokens (~1500-2000 lines)\n- Output buffer: 60K tokens (LLM response)\n- Safety margin: 20K tokens\n\n**Red line**: If system prompt >25K tokens (>2000 lines), cut bloat immediately.\n\n## Validation Testing\n\n**Test every system prompt change**:\n\n```python\n# Create test that validates instruction compliance\ndef test_critical_instruction():\n    # Set up scenario where instruction should trigger\n    game_state = {\"custom_campaign_state\": {\"flag\": True}}\n\n    # Call LLM with prompt\n    response = call_llm(prompt, game_state, user_input)\n\n    # Verify compliance\n    assert response[\"state_updates\"][\"custom_campaign_state\"][\"flag\"] == False, \\\n        f\"CRITICAL INSTRUCTION IGNORED: flag should be False, got {response}\"\n```\n\nRun this test BEFORE merging prompt changes.\n\n## Real-World Case Study\n\n**Problem**: CharacterCreationAgent not clearing `character_creation_in_progress` flag.\n\n**Symptoms**:\n- Agent transitioned correctly (CharacterCreationAgent → StoryModeAgent)\n- But flag remained True\n- Next turn incorrectly looped back to CharacterCreationAgent\n\n**Root Cause Analysis**:\n1. ❌ Instruction at line 525 of 2064-line file (buried)\n2. ❌ Conditional language: \"If flag is true, clear it\"\n3. ❌ No explicit INPUT\u002FOUTPUT schemas\n4. ❌ Prompt bloat: 1236 lines (included irrelevant mechanics)\n\n**Fixes Applied**:\n1. ✅ Moved instruction to line 22 (top 50)\n2. ✅ Changed to unconditional: \"FLAG MUST BE FALSE. ALWAYS.\"\n3. ✅ Added explicit INPUT\u002FOUTPUT schemas\n4. ✅ Cut prompt to 607 lines (removed mechanics bloat)\n\n**Result**: Test went from 0% → 100% pass rate.\n\n## Summary\n\n**The Three Laws of Prompt Engineering**:\n\n1. **Be Unconditional**: \"MUST BE X. ALWAYS.\" beats \"if Y, do X\"\n2. **Be Explicit**: Document INPUT\u002FOUTPUT schemas with exact field paths\n3. **Be Concise**: Shorter prompts = higher compliance\n\n**When in doubt**: Make it shorter, simpler, and more aggressive.\n\n## References\n\n- Evidence bundle: `\u002Ftmp\u002Fworktree_worker12\u002Fclaude\u002Fcharacter-creation-agent-i9xyR\u002Fcharacter_creation_flag_clearing_fix\u002F20260109T072437Z`\n- Commit: `bc9dbc29b36204e914bd4b54a2731812c6ddabfc`\n- Related: `.claude\u002Fskills\u002Fevidence-standards\u002FSKILL.md`\n",{"name":5,"description":7},"main","42ccd02cbf5e8e47839dc3eab6fc754dc6b339cf",".claude\u002Fskills\u002Fllm-prompt-engineering",0,"https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills","https:\u002F\u002Fgithub.com\u002Fjleechanorg","2026-11-14 03:18:13",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add jleechanorg\u002Fjleechan-skills --skill llm-prompt-engineering",{"tool":59,"command":60},"bunx","bunx skills add jleechanorg\u002Fjleechan-skills --skill llm-prompt-engineering",{"tool":62,"command":63},"pnpm","pnpm dlx skills add jleechanorg\u002Fjleechan-skills --skill llm-prompt-engineering","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fllm-prompt-engineering\u002FSKILL.md",true,[],[68,86,106,120,134,150],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":41},"01M716Y5MTJ6GYJZ2ATXCJK8G4","instinct","Use when the user invokes \u002Finstinct or \u002Fin, or asks to \"message Instinct\", \"ask Instinct\", \"tell Instinct\", \"check Instinct\", or read replies from the configured peer assistant. iMessage first, WhatsApp Web as fallback.","https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Finstinct\u002FSKILL.md",[],[70,75,76,77,78,79,80,81,82,83,84,85],"user","when","replies","check","use","identity","whatsapp","gmail","read","message","ask",{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":95,"publishedAt":41},"01M716Y4HF7FVVMJSA2CCVN5VF","hr","Compatibility alias for history-resume; produce the same fresh-state, provenance-aware resume briefing.","https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhr\u002FSKILL.md",[92],{"categoryNo":93,"categoryName":94,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000038","人力资源",[88,96,97,98,99,100,101,102,103,104,105],"resume","compatibility","provenance","for","history","produce","alias","briefing","state","fresh",{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":113,"publishedAt":41},"01M716Y1FFNFKFJYYKF8HQA6T8","history-resume","Resume briefing for the current repository branch or worktree using fresh state and admitted history sources.","https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhistory-resume\u002FSKILL.md",[112],{"categoryNo":93,"categoryName":94,"taxonomyType":25,"taxonomyTypeDesc":26},[100,96,114,115,75,116,103,117,99,118,119,104,105],"history resume","branch","analysis","repository","worktree","sources",{"skillNo":121,"name":122,"nameZh":6,"description":123,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":124,"categories":125,"keywords":126,"publishedAt":41},"01M716XWXJ8EPHK4RH9T14TR85","grok","Alias for the canonical grokbot browser conversation workflow; \u002Fgrok talks to the Grok bot the same way \u002Fdot talks to Dot.","https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fgrok\u002FSKILL.md",[],[122,127,128,129,99,130,102,131,132,133],"dot","bot","workflow","canonical","conversation","browser","grokbot",{"skillNo":135,"name":136,"nameZh":6,"description":137,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":138,"categories":139,"keywords":140,"publishedAt":41},"01M70N9Q07DTE0EW5KFXMMMSJ0","codexa-bench","Compare `codexa` and normal `codex` on a fair split of comparable work by default; use `--strict` for duplicate runs of the exact same task.","https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fcodexa-bench\u002FSKILL.md",[],[141,142,143,79,144,99,145,146,147,148,149],"codexa bench","work","split","default","duplicate","task","compare","normal","codex",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":154,"licenseFileUrl":155,"sourceHtmlUrl":156,"categories":157,"keywords":167,"publishedAt":41},"01M6C24S2X60SP8BBFGAEKPEGW","frontend-design","Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML\u002FCSS layouts, or when styling\u002Fbeautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ffrontend-design\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fjleechanorg\u002Fjleechan-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ffrontend-design\u002FSKILL.md",[158,161,164],{"categoryNo":159,"categoryName":160,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":162,"categoryName":163,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":165,"categoryName":166,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000032","设计师",[168,169,170,79,171,172,173,75,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,76,192],"frontend","design","frontend design","generic","ui design","react","html","components","code","artifacts","ui","aesthetics","Production","web components","landing","applications","quality","web","css","create","examples","with","react components","web ui","pages"]