` tags to preserve breaks\n3. **Remove front/back matter** - Copyright and TOC pollute the dataset\n\n```python\n# Extract text from ePub paragraphs\nfrom epub2 import EPub\nfrom bs4 import BeautifulSoup\n\ndef extract_epub(path):\n book = EPub(path)\n chapters = []\n for item in book.flow:\n html = book.get_chapter(item.id)\n soup = BeautifulSoup(html, 'html.parser')\n paragraphs = [p.get_text().strip() for p in soup.find_all('p')]\n chapters.append('\\n\\n'.join(p for p in paragraphs if p))\n return '\\n\\n'.join(chapters)\n```\n\n## Phase 2: Intelligent Segmentation\n\n### Smaller Chunks + Overlap\n\nSmaller chunks (150-400 words) produce more training examples and better style transfer than larger chunks (250-650).\n\n```python\ndef segment(text, min_words=150, max_words=400):\n paragraphs = text.split('\\n\\n')\n chunks, buffer, buffer_words = [], [], 0\n \n for para in paragraphs:\n words = len(para.split())\n if buffer_words + words > max_words and buffer_words >= min_words:\n chunks.append('\\n\\n'.join(buffer))\n # Keep last paragraph for overlap\n buffer = [buffer[-1], para] if buffer else [para]\n buffer_words = sum(len(p.split()) for p in buffer)\n else:\n buffer.append(para)\n buffer_words += words\n \n if buffer:\n chunks.append('\\n\\n'.join(buffer))\n return chunks\n```\n\n### Expected Results\n\nFor an 86,000-word book:\n- Old method (250-650 words): ~150 chunks\n- New method (150-400 + overlap): ~300 chunks\n- With 2 variants per chunk: 600+ training examples\n\n## Phase 3: Diverse Instruction Generation\n\n### The Key Insight\n\nUsing a single prompt template causes memorization. Diverse templates teach the underlying style.\n\n```python\nSYSTEM_PROMPTS = [\n \"You are an expert creative writer capable of emulating specific literary styles.\",\n \"You are a literary writer with deep knowledge of classic prose styles.\",\n \"You are a creative writer skilled at emulating distinctive authorial voices.\",\n \"You write prose that captures the essence of modernist literature.\",\n \"You are a talented writer who can channel classic American authors.\",\n]\n\nPROMPT_TEMPLATES = [\n \"Write a passage in the style of {author}: {desc}\",\n \"Channel {author}'s voice to write about: {desc}\",\n \"In {author}'s distinctive prose style, describe: {desc}\",\n \"Write this scene as {author} would have: {desc}\",\n \"Using {author}'s repetitive technique, describe: {desc}\",\n \"Capture the rhythm of {author} in this passage: {desc}\",\n \"Write like {author}: {desc}\",\n \"In the voice of {author}, write: {desc}\",\n \"This is a literary exercise. Write like {author}: {desc}\",\n \"Can you write in {author}'s style? {desc}\",\n]\n```\n\n### Instruction Generation\n\n```python\nINSTRUCTION_PROMPT = \"\"\"Describe what is happening in this excerpt in 2-3 sentences.\nFocus on: characters present, actions, emotions, setting.\nDo NOT quote the text directly.\n\nExcerpt:\n{text}\n\"\"\"\n\n# Use a fast, cheap LLM (e.g., Gemini Flash)\ninstruction = llm_call(INSTRUCTION_PROMPT.format(text=chunk))\n```\n\n## Phase 4: Dataset Construction\n\n### Message Format\n\n```json\n{\n \"messages\": [\n {\"role\": \"system\", \"content\": \"You are an expert creative writer...\"},\n {\"role\": \"user\", \"content\": \"Write in the style of Author: Scene description...\"},\n {\"role\": \"assistant\", \"content\": \"The actual book text from chunk...\"}\n ]\n}\n```\n\n### Multiple Variants Per Chunk\n\n```python\ndef build_examples(chunk, instruction, author, variants=2):\n examples = []\n for i in range(variants):\n system = SYSTEM_PROMPTS[i % len(SYSTEM_PROMPTS)]\n template = PROMPT_TEMPLATES[(chunk.id + i) % len(PROMPT_TEMPLATES)]\n user = template.format(author=author, desc=instruction)\n examples.append({\"messages\": [\n {\"role\": \"system\", \"content\": system},\n {\"role\": \"user\", \"content\": user},\n {\"role\": \"assistant\", \"content\": chunk.text}\n ]})\n return examples\n```\n\n## Phase 5: LoRA Training on Tinker\n\n### Configuration\n\n```python\nCONFIG = {\n \"model_name\": \"Qwen/Qwen3-8B-Base\", # Base, not instruct\n \"lora_rank\": 32, # 352MB adapter\n \"learning_rate\": 5e-4, # Higher for LoRA\n \"batch_size\": 4,\n \"epochs\": 3,\n}\n```\n\n### Why Base Model?\n\nUse **base** (pretrained) models, not instruction-tuned versions:\n- Base models are more malleable for new styles\n- Instruct models have patterns that resist overwriting\n- Style is a low-level pattern that base models capture better\n\n### Training Loop\n\n```python\nimport tinker\nfrom tinker import types\n\ntraining_client = await service_client.create_lora_training_client_async(\n base_model=\"Qwen/Qwen3-8B-Base\",\n rank=32\n)\n\nfor epoch in range(3):\n for batch in batches:\n await training_client.forward_backward_async(batch, loss_fn=\"cross_entropy\")\n await training_client.optim_step_async(types.AdamParams(learning_rate=5e-4))\n\nresult = await training_client.save_weights_for_sampler_async(name=\"final\")\n```\n\n## Phase 6: Validation\n\n### Modern Scenario Test\n\nTest with scenarios that couldn't exist in the original book:\n\n```python\nTEST_PROMPTS = [\n \"Write about a barista making lattes\",\n \"Describe lovers communicating through text messages\",\n \"Write about someone anxious about climate change\",\n]\n```\n\nIf the model applies style markers to modern scenarios, it learned **style**, not **content**.\n\n### Originality Verification\n\n```bash\n# Search training data for output phrases\ngrep \"specific phrase from output\" dataset.jsonl\n# Should return: No matches\n```\n\n### AI Detector Testing\n\nTest outputs with GPTZero, Pangram, or ZeroGPT.\n\n## Known Issues and Solutions\n\n### Character Name Leakage\n\n**Symptom**: Model uses original character names in new scenarios.\n**Cause**: Limited name diversity from one book.\n**Solution**: Train on multiple books or add synthetic examples.\n\n### Model Parrots Exact Phrases\n\n**Symptom**: Outputs contain exact sentences from training data.\n**Cause**: Too few prompt variations or too many epochs.\n**Solution**: Use 15+ templates, limit to 3 epochs.\n\n### Fragmented Outputs\n\n**Symptom**: Sentences feel incomplete.\n**Cause**: Poor segmentation breaking mid-thought.\n**Solution**: Always break at paragraph boundaries.\n\n## Guidelines\n\n1. **Always source ePub over PDF** - OCR errors become learned patterns\n2. **Never break mid-sentence** - Boundaries must be grammatically complete\n3. **Use diverse prompts** - 15+ templates, 5+ system prompts\n4. **Use base models** - Not instruct versions\n5. **Use smaller chunks** - 150-400 words for more examples\n6. **Reserve test set** - 50 examples minimum\n7. **Test on modern scenarios** - Proves style transfer vs memorization\n8. **Verify originality** - Grep training data for output phrases\n\n## Expected Results\n\n| Metric | Value |\n|--------|-------|\n| Training examples | 500-1000 per book |\n| Model | Qwen/Qwen3-8B-Base |\n| LoRA rank | 32 |\n| Adapter size | ~350 MB |\n| Training time | ~15 min |\n| Loss reduction | 90%+ |\n| Style transfer success | ~50% perfect |\n\n## Cost Estimate\n\n| Component | Cost |\n|-----------|------|\n| LLM (instruction generation) | ~$0.50 |\n| Tinker training (15 min) | ~$1.50 |\n| **Total** | **~$2.00** |\n\n## Integration with Context Engineering Skills\n\nThis example applies several skills from the Agent Skills for Context Engineering collection:\n\n### project-development\nThe pipeline follows the staged, idempotent architecture pattern:\n- **Acquire**: Extract text from ePub\n- **Prepare**: Segment into training chunks\n- **Process**: Generate synthetic instructions\n- **Parse**: Build message format\n- **Render**: Output Tinker-compatible JSONL\n- **Train**: LoRA fine-tuning\n- **Validate**: Modern scenario testing\n\nEach phase is resumable and produces intermediate artifacts for debugging.\n\n### context-compression\nSegmentation is a form of context compression for training. The core insight from context-compression applies: information density matters more than information quantity. Smaller, coherent chunks (150-400 words) produce better style transfer than larger, diluted chunks.\n\nThe two-tier strategy mirrors context compression evaluation:\n- Tier 1: Fast, deterministic compression\n- Tier 2: LLM-assisted for edge cases\n\n### multi-agent-patterns\nThe pipeline uses the **supervisor/orchestrator** pattern:\n- Orchestrator coordinates phases and manages state\n- Specialized agents (Extraction, Segmentation, Instruction, Builder) have isolated contexts\n- Each agent receives only the information needed for its task\n\nThis matches the principle that sub-agents exist primarily to isolate context rather than simulate roles.\n\n### evaluation\nValidation follows the **end-state evaluation** pattern:\n- Functional testing: Does output match expected style markers?\n- Originality verification: Is content genuinely generated?\n- External validation: AI detector scores\n\nThe \"modern scenario\" test is a form of out-of-distribution evaluation that proves generalization.\n\n### context-fundamentals\nPrompt diversity prevents attention collapse on single patterns. When training with identical prompt structures, the model memorizes the instruction-response mapping. Diverse templates force attention across the style patterns themselves.\n\n## References\n\nInternal references:\n- [Segmentation Strategies](./references/segmentation-strategies.md) - Text chunking patterns\n- [Tinker Format Specification](./references/tinker-format.md) - Datum structure\n- [Tinker API Documentation](./references/tinker.txt) - Full API reference\n\nRelated skills from Agent Skills for Context Engineering:\n- project-development - Pipeline architecture patterns\n- context-compression - Compression strategies \n- multi-agent-patterns - Agent coordination\n- evaluation - Evaluation frameworks\n- context-fundamentals - Attention and information density\n\nExternal resources:\n- [Research Paper](https://arxiv.org/pdf/2510.13939) - Chakrabarty et al. 2025\n- [Dataset on Hugging Face](https://huggingface.co/datasets/MuratcanKoylan/gertrude-stein-style-sft)\n- [Gertrude Stein Case Study](./examples/gertrude-stein/) - Complete working example\n\n---\n\n## Skill Metadata\n\n**Created**: 2025-12-26\n**Last Updated**: 2025-12-28\n**Author**: Muratcan Koylan\n**Version**: 2.0.0\n**Standalone**: Yes (separate from main context-engineering collection)\n\nFile v1.0.0:examples/digital-brain-skill/SKILL.md\n\n---\nname: digital-brain\ndescription: This skill should be used when the user asks to \"write a post\", \"check my voice\", \"look up contact\", \"prepare for meeting\", \"weekly review\", \"track goals\", or mentions personal brand, content creation, network management, or voice consistency.\nversion: 1.0.0\n---\n\n# Digital Brain\n\nA structured personal operating system for managing digital presence, knowledge, relationships, and goals with AI assistance. Designed for founders building in public, content creators growing their audience, and tech-savvy professionals seeking AI-assisted personal management.\n\n**Important**: This skill uses progressive disclosure. Module-specific instructions are in each subdirectory's `.md` file. Only load what's needed for the current task.\n\n## When to Activate\n\nActivate this skill when the user:\n\n- Requests content creation (posts, threads, newsletters) - load identity/voice.md first\n- Asks for help with personal brand or positioning\n- Needs to look up or manage contacts/relationships\n- Wants to capture or develop content ideas\n- Requests meeting preparation or follow-up\n- Asks for weekly reviews or goal tracking\n- Needs to save or retrieve bookmarked resources\n- Wants to organize research or learning materials\n\n**Trigger phrases**: \"write a post\", \"my voice\", \"content ideas\", \"who is [name]\", \"prepare for meeting\", \"weekly review\", \"save this\", \"my goals\"\n\n## Core Concepts\n\n### Progressive Disclosure Architecture\n\nThe Digital Brain follows a three-level loading pattern:\n\n| Level | When Loaded | Content |\n|-------|-------------|---------|\n| **L1: Metadata** | Always | This SKILL.md overview |\n| **L2: Module Instructions** | On-demand | `[module]/[MODULE].md` files |\n| **L3: Data Files** | As-needed | `.jsonl`, `.yaml`, `.md` data |\n\n### File Format Strategy\n\nFormats chosen for optimal agent parsing:\n\n- **JSONL** (`.jsonl`): Append-only logs - ideas, posts, contacts, interactions\n- **YAML** (`.yaml`): Structured configs - goals, values, circles\n- **Markdown** (`.md`): Narrative content - voice, brand, calendar, todos\n- **XML** (`.xml`): Complex prompts - content generation templates\n\n### Append-Only Data Integrity\n\nJSONL files are **append-only**. Never delete entries:\n- Mark as `\"status\": \"archived\"` instead of deleting\n- Preserves history for pattern analysis\n- Enables \"what worked\" retrospectives\n\n## Detailed Topics\n\n### Module Overview\n\n```\ndigital-brain/\n├── identity/ → Voice, brand, values (READ FIRST for content)\n├── content/ → Ideas, drafts, posts, calendar\n├── knowledge/ → Bookmarks, research, learning\n├── network/ → Contacts, interactions, intros\n├── operations/ → Todos, goals, meetings, metrics\n└── agents/ → Automation scripts\n```\n\n### Identity Module (Critical for Content)\n\n**Always read `identity/voice.md` before generating any content.**\n\nContains:\n- `voice.md` - Tone, style, vocabulary, patterns\n- `brand.md` - Positioning, audience, content pillars\n- `values.yaml` - Core beliefs and principles\n- `bio-variants.md` - Platform-specific bios\n- `prompts/` - Reusable generation templates\n\n### Content Module\n\nPipeline: `ideas.jsonl` → `drafts/` → `posts.jsonl`\n\n- Capture ideas immediately to `ideas.jsonl`\n- Develop in `drafts/` using `templates/`\n- Log published content to `posts.jsonl` with metrics\n- Plan in `calendar.md`\n\n### Network Module\n\nPersonal CRM with relationship tiers:\n- `inner` - Weekly touchpoints\n- `active` - Bi-weekly touchpoints\n- `network` - Monthly touchpoints\n- `dormant` - Quarterly reactivation checks\n\n### Operations Module\n\nProductivity system with priority levels:\n- P0: Do today, blocking\n- P1: This week, important\n- P2: This month, valuable\n- P3: Backlog, nice to have\n\n## Practical Guidance\n\n### Content Creation Workflow\n\n```\n1. Read identity/voice.md (REQUIRED)\n2. Check identity/brand.md for topic alignment\n3. Reference content/posts.jsonl for successful patterns\n4. Use content/templates/ as starting structure\n5. Draft matching voice attributes\n6. Log to posts.jsonl after publishing\n```\n\n### Pre-Meeting Preparation\n\n```\n1. Look up contact: network/contacts.jsonl\n2. Get history: network/interactions.jsonl\n3. Check pending: operations/todos.md\n4. Generate brief with context\n```\n\n### Weekly Review Process\n\n```\n1. Run: python agents/scripts/weekly_review.py\n2. Review metrics in operations/metrics.jsonl\n3. Check stale contacts: agents/scripts/stale_contacts.py\n4. Update goals progress in operations/goals.yaml\n5. Plan next week in content/calendar.md\n```\n\n## Examples\n\n### Example: Writing an X Post\n\n**Input**: \"Help me write a post about AI agents\"\n\n**Process**:\n1. Read `identity/voice.md` → Extract voice attributes\n2. Check `identity/brand.md` → Confirm \"ai_agents\" is a content pillar\n3. Reference `content/posts.jsonl` → Find similar successful posts\n4. Draft post matching voice patterns\n5. Suggest adding to `content/ideas.jsonl` if not publishing immediately\n\n**Output**: Post draft in user's authentic voice with platform-appropriate format.\n\n### Example: Contact Lookup\n\n**Input**: \"Prepare me for my call with Sarah Chen\"\n\n**Process**:\n1. Search `network/contacts.jsonl` for \"Sarah Chen\"\n2. Get recent entries from `network/interactions.jsonl`\n3. Check `operations/todos.md` for pending items with Sarah\n4. Compile brief: role, context, last discussed, follow-ups\n\n**Output**: Pre-meeting brief with relationship context.\n\n## Guidelines\n\n1. **Voice First**: Always read `identity/voice.md` before any content generation\n2. **Append Only**: Never delete from JSONL files - archive instead\n3. **Update Timestamps**: Set `updated` field when modifying tracked data\n4. **Cross-Reference**: Knowledge informs content, network informs operations\n5. **Log Interactions**: Always log meetings/calls to `interactions.jsonl`\n6. **Preserve History**: Past content in `posts.jsonl` informs future performance\n\n## Integration\n\nThis skill integrates context engineering principles:\n\n- **context-fundamentals** - Progressive disclosure, attention budget management\n- **memory-systems** - JSONL for persistent memory, structured recall\n- **tool-design** - Scripts in `agents/scripts/` follow tool design principles\n- **context-optimization** - Module separation prevents context bloat\n\n## References\n\nInternal references:\n- [Identity Module](./identity/IDENTITY.md) - Voice and brand details\n- [Content Module](./content/CONTENT.md) - Content pipeline docs\n- [Network Module](./network/NETWORK.md) - CRM documentation\n- [Operations Module](./operations/OPERATIONS.md) - Productivity system\n- [Agent Scripts](./agents/AGENTS.md) - Automation documentation\n\nExternal resources:\n- [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)\n- [Anthropic Context Engineering Guide](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)\n\n---\n\n## Skill Metadata\n\n**Created**: 2024-12-29\n**Last Updated**: 2024-12-29\n**Author**: Murat Can Koylan\n**Version**: 1.0.0\n\nFile v1.0.0:examples/interleaved-thinking/generated_skills/comprehensive-research-agent/SKILL.md\n\n---\nname: comprehensive-research-agent\ndescription: \"Ensure thorough validation, error recovery, and transparent reasoning in research tasks with multiple tool calls\"\n---\n\n# Comprehensive Research Agent Best Practices\n\nThis skill addresses common failures in multi-step research tasks: unhandled tool errors, missing validation, opaque reasoning, and premature conclusions. It provides structured protocols for source validation, error recovery, and thinking transparency that significantly improves research quality and reliability.\n\n## When to Activate\n\n- Task involves web research with search, read_url, or fetch operations\n- Task requires gathering information from multiple sources\n- Task has explicit requirements for completeness or verification\n- Task includes file operations that need validation (save, write, read)\n- Any research or information-gathering workflow with 3+ tool interactions\n\n## Core Concepts\n\n- Validation Checkpoints: Explicit verification steps at phase transitions to confirm tool outputs, source relevance, and information completeness before proceeding\n- Error Recovery Protocols: Mandatory acknowledgment and handling of tool failures with fallback strategies rather than silent continuation\n- Source Traceability: Maintaining clear tracking of which sources were actually retrieved vs. referenced from prior knowledge to prevent hallucination\n- Substantive Thinking Blocks: Detailed reasoning traces that document insights, connections, gaps, and decision rationale at each step\n- Cross-Source Validation: Verifying key claims against multiple sources and explicitly noting consensus, contradictions, and information gaps\n\n## Patterns to Avoid\n\n- *Silent Tool Failure**: A tool call returns an error (404, timeout, invalid URL) but the agent proceeds without acknowledging it, potentially missing critical information. Always log failures and attempt recovery or document the gap.\n- *Vague Completion Claims**: Agent declares 'I have enough information' or 'research is comprehensive' without specifying what was learned, what sources support claims, or what gaps remain. Replace with specific summaries of coverage.\n- *Unvalidated Source Selection**: Agent reads URLs from search results without evaluating relevance, credibility, or recency first. This wastes tool calls on low-quality sources. Always rank and prioritize sources before deep reading.\n- *Generic Thinking Blocks**: Thinking contains only next-action descriptions ('Now I will search for X') without analysis of what was learned, how it connects to the goal, or what questions remain. Thinking should be substantive and reflective.\n- *Verification Method Error**: Using list_directory to verify file creation can produce false negatives due to caching. Always use read_file for actual content verification.\n- *Citation Without Retrieval**: Citing sources (URLs, paper titles) in the final report that were never successfully fetched or read. Track sources explicitly and prohibit citing unretrieved content.\n- *Redundant Tool Calls**: Making overlapping searches or reading sources without tracking what has already been obtained. Maintain a 'found resources' tracker to avoid duplication.\n\n## Recommended Practices\n\n- *Implement Pre-Reading Source Evaluation**: Before reading URLs, rank search results by relevance, credibility, recency, and authority. Document selection rationale in thinking blocks.\n- *Use Structured Thinking Blocks**: Each thinking block must include: (a) what was learned from the source/action, (b) how it connects to the research goal, (c) any contradictions/gaps identified, (d) strategic decisions made. Avoid generic next-action statements.\n- *Add Mandatory Error Acknowledgment**: When any tool fails, the next thinking block must explicitly address it: note the failure type, propose a recovery strategy (retry, alternative source, or documented gap), and explain the chosen approach.\n- *Create Pre-Completion Validation Checklist**: Before declaring research complete, verify: all required sections have specific evidence, all sources were successfully retrieved, key claims are cross-validated, and gaps are documented.\n- *Implement Cross-Source Validation**: After gathering information from multiple sources, explicitly compare findings. Note where sources agree, where they contradict, and what remains unverified. Use this to assess overall confidence.\n- *Maintain Source Tracking Table**: Create a simple table in thinking showing which URLs were fetched, which failed, and which were used for specific claims. Never cite unretrieved sources.\n- *Use Read_File for Verification**: When confirming file writes, use read_file to verify actual content rather than list_directory, which can have caching issues causing false negatives.\n- *Add Explicit Validation Phase**: After reading sources, write a brief synthesis that confirms usefulness, notes relevance to research goals, and identifies remaining gaps before proceeding to the next phase.\n\n## Guidelines\n\n1. After each tool call, explicitly check for errors in the response and acknowledge failures in the next thinking block with recovery strategy\n2. Before reading URLs, rank sources by relevance/credibility and document selection rationale - never read results without evaluation\n3. Thinking blocks must be 3-5+ sentences minimum and include: what was learned, connections to goal, gaps/contradictions, and next steps\n4. Create a pre-completion checklist verifying: all requirements covered, sources retrieved, claims validated, gaps documented\n5. Maintain source tracking - only cite URLs that were successfully fetched; prohibit citing unretrieved sources\n6. When writing final reports, include 'Limitations & Gaps' section documenting what was attempted but failed or what remains unverified\n7. Use read_file (not list_directory) to verify file content after save operations\n8. Cross-validate key claims across at least 2 sources when possible; explicitly note consensus or contradictions\n9. Track gathered information to avoid redundant searches - implement 'found resources' tracker for multi-phase research\n10. Replace vague 'comprehensive' statements with specific summaries: 'Covered X sources on Y topic; missing Z aspects'\n\n## Examples\n\n- **Before (Anti-Pattern)**: 'I searched for context engineering and found several results. Now I'll read some URLs and then write the report. I have enough information to proceed.'\n\n**After (Pattern)**: 'Search returned 15 results on context engineering. Evaluating relevance: Liu et al. (2024) appears most authoritative on 'lost in the middle' phenomenon; Anthropic documentation likely has current context window specs; Patel (2023) covers RAG best practices. Ranking these as top 3 priorities. Reading top result first. If the primary source fails (URL error), will try backup search for correct documentation URL and note the gap in final report.'\n- **Before (Anti-Pattern)**: Tool returns 404 error for Anthropic context windows URL. Agent continues without acknowledgment. Later cites 'Claude has 200K context window' without showing source. Final report cites Google Research paper that was never fetched.\n\n**After (Pattern)**: Tool returned 404 for Anthropic URL. Thinking: 'Primary source failed. Fallback: search for alternative Anthropic documentation URL or find archived version. If unavailable, note context window data from secondary sources only and add disclaimer about verification status.' Then: 'Cross-validated Claude context window: Anthropic blog (successfully read) and two developer documentation sources agree on 200K. Confident in this claim.' Source tracking table shows: Anthropic URL (failed, backup used), Blog (success), Dev docs (success).\n\n---\n\n## Score Expectations\n\nComplex research tasks with multiple tools (6+) and multi-step reasoning chains typically achieve scores in the **65-75 range**. This is not a limitation of the prompt but reflects:\n\n- Inherent variability in tool outputs affecting reasoning paths\n- Multiple valid approaches leading to different intermediate scores\n- Stochastic nature of long-horizon agent execution\n\n**Focus on relative improvement and pattern elimination** rather than absolute scores. A 5-10% improvement from optimization is significant for complex tasks.\n\n---\n\n## Skill Metadata\n\n**Generated**: 2026-01-11\n**Source**: Reasoning Trace Optimizer\n**Optimization Iterations**: 10\n**Best Score Achieved**: 72/100 (iteration 4)\n**Final Score**: 70.0/100\n**Score Improvement**: 67.6 → 70.0 (+3.6%)\n\nFile v1.0.0:examples/interleaved-thinking/SKILL.md\n\n---\nname: reasoning-trace-optimizer\ndescription: \"Debug and optimize AI agents by analyzing reasoning traces. Activates on 'debug agent', 'optimize prompt', 'analyze reasoning', 'why did the agent fail', 'improve agent performance', or when diagnosing agent failures and context degradation.\"\n---\n\n# Reasoning Trace Optimizer\n\nDebug and optimize AI agents by analyzing their reasoning traces. This skill uses MiniMax M2.1's interleaved thinking to provide deep insight into agent decision-making and generate concrete improvements.\n\n## When to Activate\n\n- User asks to \"debug agent\", \"analyze reasoning\", or \"optimize prompt\"\n- Agent task fails and user wants to understand why\n- User mentions \"context degradation\", \"tool confusion\", or \"instruction drift\"\n- Request to improve agent performance or reduce errors\n- User wants to generate shareable learnings from debugging sessions\n- After repeated failures on similar tasks\n\n## Core Concepts\n\n### Interleaved Thinking\n\nUnlike standard reasoning models that think once at the start, interleaved thinking allows reasoning BETWEEN each tool interaction. This is critical because:\n\n1. **Long-horizon tasks** require maintaining focus across many turns\n2. **External perturbations** (tool outputs, environment changes) need real-time adaptation\n3. **Debugging** requires seeing HOW decisions were made, not just WHAT was output\n\n### The Optimization Loop\n\n```\nExecute Agent → Capture Traces → Analyze Patterns → Optimize Prompt → Re-run\n ↑____________|\n```\n\nEach iteration improves the prompt based on detected patterns until convergence.\n\n### Pattern Detection\n\nCommon failure patterns the analyzer detects:\n\n| Pattern | Description |\n|---------|-------------|\n| `context_degradation` | Model loses track of information over long contexts |\n| `tool_confusion` | Model misunderstands tool capabilities or outputs |\n| `instruction_drift` | Model gradually deviates from original instructions |\n| `goal_abandonment` | Model stops pursuing the original goal |\n| `circular_reasoning` | Model repeats similar actions without progress |\n| `premature_conclusion` | Model concludes before completing the task |\n\n## Usage Modes\n\n### Mode 1: M2.1 Agent Debugging\n\nRun a task through M2.1 and analyze its reasoning:\n\n```python\nfrom reasoning_trace_optimizer import TraceCapture, TraceAnalyzer\n\ncapture = TraceCapture()\ntrace = capture.run(\n task=\"Search for Python tutorials and summarize them\",\n system_prompt=\"You are a research assistant.\",\n tools=[search_tool],\n tool_executor=execute_search\n)\n\nanalyzer = TraceAnalyzer()\nanalysis = analyzer.analyze(trace)\n\nprint(f\"Score: {analysis.overall_score}/100\")\nfor pattern in analysis.patterns:\n print(f\"Found: {pattern.type.value} - {pattern.suggestion}\")\n```\n\n### Mode 2: Full Optimization Loop\n\nAutomatically iterate until the prompt is optimized:\n\n```python\nfrom reasoning_trace_optimizer import OptimizationLoop, LoopConfig\n\nconfig = LoopConfig(\n max_iterations=5,\n min_score_threshold=80.0,\n)\n\nloop = OptimizationLoop(config=config)\nresult = loop.run(\n task=\"Analyze this codebase and suggest improvements\",\n initial_prompt=\"You are a code reviewer.\",\n tools=[read_file_tool, search_tool],\n tool_executor=execute_tool\n)\n\nprint(f\"Improved: {result.initial_score} → {result.final_score}\")\nprint(f\"Final prompt:\\n{result.final_prompt}\")\n```\n\n### Mode 3: Universal Session Analysis\n\nAnalyze any agent's previous thinking (works with Claude, GPT, etc.):\n\nWhen this skill is activated in Claude Code, it can analyze the current session's thinking blocks to identify issues and suggest improvements.\n\n```\n/reasoning-trace-optimizer analyze-session\n```\n\n### Mode 4: Generate Shareable Skills\n\nConvert optimization learnings into reusable Agent Skills:\n\n```python\nfrom reasoning_trace_optimizer import SkillGenerator\n\ngenerator = SkillGenerator()\nskill_path = generator.generate(\n result=loop_result,\n skill_name=\"web-search-best-practices\",\n output_dir=\"./skills\"\n)\n```\n\n## CLI Commands\n\n```bash\n# Capture reasoning trace\nrto capture \"Search for Python tutorials\" -s \"You are a helpful assistant.\"\n\n# Analyze a task\nrto analyze \"Debug this code\" -o analysis.txt\n\n# Run optimization loop\nrto optimize \"Research AI papers\" --max-iterations 5 --generate-skill\n\n# Generate skill from artifacts\nrto generate-skill my-skill-name --artifacts-dir ./optimization_artifacts\n```\n\n## Integration with Claude Code\n\n### Auto-trigger on Failure\n\nAdd to your hooks to automatically analyze failures:\n\n```json\n{\n \"hooks\": {\n \"post_tool_error\": {\n \"command\": \"rto analyze-session --last-error\"\n }\n }\n}\n```\n\n### On-demand Analysis\n\nUse the slash command to analyze current session:\n\n```\n/reasoning-trace-optimizer\n```\n\nThis will:\n1. Extract thinking blocks from the current session\n2. Identify patterns and issues\n3. Suggest prompt improvements\n4. Optionally update the system prompt\n\n## Guidelines\n\n1. **Preserve full context**: M2.1 requires full response history including thinking blocks for optimal performance\n2. **Use appropriate tools**: Define tools clearly with unambiguous descriptions\n3. **Set realistic convergence thresholds**: 5-10% improvement per iteration is typical\n4. **Review generated skills**: Auto-generated skills should be reviewed before sharing\n5. **Monitor token usage**: Each optimization iteration uses significant tokens\n\n## Examples\n\n### Before Optimization\n\n```\nSystem: You are a helpful assistant.\n\nIssue: Agent called wrong tools, lost track of goal after 3 turns\nScore: 45/100\nPatterns: tool_confusion, goal_abandonment\n```\n\n### After Optimization\n\n```\nSystem: You are a research assistant focused on finding accurate information.\n\nIMPORTANT GUIDELINES:\n- Always verify search results before summarizing\n- If a tool returns an error, try an alternative approach\n- Keep track of your original goal throughout the task\n- Validate findings against multiple sources when possible\n\nIssue: None\nScore: 85/100\nPatterns: None detected\n```\n\n## References\n\n- MiniMax M2.1 Documentation: https://platform.minimax.io/docs\n- Interleaved Thinking Guide: See `docs/interleavedthinking.md`\n- Agent Generalization: See `docs/agentthinking.md`\n\n---\n\n## Skill Metadata\n\n**Created**: 2025-01-11\n**Author**: Muratcan Koylan\n**Version**: 0.1.0\n**Powered by**: MiniMax M2.1\n**Partnership**: Built in collaboration with MiniMax AI\n\nFile v1.0.0:SKILL.md\n\n---\nname: context-engineering-collection\ndescription: A comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.\n---\n\n# Agent Skills for Context Engineering\n\nThis collection provides structured guidance for building production-grade AI agent systems through effective context engineering.\n\n## When to Activate\n\nActivate these skills when:\n- Building new agent systems from scratch\n- Optimizing existing agent performance\n- Debugging context-related failures\n- Designing multi-agent architectures\n- Creating or evaluating tools for agents\n- Implementing memory and persistence layers\n\n## Skill Map\n\n### Foundational Context Engineering\n\n**Understanding Context Fundamentals**\nContext is not just prompt text—it is the complete state available to the language model at inference time, including system instructions, tool definitions, retrieved documents, message history, and tool outputs. Effective context engineering means understanding what information truly matters for the task at hand and curating that information for maximum signal-to-noise ratio.\n\n**Recognizing Context Degradation**\nLanguage models exhibit predictable degradation patterns as context grows: the \"lost-in-middle\" phenomenon where information in the center of context receives less attention; U-shaped attention curves that prioritize beginning and end; context poisoning when errors compound; and context distraction when irrelevant information overwhelms relevant content.\n\n### Architectural Patterns\n\n**Multi-Agent Coordination**\nProduction multi-agent systems converge on three dominant patterns: supervisor/orchestrator architectures with centralized control, peer-to-peer swarm architectures for flexible handoffs, and hierarchical structures for complex task decomposition. The critical insight is that sub-agents exist primarily to isolate context rather than to simulate organizational roles.\n\n**Memory System Design**\nMemory architectures range from simple scratchpads to sophisticated temporal knowledge graphs. Vector RAG provides semantic retrieval but loses relationship information. Knowledge graphs preserve structure but require more engineering investment. The file-system-as-memory pattern enables just-in-time context loading without stuffing context windows.\n\n**Filesystem-Based Context**\nThe filesystem provides a single interface for storing, retrieving, and updating effectively unlimited context. Key patterns include scratch pads for tool output offloading, plan persistence for long-horizon tasks, sub-agent communication via shared files, and dynamic skill loading. Agents use `ls`, `glob`, `grep`, and `read_file` for targeted context discovery, often outperforming semantic search for structural queries.\n\n**Hosted Agent Infrastructure**\nBackground coding agents run in remote sandboxed environments rather than on local machines. Key patterns include pre-built environment images refreshed on regular cadence, warm sandbox pools for instant session starts, filesystem snapshots for session persistence, and multiplayer support for collaborative agent sessions. Critical optimizations include allowing file reads before git sync completes (blocking only writes), predictive sandbox warming when users start typing, and self-spawning agents for parallel task execution.\n\n**Tool Design Principles**\nTools are contracts between deterministic systems and non-deterministic agents. Effective tool design follows the consolidation principle (prefer single comprehensive tools over multiple narrow ones), returns contextual information in errors, supports response format options for token efficiency, and uses clear namespacing.\n\n### Operational Excellence\n\n**Context Compression**\nWhen agent sessions exhaust memory, compression becomes mandatory. The correct optimization target is tokens-per-task, not tokens-per-request. Structured summarization with explicit sections for files, decisions, and next steps preserves more useful information than aggressive compression. Artifact trail integrity remains the weakest dimension across all compression methods.\n\n**Context Optimization**\nTechniques include compaction (summarizing context near limits), observation masking (replacing verbose tool outputs with references), prefix caching (reusing KV blocks across requests), and strategic context partitioning (splitting work across sub-agents with isolated contexts).\n\n**Evaluation Frameworks**\nProduction agent evaluation requires multi-dimensional rubrics covering factual accuracy, completeness, tool efficiency, and process quality. Effective patterns include LLM-as-judge for scalability, human evaluation for edge cases, and end-state evaluation for agents that mutate persistent state.\n\n### Development Methodology\n\n**Project Development**\nEffective LLM project development begins with task-model fit analysis: validating through manual prototyping that a task is well-suited for LLM processing before building automation. Production pipelines follow staged, idempotent architectures (acquire, prepare, process, parse, render) with file system state management for debugging and caching. Structured output design with explicit format specifications enables reliable parsing. Start with minimal architecture and add complexity only when proven necessary.\n\n## Core Concepts\n\nThe collection is organized around three core themes. First, context fundamentals establish what context is, how attention mechanisms work, and why context quality matters more than quantity. Second, architectural patterns cover the structures and coordination mechanisms that enable effective agent systems. Third, operational excellence addresses the ongoing work of optimizing and evaluating production systems.\n\n## Practical Guidance\n\nEach skill can be used independently or in combination. Start with fundamentals to establish context management mental models. Branch into architectural patterns based on your system requirements. Reference operational skills when optimizing production systems.\n\nThe skills are platform-agnostic and work with Claude Code, Cursor, or any agent framework that supports custom instructions or skill-like constructs.\n\n## Integration\n\nThis collection integrates with itself—skills reference each other and build on shared concepts. The fundamentals skill provides context for all other skills. Architectural skills (multi-agent, memory, tools) can be combined for complex systems. Operational skills (optimization, evaluation) apply to any system built using the foundational and architectural skills.\n\n## References\n\nInternal skills in this collection:\n- [context-fundamentals](skills/context-fundamentals/SKILL.md)\n- [context-degradation](skills/context-degradation/SKILL.md)\n- [context-compression](skills/context-compression/SKILL.md)\n- [multi-agent-patterns](skills/multi-agent-patterns/SKILL.md)\n- [memory-systems](skills/memory-systems/SKILL.md)\n- [tool-design](skills/tool-design/SKILL.md)\n- [filesystem-context](skills/filesystem-context/SKILL.md)\n- [hosted-agents](skills/hosted-agents/SKILL.md)\n- [context-optimization](skills/context-optimization/SKILL.md)\n- [evaluation](skills/evaluation/SKILL.md)\n- [project-development](skills/project-development/SKILL.md)\n\nExternal resources on context engineering:\n- Research on attention mechanisms and context window limitations\n- Production experience from leading AI labs on agent system design\n- Framework documentation for LangGraph, AutoGen, and CrewAI\n\n---\n\n## Skill Metadata\n\n**Created**: 2025-12-20\n**Last Updated**: 2025-12-25\n**Author**: Agent Skills for Context Engineering Contributors\n**Version**: 1.2.0\n\nFile v1.0.0:skills/advanced-evaluation/SKILL.md\n\n---\nname: advanced-evaluation\ndescription: This skill should be used when the user asks to \"implement LLM-as-judge\", \"compare model outputs\", \"create evaluation rubrics\", \"mitigate evaluation bias\", or mentions direct scoring, pairwise comparison, position bias, evaluation pipelines, or automated quality assessment.\n---\n\n# Advanced Evaluation\n\nThis skill covers production-grade techniques for evaluating LLM outputs using LLMs as judges. It synthesizes research from academic papers, industry practices, and practical implementation experience into actionable patterns for building reliable evaluation systems.\n\n**Key insight**: LLM-as-a-Judge is not a single technique but a family of approaches, each suited to different evaluation contexts. Choosing the right approach and mitigating known biases is the core competency this skill develops.\n\n## When to Activate\n\nActivate this skill when:\n\n- Building automated evaluation pipelines for LLM outputs\n- Comparing multiple model responses to select the best one\n- Establishing consistent quality standards across evaluation teams\n- Debugging evaluation systems that show inconsistent results\n- Designing A/B tests for prompt or model changes\n- Creating rubrics for human or automated evaluation\n- Analyzing correlation between automated and human judgments\n\n## Core Concepts\n\n### The Evaluation Taxonomy\n\nSelect between two primary approaches based on whether ground truth exists:\n\n**Direct Scoring** — Use when objective criteria exist (factual accuracy, instruction following, toxicity). A single LLM rates one response on a defined scale. Achieves moderate-to-high reliability for well-defined criteria. Watch for score calibration drift and inconsistent scale interpretation.\n\n**Pairwise Comparison** — Use for subjective preferences (tone, style, persuasiveness). An LLM compares two responses and selects the better one. Achieves higher human-judge agreement than direct scoring for preference tasks (Zheng et al., 2023). Watch for position bias and length bias.\n\n### The Bias Landscape\n\nMitigate these systematic biases in every evaluation system:\n\n**Position Bias**: First-position responses get preferential treatment. Mitigate by evaluating twice with swapped positions, then apply majority vote or consistency check.\n\n**Length Bias**: Longer responses score higher regardless of quality. Mitigate by explicitly prompting to ignore length and applying length-normalized scoring.\n\n**Self-Enhancement Bias**: Models rate their own outputs higher. Mitigate by using different models for generation and evaluation.\n\n**Verbosity Bias**: Excessive detail scores higher even when unnecessary. Mitigate with criteria-specific rubrics that penalize irrelevant detail.\n\n**Authority Bias**: Confident tone scores higher regardless of accuracy. Mitigate by requiring evidence citation and adding a fact-checking layer.\n\n### Metric Selection Framework\n\nMatch metrics to the evaluation task structure:\n\n| Task Type | Primary Metrics | Secondary Metrics |\n|-----------|-----------------|-------------------|\n| Binary classification (pass/fail) | Recall, Precision, F1 | Cohen's kappa |\n| Ordinal scale (1-5 rating) | Spearman's rho, Kendall's tau | Cohen's kappa (weighted) |\n| Pairwise preference | Agreement rate, Position consistency | Confidence calibration |\n| Multi-label | Macro-F1, Micro-F1 | Per-label precision/recall |\n\nPrioritize systematic disagreement patterns over absolute agreement rates because a judge that consistently disagrees with humans on specific criteria is more problematic than one with random noise.\n\n## Evaluation Approaches\n\n### Direct Scoring Implementation\n\nBuild direct scoring with three components: clear criteria, a calibrated scale, and structured output format.\n\n**Criteria Definition Pattern**:\n```\nCriterion: [Name]\nDescription: [What this criterion measures]\nWeight: [Relative importance, 0-1]\n```\n\n**Scale Calibration** — Choose scale granularity based on rubric detail:\n- 1-3: Binary with neutral option, lowest cognitive load\n- 1-5: Standard Likert, best balance of granularity and reliability\n- 1-10: Use only with detailed per-level rubrics because calibration is harder\n\n**Prompt Structure for Direct Scoring**:\n```\nYou are an expert evaluator assessing response quality.\n\n## Task\nEvaluate the following response against each criterion.\n\n## Original Prompt\n{prompt}\n\n## Response to Evaluate\n{response}\n\n## Criteria\n{for each criterion: name, description, weight}\n\n## Instructions\nFor each criterion:\n1. Find specific evidence in the response\n2. Score according to the rubric (1-{max} scale)\n3. Justify your score with evidence\n4. Suggest one specific improvement\n\n## Output Format\nRespond with structured JSON containing scores, justifications, and summary.\n```\n\nAlways require justification before the score in all scoring prompts because research shows this improves reliability by 15-25% compared to score-first approaches.\n\n### Pairwise Comparison Implementation\n\nApply position bias mitigation in every pairwise evaluation:\n\n1. First pass: Response A in first position, Response B in second\n2. Second pass: Response B in first position, Response A in second\n3. Consistency check: If passes disagree, return TIE with reduced confidence\n4. Final verdict: Consistent winner with averaged confidence\n\n**Prompt Structure for Pairwise Comparison**:\n```\nYou are an expert evaluator comparing two AI responses.\n\n## Critical Instructions\n- Do NOT prefer responses because they are longer\n- Do NOT prefer responses based on position (first vs second)\n- Focus ONLY on quality according to the specified criteria\n- Ties are acceptable when responses are genuinely equivalent\n\n## Original Prompt\n{prompt}\n\n## Response A\n{response_a}\n\n## Response B\n{response_b}\n\n## Comparison Criteria\n{criteria list}\n\n## Instructions\n1. Analyze each response independently first\n2. Compare them on each criterion\n3. Determine overall winner with confidence level\n\n## Output Format\nJSON with per-criterion comparison, overall winner, confidence (0-1), and reasoning.\n```\n\n**Confidence Calibration** — Map confidence to position consistency:\n- Both passes agree: confidence = average of individual confidences\n- Passes disagree: confidence = 0.5, verdict = TIE\n\n### Rubric Generation\n\nGenerate rubrics to reduce evaluation variance by 40-60% compared to open-ended scoring.\n\n**Include these rubric components**:\n1. **Level descriptions**: Clear boundaries for each score level\n2. **Characteristics**: Observable features that define each level\n3. **Examples**: Representative text for each level (optional but valuable)\n4. **Edge cases**: Guidance for ambiguous situations\n5. **Scoring guidelines**: General principles for consistent application\n\n**Set strictness calibration** for the use case:\n- **Lenient**: Lower passing bar, appropriate for encouraging iteration\n- **Balanced**: Typical production expectations\n- **Strict**: High standards for safety-critical or high-stakes evaluation\n\nAdapt rubrics to the domain — use domain-specific terminology. A code readability rubric mentions variables, functions, and comments. A medical accuracy rubric references clinical terminology and evidence standards.\n\n## Practical Guidance\n\n### Evaluation Pipeline Design\n\nBuild production evaluation systems with these layers: Criteria Loader (rubrics + weights) -> Primary Scorer (direct or pairwise) -> Bias Mitigation (position swap, etc.) -> Confidence Scoring (calibration) -> Output (scores + justifications + confidence). See [Evaluation Pipeline Diagram](./references/evaluation-pipeline.md) for the full visual layout.\n\n### Decision Framework: Direct vs. Pairwise\n\nApply this decision tree:\n\n```\nIs there an objective ground truth?\n+-- Yes -> Direct Scoring\n| Examples: factual accuracy, instruction following, format compliance\n|\n+-- No -> Is it a preference or quality judgment?\n +-- Yes -> Pairwise Comparison\n | Examples: tone, style, persuasiveness, creativity\n |\n +-- No -> Consider reference-based evaluation\n Examples: summarization (compare to source), translation (compare to reference)\n```\n\n### Scaling Evaluation\n\nFor high-volume evaluation, apply one of these strategies:\n\n1. **Panel of LLMs (PoLL)**: Use multiple models as judges and aggregate votes to reduce individual model bias. More expensive but more reliable for high-stakes decisions.\n\n2. **Hierarchical evaluation**: Use a fast cheap model for screening and an expensive model for edge cases. Requires calibration of the screening threshold.\n\n3. **Human-in-the-loop**: Automate clear cases and route low-confidence decisions to human review. Design feedback loops to improve automated evaluation over time.\n\n## Examples\n\n### Example 1: Direct Scoring for Accuracy\n\n**Input**:\n```\nPrompt: \"What causes seasons on Earth?\"\nResponse: \"Seasons are caused by Earth's tilted axis. As Earth orbits the Sun,\ndifferent hemispheres receive more direct sunlight at different times of year.\"\nCriterion: Factual Accuracy (weight: 1.0)\nScale: 1-5\n```\n\n**Output**:\n```json\n{\n \"criterion\": \"Factual Accuracy\",\n \"score\": 5,\n \"evidence\": [\n \"Correctly identifies axial tilt as primary cause\",\n \"Correctly explains differential sunlight by hemisphere\",\n \"No factual errors present\"\n ],\n \"justification\": \"Response accurately explains the cause of seasons with correct\nscientific reasoning. Both the axial tilt and its effect on sunlight distribution\nare correctly described.\",\n \"improvement\": \"Could add the specific tilt angle (23.5 degrees) for completeness.\"\n}\n```\n\n### Example 2: Pairwise Comparison with Position Swap\n\n**Input**:\n```\nPrompt: \"Explain machine learning to a beginner\"\nResponse A: [Technical explanation with jargon]\nResponse B: [Simple analogy-based explanation]\nCriteria: [\"clarity\", \"accessibility\"]\n```\n\n**First Pass (A first)**:\n```json\n{ \"winner\": \"B\", \"confidence\": 0.8 }\n```\n\n**Second Pass (B first)**:\n```json\n{ \"winner\": \"A\", \"confidence\": 0.6 }\n```\n(Note: Winner is A because B was in first position)\n\n**Mapped Second Pass**:\n```json\n{ \"winner\": \"B\", \"confidence\": 0.6 }\n```\n\n**Final Result**:\n```json\n{\n \"winner\": \"B\",\n \"confidence\": 0.7,\n \"positionConsistency\": {\n \"consistent\": true,\n \"firstPassWinner\": \"B\",\n \"secondPassWinner\": \"B\"\n }\n}\n```\n\n### Example 3: Rubric Generation\n\n**Input**:\n```\ncriterionName: \"Code Readability\"\ncriterionDescription: \"How easy the code is to understand and maintain\"\ndomain: \"software engineering\"\nscale: \"1-5\"\nstrictness: \"balanced\"\n```\n\n**Output** (abbreviated):\n```json\n{\n \"levels\": [\n {\n \"score\": 1,\n \"label\": \"Poor\",\n \"description\": \"Code is difficult to understand without significant effort\",\n \"characteristics\": [\n \"No meaningful variable or function names\",\n \"No comments or documentation\",\n \"Deeply nested or convoluted logic\"\n ]\n },\n {\n \"score\": 3,\n \"label\": \"Adequate\",\n \"description\": \"Code is understandable with some effort\",\n \"characteristics\": [\n \"Most variables have meaningful names\",\n \"Basic comments present for complex sections\",\n \"Logic is followable but could be cleaner\"\n ]\n },\n {\n \"score\": 5,\n \"label\": \"Excellent\",\n \"description\": \"Code is immediately clear and maintainable\",\n \"characteristics\": [\n \"All names are descriptive and consistent\",\n \"Comprehensive documentation\",\n \"Clean, modular structure\"\n ]\n }\n ],\n \"edgeCases\": [\n {\n \"situation\": \"Code is well-structured but uses domain-specific abbreviations\",\n \"guidance\": \"Score based on readability for domain experts, not general audience\"\n }\n ]\n}\n```\n\n## Guidelines\n\n1. **Always require justification before scores** - Chain-of-thought prompting improves reliability by 15-25%\n\n2. **Always swap positions in pairwise comparison** - Single-pass comparison is corrupted by position bias\n\n3. **Match scale granularity to rubric specificity** - Don't use 1-10 without detailed level descriptions\n\n4. **Separate objective and subjective criteria** - Use direct scoring for objective, pairwise for subjective\n\n5. **Include confidence scores** - Calibrate to position consistency and evidence strength\n\n6. **Define edge cases explicitly** - Ambiguous situations cause the most evaluation variance\n\n7. **Use domain-specific rubrics** - Generic rubrics produce generic (less useful) evaluations\n\n8. **Validate against human judgments** - Automated evaluation is only valuable if it correlates with human assessment\n\n9. **Monitor for systematic bias** - Track disagreement patterns by criterion, response type, model\n\n10. **Design for iteration** - Evaluation systems improve with feedback loops\n\n## Gotchas\n\n1. **Scoring without justification**: Scores lack grounding and are difficult to debug. Always require evidence-based justification before the score.\n\n2. **Single-pass pairwise comparison**: Position bias corrupts results when positions are not swapped. Always evaluate twice with swapped positions and check consistency.\n\n3. **Overloaded criteria**: Criteria that measure multiple things at once produce unreliable scores. Enforce one criterion = one measurable aspect.\n\n4. **Missing edge case guidance**: Evaluators handle ambiguous cases inconsistently without explicit instructions. Include edge cases in rubrics with clear resolution rules.\n\n5. **Ignoring confidence calibration**: High-confidence wrong judgments are worse than low-confidence ones. Calibrate confidence to position consistency and evidence strength.\n\n6. **Rubric drift**: Rubrics become miscalibrated as quality standards evolve or model capabilities improve. Schedule periodic rubric reviews and re-anchor score levels against fresh human-annotated examples.\n\n7. **Evaluation prompt sensitivity**: Minor wording changes in evaluation prompts (e.g., reordering instructions, changing phrasing) can cause 10-20% score swings. Version-control evaluation prompts and run regression tests before deploying prompt changes.\n\n8. **Uncontrolled length bias**: Longer responses systematically score higher even when conciseness is preferred. Add explicit length-neutrality instructions to evaluation prompts and validate with length-controlled test pairs.\n\n## Integration\n\nThis skill integrates with:\n\n- **context-fundamentals** - Evaluation prompts require effective context structure\n- **tool-design** - Evaluation tools need proper schemas and error handling\n- **context-optimization** - Evaluation prompts can be optimized for token efficiency\n- **evaluation** (foundational) - This skill extends the foundational evaluation concepts\n\n## References\n\nInternal reference:\n- [LLM-as-Judge Implementation Patterns](./references/implementation-patterns.md) - Read when: building an evaluation pipeline from scratch or integrating LLM judges into CI/CD\n- [Bias Mitigation Techniques](./references/bias-mitigation.md) - Read when: evaluation results show inconsistent or suspicious scoring patterns\n- [Metric Selection Guide](./references/metrics-guide.md) - Read when: choosing statistical metrics to validate evaluation reliability\n- [Evaluation Pipeline Diagram](./references/evaluation-pipeline.md) - Read when: designing the architecture of a multi-stage evaluation system\n\nExternal research:\n- [Eugene Yan: Evaluating the Effectiveness of LLM-Evaluators](https://eugeneyan.com/writing/llm-evaluators/) - Read when: surveying the state of the art in LLM evaluation\n- [Judging LLM-as-a-Judge (Zheng et al., 2023)](https://arxiv.org/abs/2306.05685) - Read when: understanding position bias and MT-Bench methodology\n- [G-Eval: NLG Evaluation using GPT-4 (Liu et al., 2023)](https://arxiv.org/abs/2303.16634) - Read when: implementing chain-of-thought evaluation scoring\n- [Large Language Models are not Fair Evaluators (Wang et al., 2023)](https://arxiv.org/abs/2305.17926) - Read when: diagnosing systematic bias in evaluation outputs\n\nRelated skills in this collection:\n- evaluation - Foundational evaluation concepts\n- context-fundamentals - Context structure for evaluation prompts\n- tool-design - Building evaluation tools\n\n---\n\n## Skill Metadata\n\n**Created**: 2025-12-24\n**Last Updated**: 2026-03-17\n**Author**: Agent Skills for Context Engineering Contributors\n**Version**: 2.0.0\n\nFile v1.0.0:skills/bdi-mental-states/SKILL.md\n\n---\nname: bdi-mental-states\ndescription: This skill should be used when the user asks to \"model agent mental states\", \"implement BDI architecture\", \"create belief-desire-intention models\", \"transform RDF to beliefs\", \"build cognitive agent\", or mentions BDI ontology, mental state modeling, rational agency, or neuro-symbolic AI integration.\n---\n\n# BDI Mental State Modeling\n\nTransform external RDF context into agent mental states (beliefs, desires, intentions) using formal BDI ontology patterns. This skill enables agents to reason about context through cognitive architecture, supporting deliberative reasoning, explainability, and semantic interoperability within multi-agent systems.\n\n## When to Activate\n\nActivate this skill when:\n- Processing external RDF context into agent beliefs about world states\n- Modeling rational agency with perception, deliberation, and action cycles\n- Enabling explainability through traceable reasoning chains\n- Implementing BDI frameworks (SEMAS, JADE, JADEX)\n- Augmenting LLMs with formal cognitive structures (Logic Augmented Generation)\n- Coordinating mental states across multi-agent platforms\n- Tracking temporal evolution of beliefs, desires, and intentions\n- Linking motivational states to action plans\n\n## Core Concepts\n\n### Mental Reality Architecture\n\nSeparate mental states into two ontological categories because BDI reasoning requires distinguishing what persists from what happens:\n\n**Mental States (Endurants)** -- model these as persistent cognitive attributes that hold over time intervals:\n- `Belief`: Represent what the agent holds true about the world. Ground every belief in a world state reference.\n- `Desire`: Represent what the agent wishes to bring about. Link each desire back to the beliefs that motivate it.\n- `Intention`: Represent what the agent commits to achieving. An intention must fulfil a desire and specify a plan.\n\n**Mental Processes (Perdurants)** -- model these as events that create or modify mental states, because tracking causal transitions enables explainability:\n- `BeliefProcess`: Triggers belief formation/update from perception. Always connect to a generating world state.\n- `DesireProcess`: Generates desires from existing beliefs. Preserves the motivational chain.\n- `IntentionProcess`: Commits to selected desires as actionable intentions.\n\n### Cognitive Chain Pattern\n\nWire beliefs, desires, and intentions into directed chains using bidirectional properties (`motivates`/`isMotivatedBy`, `fulfils`/`isFulfilledBy`) because this enables both forward reasoning (what should the agent do?) and backward tracing (why did the agent act?):\n\n```turtle\n:Belief_store_open a bdi:Belief ;\n rdfs:comment \"Store is open\" ;\n bdi:motivates :Desire_buy_groceries .\n\n:Desire_buy_groceries a bdi:Desire ;\n rdfs:comment \"I desire to buy groceries\" ;\n bdi:isMotivatedBy :Belief_store_open .\n\n:Intention_go_shopping a bdi:Intention ;\n rdfs:comment \"I will buy groceries\" ;\n bdi:fulfils :Desire_buy_groceries ;\n bdi:isSupportedBy :Belief_store_open ;\n bdi:specifies :Plan_shopping .\n```\n\n### World State Grounding\n\nAlways ground mental states in world state references rather than free-text descriptions, because ungrounded beliefs break semantic querying and cross-agent interoperability:\n\n```turtle\n:Agent_A a bdi:Agent ;\n bdi:perceives :WorldState_WS1 ;\n bdi:hasMentalState :Belief_B1 .\n\n:WorldState_WS1 a bdi:WorldState ;\n rdfs:comment \"Meeting scheduled at 10am in Room 5\" ;\n bdi:atTime :TimeInstant_10am .\n\n:Belief_B1 a bdi:Belief ;\n bdi:refersTo :WorldState_WS1 .\n```\n\n### Goal-Directed Planning\n\nConnect intentions to plans via `bdi:specifies`, and decompose plans into ordered task sequences using `bdi:precedes`, because this separation allows plan reuse across different intentions while keeping execution order explicit:\n\n```turtle\n:Intention_I1 bdi:specifies :Plan_P1 .\n\n:Plan_P1 a bdi:Plan ;\n bdi:addresses :Goal_G1 ;\n bdi:beginsWith :Task_T1 ;\n bdi:endsWith :Task_T3 .\n\n:Task_T1 bdi:precedes :Task_T2 .\n:Task_T2 bdi:precedes :Task_T3 .\n```\n\n## T2B2T Paradigm\n\nImplement Triples-to-Beliefs-to-Triples as a bidirectional pipeline because agents must both consume external RDF context and produce new RDF assertions. Structure every T2B2T implementation in two explicit phases:\n\n**Phase 1: Triples-to-Beliefs** -- Translate incoming RDF triples into belief instances. Use `bdi:triggers` to connect the external world state to a `BeliefProcess`, and `bdi:generates` to produce the resulting belief. This preserves provenance from source data through to internal cognition:\n```turtle\n:WorldState_notification a bdi:WorldState ;\n rdfs:comment \"Push notification: Payment request $250\" ;\n bdi:triggers :BeliefProcess_BP1 .\n\n:BeliefProcess_BP1 a bdi:BeliefProcess ;\n bdi:generates :Belief_payment_request .\n```\n\n**Phase 2: Beliefs-to-Triples** -- After BDI deliberation selects an intention and executes a plan, project the results back into RDF using `bdi:bringsAbout`. This closes the loop so downstream systems can consume agent outputs as standard linked data:\n```turtle\n:Intention_pay a bdi:Intention ;\n bdi:specifies :Plan_payment .\n\n:PlanExecution_PE1 a bdi:PlanExecution ;\n bdi:satisfies :Plan_payment ;\n bdi:bringsAbout :WorldState_payment_complete .\n```\n\n## Notation Selection by Level\n\nChoose notation based on the C4 abstraction level being modeled, because mixing notations at the wrong level obscures rather than clarifies the cognitive architecture:\n\n| C4 Level | Notation | Mental State Representation |\n|----------|----------|----------------------------|\n| L1 Context | ArchiMate | Agent boundaries, external perception sources |\n| L2 Container | ArchiMate | BDI reasoning engine, belief store, plan executor |\n| L3 Component | UML | Mental state managers, process handlers |\n| L4 Code | UML/RDF | Belief/Desire/Intention classes, ontology instances |\n\n## Justification and Explainability\n\nAttach `bdi:Justification` instances to every mental entity using `bdi:isJustifiedBy`, because unjustified mental states make agent reasoning opaque and untraceable. Each justification should capture the evidence or rule that produced the mental state:\n\n```turtle\n:Belief_B1 a bdi:Belief ;\n bdi:isJustifiedBy :Justification_J1 .\n\n:Justification_J1 a bdi:Justification ;\n rdfs:comment \"Official announcement received via email\" .\n\n:Intention_I1 a bdi:Intention ;\n bdi:isJustifiedBy :Justification_J2 .\n\n:Justification_J2 a bdi:Justification ;\n rdfs:comment \"Location precondition satisfied\" .\n```\n\n## Temporal Dimensions\n\nAssign validity intervals to every mental state using `bdi:hasValidity` with `TimeInterval` instances, because beliefs without temporal bounds cannot be garbage-collected or conflict-checked during diachronic reasoning:\n\n```turtle\n:Belief_B1 a bdi:Belief ;\n bdi:hasValidity :TimeInterval_TI1 .\n\n:TimeInterval_TI1 a bdi:TimeInterval ;\n bdi:hasStartTime :TimeInstant_9am ;\n bdi:hasEndTime :TimeInstant_11am .\n```\n\nQuery mental states active at a specific moment using SPARQL temporal filters. Use this pattern to resolve conflicts when multiple beliefs about the same world state overlap in time:\n\n```sparql\nSELECT ?mentalState WHERE {\n ?mentalState bdi:hasValidity ?interval .\n ?interval bdi:hasStartTime ?start ;\n bdi:hasEndTime ?end .\n FILTER(?start <= \"2025-01-04T10:00:00\"^^xsd:dateTime &&\n ?end >= \"2025-01-04T10:00:00\"^^xsd:dateTime)\n}\n```\n\n## Compositional Mental Entities\n\nDecompose complex beliefs into constituent parts using `bdi:hasPart` relations, because monolithic beliefs force full replacement on partial updates. Structure composite beliefs so that each sub-belief can be independently updated, queried, or invalidated:\n\n```turtle\n:Belief_meeting a bdi:Belief ;\n rdfs:comment \"Meeting at 10am in Room 5\" ;\n bdi:hasPart :Belief_meeting_time , :Belief_meeting_location .\n\n# Update only location component without touching time\n:BeliefProcess_update a bdi:BeliefProcess ;\n bdi:modifies :Belief_meeting_location .\n```\n\n## Integration Patterns\n\n### Logic Augmented Generation (LAG)\n\nUse LAG to constrain LLM outputs with ontological structure, because unconstrained generation produces triples that violate BDI class restrictions. Serialize the ontology into the prompt context, then validate generated triples against it before accepting them:\n\n```python\ndef augment_llm_with_bdi_ontology(prompt, ontology_graph):\n ontology_context = serialize_ontology(ontology_graph, format='turtle')\n augmented_prompt = f\"{ontology_context}\\n\\n{prompt}\"\n\n response = llm.generate(augmented_prompt)\n triples = extract_rdf_triples(response)\n\n is_consistent = validate_triples(triples, ontology_graph)\n return triples if is_consistent else retry_with_feedback()\n```\n\n### SEMAS Rule Translation\n\nTranslate BDI ontology patterns into executable production rules when deploying to rule-based agent platforms. Map each cognitive chain link (belief-to-desire, desire-to-intention) to a HEAD/CONDITIONALS/TAIL rule, because this preserves the deliberative semantics while enabling runtime execution:\n\n```prolog\n% Belief triggers desire formation\n[HEAD: belief(agent_a, store_open)] /\n[CONDITIONALS: time(weekday_afternoon)] »\n[TAIL: generate_desire(agent_a, buy_groceries)].\n\n% Desire triggers intention commitment\n[HEAD: desire(agent_a, buy_groceries)] /\n[CONDITIONALS: belief(agent_a, has_shopping_list)] »\n[TAIL: commit_intention(agent_a, buy_groceries)].\n```\n\n## Guidelines\n\n1. Model world states as configurations independent of agent perspectives, providing referential substrate for mental states.\n\n2. Distinguish endurants (persistent mental states) from perdurants (temporal mental processes), aligning with DOLCE ontology.\n\n3. Treat goals as descriptions rather than mental states, maintaining separation between cognitive and planning layers.\n\n4. Use `hasPart` relations for meronymic structures enabling selective belief updates.\n\n5. Associate every mental entity with temporal constructs via `atTime` or `hasValidity`.\n\n6. Use bidirectional property pairs (`motivates`/`isMotivatedBy`, `generates`/`isGeneratedBy`) for flexible querying.\n\n7. Link mental entities to `Justification` instances for explainability and trust.\n\n8. Implement T2B2T through: (1) translate RDF to beliefs, (2) execute BDI reasoning, (3) project mental states back to RDF.\n\n9. Define existential restrictions on mental processes (e.g., `BeliefProcess ⊑ ∃generates.Belief`).\n\n10. Reuse established ODPs (EventCore, Situation, TimeIndexedSituation, BasicPlan, Provenance) for interoperability.\n\n## Competency Questions\n\nValidate implementation against these SPARQL queries:\n\n```sparql\n# CQ1: What beliefs motivated formation of a given desire?\nSELECT ?belief WHERE {\n :Desire_D1 bdi:isMotivatedBy ?belief .\n}\n\n# CQ2: Which desire does a particular intention fulfill?\nSELECT ?desire WHERE {\n :Intention_I1 bdi:fulfils ?desire .\n}\n\n# CQ3: Which mental process generated a belief?\nSELECT ?process WHERE {\n ?process bdi:generates :Belief_B1 .\n}\n\n# CQ4: What is the ordered sequence of tasks in a plan?\nSELECT ?task ?nextTask WHERE {\n :Plan_P1 bdi:hasComponent ?task .\n OPTIONAL { ?task bdi:precedes ?nextTask }\n} ORDER BY ?task\n```\n\n## Gotchas\n\n1. **Conflating mental states with world states**: Mental states reference world states via `bdi:refersTo`, they are not world states themselves. Mixing them collapses the perception-cognition boundary and breaks SPARQL queries that filter by type.\n\n2. **Missing temporal bounds**: Every mental state needs validity intervals for diachronic reasoning. Without them, stale beliefs persist indefinitely and conflict detection becomes impossible.\n\n3. **Flat belief structures**: Use compositional modeling with `hasPart` for complex beliefs. Monolithic beliefs force full replacement when only one attribute changes.\n\n4. **Implicit justifications**: Always link mental entities to explicit `Justification` instances. Unjustified mental states cannot be audited or traced.\n\n5. **Direct intention-to-action mapping**: Intentions specify plans which contain tasks; actions execute tasks. Skipping the plan layer removes the ability to reuse, reorder, or share execution strategies.\n\n6. **Ontology over-complexity**: Start with 5-10 core classes and properties (Belief, Desire, Intention, WorldState, Plan, plus key relations). Expanding the ontology prematurely inflates prompt context and slows SPARQL queries without improving reasoning quality.\n\n7. **Reasoning cost explosion**: Keep belief chains to 3 levels or fewer (belief -> desire -> intention). Deeper chains become prohibitively expensive for LLM inference and rarely improve decision quality over shallower alternatives.\n\n## Integration\n\n- **RDF Processing**: Apply after parsing external RDF context to construct cognitive representations\n- **Semantic Reasoning**: Combine with ontology reasoning to infer implicit mental state relationships\n- **Multi-Agent Communication**: Integrate with FIPA ACL for cross-platform belief sharing\n- **Temporal Context**: Coordinate with temporal reasoning for mental state evolution\n- **Explainable AI**: Feed into explanation systems tracing perception through deliberation to action\n- **Neuro-Symbolic AI**: Apply in LAG pipelines to constrain LLM outputs with cognitive structures\n\n## References\n\nInternal references:\n- [BDI Ontology Core](./references/bdi-ontology-core.md) - Read when: implementing BDI class hierarchies or defining ontology properties from scratch\n- [RDF Examples](./references/rdf-examples.md) - Read when: writing Turtle serializations of mental states or debugging triple structure\n- [SPARQL Competency Queries](./references/sparql-competency.md) - Read when: validating an implementation against competency questions or building custom queries\n- [Framework Integration](./references/framework-integration.md) - Read when: deploying BDI models to SEMAS, JADE, or LAG pipelines\n\nPrimary sources:\n- Zuppiroli et al. \"The Belief-Desire-Intention Ontology\" (2025) — Read when: implementing formal BDI class hierarchies or validating ontology alignment\n- Rao & Georgeff \"BDI agents: From theory to practice\" (1995) — Read when: understanding the theoretical foundations of practical reasoning agents\n- Bratman \"Intention, plans, and practical reason\" (1987) — Read when: grounding implementation decisions in the philosophical basis of intentionality\n\n---\n\n## Skill Metadata\n\n**Created**: 2026-01-07\n**Last Updated**: 2026-03-17\n**Author**: Agent Skills for Context Engineering Contributors\n**Version**: 2.0.0\n\nFile v1.0.0:skills/context-compression/SKILL.md\n\n---\nname: context-compression\ndescription: This skill should be used when the user asks to \"compress context\", \"summarize conversation history\", \"implement compaction\", \"reduce token usage\", or mentions context compression, structured summarization, tokens-per-task optimization, or long-running agent sessions exceeding context limits.\n---\n\n# Context Compression Strategies\n\nWhen agent sessions generate millions of tokens of conversation history, compression becomes mandatory. The naive approach is aggressive compression to minimize tokens per request. The correct optimization target is tokens per task: total tokens consumed to complete a task, including re-fetching costs when compression loses critical information.\n\n## When to Activate\n\nActivate this skill when:\n- Agent sessions exceed context window limits\n- Codebases exceed context windows (5M+ token systems)\n- Designing conversation summarization strategies\n- Debugging cases where agents \"forget\" what files they modified\n- Building evaluation frameworks for compression quality\n\n## Core Concepts\n\nContext compression trades token savings against information loss. Select from three production-ready approaches based on session characteristics:\n\n1. **Anchored Iterative Summarization**: Implement this for long-running sessions where file tracking matters. Maintain structured, persistent summaries with explicit sections for session intent, file modifications, decisions, and next steps. When compression triggers, summarize only the newly-truncated span and merge with the existing summary rather than regenerating from scratch. This prevents drift that accumulates when summaries are regenerated wholesale — each regeneration risks losing details the model considers low-priority but the task requires. Structure forces preservation because dedicated sections act as checklists the summarizer must populate, catching silent information loss.\n\n2. **Opaque Compression**: Reserve this for short sessions where re-fetching costs are low and maximum token savings are required. It produces compressed representations optimized for reconstruction fidelity, achieving 99%+ compression ratios but sacrificing interpretability entirely. The tradeoff matters: there is no way to verify what was preserved without running probe-based evaluation, so never use this when debugging or artifact tracking is critical.\n\n3. **Regenerative Full Summary**: Use this when summary readability is critical and sessions have clear phase boundaries. It generates detailed structured summaries on each compression trigger. The weakness is cumulative detail loss across repeated cycles — each full regeneration is a fresh pass that may deprioritize details preserved in earlier summaries.\n\n## Detailed Topics\n\n### Optimize for Tokens-Per-Task, Not Tokens-Per-Request\n\nMeasure total tokens consumed from task start to completion, not tokens per individual request. When compression drops file paths, error messages, or decision rationale, the agent must re-explore, re-read files, and re-derive conclusions — wasting far more tokens than the compression saved. A strategy saving 0.5% more tokens per request but causing 20% more re-fetching costs more overall. Track re-fetching frequency as the primary quality signal: if the agent repeatedly asks to re-read files it already processed, compression is too aggressive.\n\n### Solve the Artifact Trail Problem First\n\nArtifact trail integrity is the weakest dimension across all compression methods, scoring only 2.2-2.5 out of 5.0 in evaluations. Address this proactively because general summarization cannot reliably maintain it.\n\nPreserve these categories explicitly in every compression cycle:\n- Which files were created (full paths)\n- Which files were modified and what changed (include function names, not just file names)\n- Which files were read but not changed\n- Specific identifiers: function names, variable names, error messages, error codes\n\nImplement a separate artifact index or explicit file-state tracking in agent scaffolding rather than relying on the summarizer to capture these details. Even structured summarization with dedicated file sections struggles with completeness over long sessions.\n\n### Structure Summaries with Mandatory Sections\n\nBuild structured summaries with explicit sections that prevent silent information loss. Each section acts as a checklist the summarizer must populate, making omissions visible rather than silent.\n\n```markdown\n## Session Intent\n[What the user is trying to accomplish]\n\n## Files Modified\n- auth.controller.ts: Fixed JWT token generation\n- config/redis.ts: Updated connection pooling\n- tests/auth.test.ts: Added mock setup for new config\n\n## Decisions Made\n- Using Redis connection pool instead of per-request connections\n- Retry logic with exponential backoff for transient failures\n\n## Current State\n- 14 tests passing, 2 failing\n- Remaining: mock setup for session service tests\n\n## Next Steps\n1. Fix remaining test failures\n2. Run full test suite\n3. Update documentation\n```\n\nAdapt sections to the agent's domain. A debugging agent needs \"Root Cause\" and \"Error Messages\"; a migration agent needs \"Source Schema\" and \"Target Schema.\" The structure matters more than the specific sections — any explicit schema outperforms freeform summarization.\n\n### Choose Compression Triggers Strategically\n\nWhen to trigger compression matters as much as how to compress. Select a trigger strategy based on session predictability:\n\n| Strategy | Trigger Point | Trade-off |\n|----------|---------------|-----------|\n| Fixed threshold | 70-80% context utilization | Simple but may compress too early |\n| Sliding window | Keep last N turns + summary | Predictable context size |\n| Importance-based | Compress low-relevance sections first | Complex but preserves signal |\n| Task-boundary | Compress at logical task completions | Clean summaries but unpredictable timing |\n\nDefault to sliding window with structured summaries for coding agents — it provides the best balance of predictability and quality. Use task-boundary triggers when sessions have clear phase transitions (e.g., research then implementation then testing).\n\n### Evaluate Compression with Probes, Not Metrics\n\nTraditional metrics like ROUGE or embedding similarity fail to capture functional compression quality. A summary can score high on lexical overlap while missing the one file path the agent needs to continue.\n\nUse probe-based evaluation: after compression, pose questions that test whether critical information survived. If the agent answers correctly, compression preserved the right information. If not, it guesses or hallucinates.\n\n| Probe Type | What It Tests | Example Question |\n|------------|---------------|------------------|\n| Recall | Factual retention | \"What was the original error message?\" |\n| Artifact | File tracking | \"Which files have we modified?\" |\n| Continuation | Task planning | \"What should we do next?\" |\n| Decision | Reasoning chain | \"What did we decide about the Redis issue?\" |\n\n### Score Compression Across Six Dimensions\n\nEvaluate compression quality for coding agents across these dimensions. Accuracy shows the largest variation between methods (0.6 point gap), making it the strongest discriminator. Artifact trail is universally weak (2.2-2.5), confirming it needs specialized handling beyond general summarization.\n\n1. **Accuracy**: Are technical details correct — file paths, function names, error codes?\n2. **Context Awareness**: Does the response reflect current conversation state?\n3. **Artifact Trail**: Does the agent know which files were read or modified?\n4. **Completeness**: Does the response address all parts of the question?\n5. **Continuity**: Can work continue without re-fetching information?\n6. **Instruction Following**: Does the response respect stated constraints?\n\n## Practical Guidance\n\n### Apply the Three-Phase Compression Workflow for Large Codebases\n\nFor codebases or agent systems exceeding context windows, compress through three sequential phases. Each phase narrows context so the next phase operates within budget.\n\n1. **Research Phase**: Explore architecture diagrams, documentation, and key interfaces. Compress exploration into a structured analysis of components, dependencies, and boundaries. Output: a single research document that replaces raw exploration.\n\n2. **Planning Phase**: Convert the research document into an implementation specification with function signatures, type definitions, and data flow. A 5M-token codebase compresses to approximately 2,000 words of specification at this stage.\n\n3. **Implementation Phase**: Execute against the specification. Context stays focused on the spec plus active working files, not raw codebase exploration. This phase rarely needs further compression because the spec is already compact.\n\n### Use Example Artifacts as Compression Seeds\n\nWhen provided with a manual migration example or reference PR, use it as a template to understand the target pattern rather than exploring the codebase from scratch. The example reveals constraints static analysis cannot surface: which invariants must hold, which services break on changes, and what a clean implementation looks like.\n\nThis matters most when the agent cannot distinguish essential complexity (business requirements) from accidental complexity (legacy workarounds). The example artifact encodes that distinction implicitly, saving tokens that would otherwise go to trial-and-error exploration.\n\n### Implement Anchored Iterative Summarization Step by Step\n\n1. Define explicit summary sections matching the agent's domain (debugging, migration, feature development)\n2. On first compression trigger, summarize the truncated history into those sections\n3. On subsequent compressions, summarize only newly truncated content — do not re-summarize the existing summary\n4. Merge new information into existing sections rather than regenerating them, deduplicating by file path and decision identity\n5. Tag which information came from which compression cycle — this enables debugging when summaries drift\n\n### Select the Right Approach for the Session Profile\n\n**Use anchored iterative summarization when:**\n- Sessions are long-running (100+ messages)\n- File tracking matters (coding, debugging)\n- Verification of preserved information is needed\n\n**Use opaque compression when:**\n- Maximum token savings are required\n- Sessions are relatively short\n- Re-fetching costs are low (e.g., no file system access needed)\n\n**Use regenerative summaries when:**\n- Summary interpretability is critical for human review\n- Sessions have clear phase boundaries\n- Full context review is acceptable on each compression trigger\n\n### Calibrate Compression Ratios by Method\n\n| Method | Compression Ratio | Quality Score | Trade-off |\n|--------|-------------------|---------------|-----------|\n| Anchored Iterative | 98.6% | 3.70 | Best quality, slightly less compression |\n| Regenerative | 98.7% | 3.44 | Good quality, moderate compression |\n| Opaque | 99.3% | 3.35 | Best compression, quality loss |\n\nThe 0.7% additional tokens retained by structured summarization buys 0.35 quality points — a significant gap when compounded over multiple compression cycles. For any task where re-fetching costs exist, this tradeoff favors structured approaches.\n\n## Examples\n\n**Example 1: Debugging Session Compression**\n\nOriginal context (89,000 tokens, 178 messages):\n- 401 error on /api/auth/login endpoint\n- Traced through auth controller, middleware, session store\n- Found stale Redis connection\n- Fixed connection pooling, added retry logic\n- 14 tests passing, 2 failing\n\nStructured summary after compression:\n\n```markdown\n## Session Intent\nDebug 401 Unauthorized error on /api/auth/login despite valid credentials.\n\n## Root Cause\nStale Redis connection in session store. JWT generated correctly but session could not be persisted.\n\n## Files Modified\n- auth.controller.ts: No changes (read only)\n- middleware/cors.ts: No changes (examined)\n- config/redis.ts: Fixed connection pooling configuration\n- services/session.service.ts: Added retry logic for transient failures\n- tests/auth.test.ts: Updated mock setup\n\n## Test Status\n14 passing, 2 failing (mock setup issues)\n\n## Next Steps\n1. Fix remaining test failures (mock session service)\n2. Run full test suite\n3. Deploy to staging\n```\n\n**Example 2: Probe Response Quality**\n\nAfter compression, asking \"What was the original error?\":\n\nGood response (structured summarization):\n> \"The original error was a 401 Unauthorized response from the /api/auth/login endpoint. Users received this error with valid credentials. Root cause was stale Redis connection in session store.\"\n\nPoor response (aggressive compression):\n> \"We were debugging an authentication issue. The login was failing. We fixed some configuration problems.\"\n\nThe structured response preserves endpoint, error code, and root cause. The aggressive response loses all technical detail.\n\n## Guidelines\n\n1. Optimize for tokens-per-task, not tokens-per-request\n2. Use structured summaries with explicit sections for file tracking\n3. Trigger compression at 70-80% context utilization\n4. Implement incremental merging rather than full regeneration\n5. Test compression quality with probe-based evaluation\n6. Track artifact trail separately if file tracking is critical\n7. Accept slightly lower compression ratios for better quality retention\n8. Monitor re-fetching frequency as a compression quality signal\n\n## Gotchas\n\n1. **Never compress tool definitions or schemas**: Compressing function call schemas, API specs, or tool definitions destroys agent functionality entirely. The agent cannot invoke tools whose parameter names or types have been summarized away. Treat tool definitions as immutable anchors that bypass compression.\n\n2. **Compressed summaries hallucinate facts**: When an LLM summarizes conversation history, it may introduce plausible-sounding details that never appeared in the original. Always validate compressed output against source material before discarding originals — especially for file paths, error codes, and numeric values that the summarizer may \"round\" or fabricate.\n\n3. **Compression breaks artifact references**: File paths, commit SHAs, variable names, and code snippets get paraphrased or dropped during compression. A summary saying \"updated the config file\" when the agent needs `config/redis.ts` causes re-exploration. Preserve identifiers verbatim in dedicated sections rather than embedding them in prose.\n\n4. **Early turns contain irreplaceable constraints**: The first few turns of a session often contain task setup, user constraints, and architectural decisions that cannot be re-derived. Protect early turns from compression or extract their constraints into a persistent preamble that survives all compression cycles.\n\n5. **Aggressive ratios compound across cycles**: A 95% compression ratio seems safe once, but applying it repeatedly compounds losses. After three cycles at 95%, only 0.0125% of original tokens remain. Calibrate ratios assuming multiple compression cycles, not a single pass.\n\n6. **Code and prose need different compression**: Prose compresses well because natural language is redundant. Code does not — removing a single token from a function signature or import path can make it useless. Apply domain-specific compression strategies: summarize prose sections aggressively while preserving code blocks and structured data verbatim.\n\n7. **Probe-based evaluation gives false confidence**: Probes can pass despite critical information being lost, because the probes test only what they ask about. A probe set that checks file names but not function signatures will miss signature loss. Design probes to cover all six evaluation dimensions, and rotate probe sets across evaluation runs to avoid blind spots.\n\n## Integration\n\nThis skill connects to several others in the collection:\n\n- context-degradation - Compression is a mitigation strategy for degradation\n- context-optimization - Compression is one optimization technique among many\n- evaluation - Probe-based evaluation applies to compression testing\n- memory-systems - Compression relates to scratchpad and summary memory patterns\n\n## References\n\nInternal reference:\n- [Evaluation Framework Reference](./references/evaluation-framework.md) - Read when: building or calibrating a probe-based evaluation pipeline, or when needing scoring rubrics and LLM judge configuration for compression quality assessment\n\nRelated skills in this collection:\n- context-degradation - Read when: diagnosing why agent performance drops over long sessions, before applying compression as a mitigation\n- context-optimization - Read when: compression alone is insufficient and broader optimization strategies (pruning, caching, routing) are needed\n- evaluation - Read when: designing evaluation frameworks beyond compression-specific probes, including general LLM-as-judge methodology\n\nExternal resources:\n- Factory Research: Evaluating Context Compression for AI Agents (December 2025) - Read when: needing benchmark data on compression method comparisons or the 36,000-message evaluation dataset\n- Research on LLM-as-judge evaluation methodology (Zheng et al., 2023) - Read when: implementing or validating LLM judge scoring to understand bias patterns and calibration\n- Netflix Engineering: \"The Infinite Software Crisis\" - Three-phase workflow and context compression at scale (AI Summit 2025) - Read when: implementing the three-phase compression workflow for large codebases or understanding production-scale context management\n\n---\n\n## Skill Metadata\n\n**Created**: 2025-12-22\n**Last Updated**: 2026-03-17\n**Author**: Agent Skills for Context Engineering Contributors\n**Version**: 1.2.0\n\nFile v1.0.0:skills/context-degradation/SKILL.md\n\n---\nname: context-degradation\ndescription: This skill should be used when the user asks to \"diagnose context problems\", \"fix lost-in-middle issues\", \"debug agent failures\", \"understand context poisoning\", or mentions context degradation, attention patterns, context clash, context confusion, or agent performance degradation. Provides patterns for recognizing and mitigating context failures.\n---\n\n# Context Degradation Patterns\n\nDiagnose and fix context failures before they cascade. Context degradation is not binary — it is a continuum that manifests through five distinct, predictable patterns: lost-in-middle, poisoning, distraction, confusion, and clash. Each pattern has specific detection signals and mitigation strategies. Treat degradation as an engineering problem with measurable thresholds, not an unpredictable failure mode.\n\n## When to Activate\n\nActivate this skill when:\n- Agent performance degrades unexpectedly during long conversations\n- Debugging cases where agents produce incorrect or irrelevant outputs\n- Designing systems that must handle large contexts reliably\n- Evaluating context engineering choices for production systems\n- Investigating \"lost in middle\" phenomena in agent outputs\n- Analyzing context-related failures in agent behavior\n\n## Core Concepts\n\nStructure context placement around the attention U-curve: beginning and end positions receive reliable attention, while middle positions suffer 10-40% reduced recall accuracy (Liu et al., 2023). This is not a model bug but a consequence of attention mechanics — the first token (often BOS) acts as an \"attention sink\" that absorbs disproportionate attention budget, leaving middle tokens under-attended as context grows.\n\nTreat context poisoning as a circuit breaker problem. Once a hallucination, tool error, or incorrect retrieved fact enters context, it compounds through repeated self-reference. A poisoned goals section causes every downstream decision to reinforce incorrect assumptions. Detection requires tracking claim provenance; recovery requires truncating to before the poisoning point or restarting with verified-only context.\n\nFilter aggressively before loading context — even a single irrelevant document measurably degrades performance on relevant tasks. Models cannot \"skip\" irrelevant context; they must attend to everything provided, creating attention competition between relevant and irrelevant content. Move information that might be needed but is not immediately relevant behind tool calls instead of pre-loading it.\n\nIsolate task contexts to prevent confusion. When context contains multiple task types or switches between objectives, models incorporate constraints from the wrong task, call tools appropriate for a different context, or blend requirements from multiple sources. Explicit task segmentation with separate context windows eliminates cross-contamination.\n\nResolve context clash through priority rules, not accumulation. When multiple correct-but-contradictory sources appear in context (version conflicts, perspective conflicts, multi-source retrieval), models cannot determine which applies. Mark contradictions explicitly, establish source precedence, and filter outdated versions before they enter context.\n\n## Detailed Topics\n\n### Lost-in-Middle: Detection and Placement Strategy\n\nPlace critical information at the beginning and end of context, never in the middle. The U-shaped attention curve means middle-positioned information suffers 10-40% reduced recall accuracy. For contexts over 4K tokens, this effect becomes significant.\n\nUse summary structures that surface key findings at attention-favored positions. Add explicit section headers and structural markers — these help models navigate long contexts by creating attention anchors. When a document must be included in full, prepend a summary of its key points and append the critical conclusions.\n\nMonitor for lost-in-middle symptoms: correct information exists in context but the model ignores it, responses contradict provided data, or the model \"forgets\" instructions given earlier in a long prompt.\n\n### Context Poisoning: Prevention and Recovery\n\nValidate all external inputs before they enter context. Tool outputs, retrieved documents, and model-generated summaries are the three primary poisoning vectors. Each introduces unverified claims that subsequent reasoning treats as ground truth.\n\nDetect poisoning through these signals: degraded output quality on previously-successful tasks, tool misalignment (wrong tools or parameters), and hallucinations that persist despite explicit correction. When these cluster, suspect poisoning rather than model capability issues.\n\nRecover by removing poisoned content, not by adding corrections on top. Truncate to before the poisoning point, restart with clean context preserving only verified information, or explicitly mark the poisoned section and request re-evaluation from scratch. Layering corrections over poisoned context rarely works — the original errors retain attention weight.\n\n### Context Distraction: Curation Over Accumulation\n\nCurate what enters context rather than relying on models to ignore irrelevant content. Research shows even a single distractor document triggers measurable performance degradation — the effect follows a step function, not a linear curve. Multiple distractors compound the problem.\n\nApply relevance filtering before loading retrieved documents. Use namespacing and structural organization to make section boundaries clear. Prefer tool-call-based access over pre-loading: store reference material behind retrieval tools so it enters context only when directly relevant to the current reasoning step.\n\n### Context Confusion: Task Isolation\n\nSegment different tasks into separate context windows. Context confusion is distinct from distraction — it concerns the model applying wrong-context constraints to the current task, not just attention dilution. Signs include responses addressing the wrong aspect of a query, tool calls appropriate for a different task, and outputs mixing requirements from multiple sources.\n\nImplement clear transitions between task contexts. Use state management that isolates objectives, constraints, and tool definitions per task. When task-switching within a single session is unavoidable, use explicit \"context reset\" markers that signal which constraints apply to the current segment.\n\n### Context Clash: Conflict Resolution Protocols\n\nEstablish source priority rules before conflicts arise. Context clash differs from poisoning — multiple pieces of information are individually correct but mutually contradictory (version conflicts, perspective differences, multi-source retrieval with divergent facts).\n\nImplement version filtering to exclude outdated information before it enters context. When contradictions are unavoidable, mark them explicitly with structured conflict annotations: state what conflicts, which source each claim comes from, and which source takes precedence. Without explicit priority rules, models resolve contradictions unpredictably.\n\n### Empirical Benchmarks and Thresholds\n\nUse these benchmarks to set design constraints — not as universal truths. The RULER benchmark found only 50% of models claiming 32K+ context maintain satisfactory performance at that length. Near-perfect needle-in-haystack scores do not predict real-world long-context performance.\n\n**Model-Specific Degradation Thresholds**\n\nDegradation onset varies significantly by model family and task type. As a general rule, expect degradation to begin at 60-70% of the advertised context window for complex retrieval tasks (RULER benchmark found only 50% of models claiming 32K+ context maintain satisfactory performance at that length). Key patterns:\n\n- **Models with extended thinking** reduce hallucination through step-by-step verification but at higher latency and token cost\n- **Models optimized for agents/coding** tend to have better attention management for tool-output-heavy contexts\n- **Models with very large context windows (1M+)** handle more raw context but still follow U-shaped degradation curves — bigger windows do not eliminate the problem, they delay it\n\nAlways benchmark degradation thresholds with your specific workload rather than relying on published benchmarks. Model-specific thresholds go stale with each model update (see Gotcha 2).\n\n### Counterintuitive Findings\n\nAccount for these research-backed surprises when designing context strategies:\n\n**Shuffled context can outperform coherent context.** Studies found incoherent (shuffled) haystacks produce better retrieval performance than logically ordered ones. Coherent context creates false associations that confuse retrieval; incoherent context forces exact matching. Do not assume that better-organized context always yields better results — test both arrangements.\n\n**Single distractors have outsized impact.** The performance hit from one irrelevant document is disproportionately large compared to adding more distractors after the first. Treat distractor prevention as binary: either keep context clean or accept significant degradation.\n\n**Low needle-question similarity accelerates degradation.** Tasks requiring inference across dissimilar content degrade faster with context length than tasks with high surface-level similarity. Design retrieval to maximize semantic overlap between queries and retrieved content.\n\n### When Larger Contexts Hurt\n\nDo not assume larger context windows improve performance. Performance remains stable up to a model-specific threshold, then degrades rapidly — the curve is non-linear with a cliff edge, not a gentle slope. For many models, meaningful degradation begins at 8K-16K tokens even when windows support much larger sizes.\n\nFactor in cost: processing a 400K token context costs exponentially more than 200K in both time and compute, not linearly more. For many applications, this makes large-context processing economically impractical.\n\nRecognize the cognitive bottleneck: even with infinite context, asking a single model to maintain quality across dozens of independent tasks creates degradation that more context cannot solve. Split tasks across sub-agents instead of expanding context.\n\n## Practical Guidance\n\n### The Four-Bucket Mitigation Framework\n\nApply these four strategies based on which degradation pattern is active:\n\n**Write** — Save context outside the window using scratchpads, file systems, or external storage. Use when context utilization exceeds 70% of the window. This keeps active context lean while preserving information access through tool calls.\n\n**Select** — Pull only relevant context into the window through retrieval, filtering, and prioritization. Use when distraction or confusion symptoms appear. Apply relevance scoring before loading; exclude anything below threshold rather than including everything available.\n\n**Compress** — Reduce tokens while preserving information through summarization, abstraction, and observation masking. Use when context is growing but all content is relevant. Replace verbose tool outputs with compact structured summaries; abstract repeated patterns into single references.\n\n**Isolate** — Split context across sub-agents or sessions to prevent any single context from growing past its degradation threshold. Use when confusion or clash symptoms appear, or when tasks are independent. This is the most aggressive strategy but often the most effective for complex multi-task systems.\n\n### Architectural Patterns for Resilience\n\nImplement just-in-time context loading: retrieve information only when the current reasoning step needs it, not preemptively. Use observation masking to replace verbose tool outputs with compact references after processing. Deploy sub-agent architectures where each agent holds only task-relevant context. Trigger compaction before context exceeds the model-specific degradation onset threshold — not after symptoms appear.\n\n## Examples\n\n**Example 1: Detecting Degradation**\n```yaml\n# Context grows during long conversation\nturn_1: 1000 tokens\nturn_5: 8000 tokens\nturn_10: 25000 tokens\nturn_20: 60000 tokens (degradation begins)\nturn_30: 90000 tokens (significant degradation)\n```\n\n**Example 2: Mitigating Lost-in-Middle**\n```markdown\n# Organize context with critical info at edges\n\n[CURRENT TASK] # At start\n- Goal: Generate quarterly report\n- Deadline: End of week\n\n[DETAILED CONTEXT] # Middle (less attention)\n- 50 pages of data\n- Multiple analysis sections\n- Supporting evidence\n\n[KEY FINDINGS] # At end\n- Revenue up 15%\n- Costs down 8%\n- Growth in Region A\n```\n\n## Guidelines\n\n1. Monitor context length and performance correlation during development\n2. Place critical information at beginning or end of context\n3. Implement compaction triggers before degradation becomes severe\n4. Validate retrieved documents for accuracy before adding to context\n5. Use versioning to prevent outdated information from causing clash\n6. Segment tasks to prevent context confusion across different objectives\n7. Design for graceful degradation rather than assuming perfect conditions\n8. Test with progressively larger contexts to find degradation thresholds\n\n## Gotchas\n\n1. **Normal variance looks like degradation**: Model output quality fluctuates naturally across runs. Do not diagnose degradation from a single drop in quality — establish a baseline over multiple runs and look for sustained, correlated decline tied to context growth. A 5-10% quality dip on one run is noise; the same dip consistently appearing after 40K tokens is signal.\n\n2. **Model-specific thresholds go stale**: The degradation onset values in benchmark tables reflect specific model versions. Provider updates, fine-tuning changes, and infrastructure shifts can move thresholds by 20-50% in either direction. Re-benchmark quarterly and after any major model update rather than treating published thresholds as permanent.\n\n3. **Needle-in-haystack scores create false confidence**: A model scoring 99% on needle-in-haystack does not mean it handles 128K tokens well in production. Needle tests measure single-fact retrieval from passive context — real workloads require multi-fact reasoning, instruction following, and synthesis across the full window. Use task-specific benchmarks that mirror actual workload patterns.\n\n4. **Contradictory retrieved documents poison silently**: When a RAG pipeline retrieves two documents that disagree on a fact, the model may silently pick one without signaling the conflict. This looks like a correct response but is effectively random. Implement contradiction detection in the retrieval layer before documents enter context.\n\n5. **Prompt quality problems masquerade as degradation**: Poor prompt structure (ambiguous instructions, missing constraints, unclear task framing) produces symptoms identical to context degradation — inconsistent outputs, ignored instructions, wrong tool usage. Before diagnosing degradation, verify the same prompt works correctly at low context lengths. If it fails at 2K tokens, the problem is the prompt, not the context.\n\n6. **Degradation is non-linear with a cliff edge**: Performance does not degrade gradually — it holds steady until a model-specific threshold, then drops sharply. Systems designed for \"graceful degradation\" often miss this pattern because monitoring checks assume linear decline. Set compaction triggers well before the cliff (at 70% of known onset), not at the onset itself.\n\n7. **Over-organizing context can backfire**: Intuitively, well-structured and coherent context should outperform disorganized content. Research shows shuffled haystacks sometimes outperform coherent ones for retrieval tasks because coherent context creates false associations. Test whether heavy structural formatting actually helps for the specific task — do not assume it does.\n\n## Integration\n\nThis skill builds on context-fundamentals and should be studied after understanding basic context concepts. It connects to:\n\n- context-optimization - Techniques for mitigating degradation\n- multi-agent-patterns - Using isolation to prevent degradation\n- evaluation - Measuring and detecting degradation in production\n\n## References\n\nInternal reference:\n- [Degradation Patterns Reference](./references/patterns.md) - Read when: debugging a specific degradation pattern and needing implementation-level detection code (attention analysis, poisoning tracking, relevance scoring, recovery procedures)\n\nRelated skills in this collection:\n- context-fundamentals - Read when: lacking foundational understanding of context windows, token budgets, or placement mechanics\n- context-optimization - Read when: degradation is diagnosed and specific mitigation techniques (compaction, compression, masking) are needed\n- evaluation - Read when: setting up production monitoring to detect degradation before it impacts users\n\nExternal resources:\n- Liu et al., 2023 \"Lost in the Middle\" - Read when: needing primary research backing for U-shaped attention claims or designing position-aware context layouts\n- RULER benchmark documentation - Read when: evaluating model claims about long-context support or comparing models for context-heavy workloads\n- Production engineering guides from AI labs - Read when: implementing context management in production infrastructure\n\n---\n\n## Skill Metadata\n\n**Created**: 2025-12-20\n**Last Updated**: 2026-03-17\n**Author**: Agent Skills for Context Engineering Contributors\n**Version**: 2.0.0\n\nFile v1.0.0:skills/context-fundamentals/SKILL.md\n\n---\nname: context-fundamentals\ndescription: This skill should be used when the user asks to \"understand context\", \"explain context windows\", \"design agent architecture\", \"debug context issues\", \"optimize context usage\", or discusses context components, attention mechanics, progressive disclosure, or context budgeting. Provides foundational understanding of context engineering for AI agent systems.\n---\n\n# Context Engineering Fundamentals\n\nContext is the complete state available to a language model at inference time — system instructions, tool definitions, retrieved documents, message history, and tool outputs. Context engineering is the discipline of curating the smallest high-signal token set that maximizes the likelihood of desired outcomes. Every paragraph below earns its tokens by teaching a non-obvious technique or providing an actionable threshold.\n\n## When to Activate\n\nActivate this skill when:\n- Designing new agent systems or modifying existing architectures\n- Debugging unexpected agent behavior that may relate to context\n- Optimizing context usage to reduce token costs or improve performance\n- Onboarding new team members to context engineering concepts\n- Reviewing context-related design decisions\n\n## Core Concepts\n\nTreat context as a finite attention budget, not a storage bin. Every token added competes for the model's attention and depletes a budget that cannot be refilled mid-inference. The engineering problem is maximizing utility per token against three constraints: the hard token limit, the softer effective-capacity ceiling (typically 60-70% of the advertised window), and the U-shaped attention curve that penalizes information placed in the middle of context.\n\nApply four principles when assembling context:\n\n1. **Informativity over exhaustiveness** — include only what matters for the current decision; design systems that can retrieve additional information on demand.\n2. **Position-aware placement** — place critical constraints at the beginning and end of context, where recall accuracy runs 85-95%; the middle drops to 76-82% (the \"lost-in-the-middle\" effect).\n3. **Progressive disclosure** — load skill names and summaries at startup; load full content only when a skill activates for a specific task.\n4. **Iterative curation** — context engineering is not a one-time prompt-writing exercise but an ongoing discipline applied every time content is passed to the model.\n\n## Detailed Topics\n\n### The Anatomy of Context\n\n**System Prompts**\nOrganize system prompts into distinct sections using XML tags or Markdown headers (background, instructions, tool guidance, output format). System prompts persist throughout the conversation, so place the most critical constraints at the beginning and end where attention is strongest.\n\nCalibrate instruction altitude to balance two failure modes. Too-low altitude hardcodes brittle logic that breaks when conditions shift. Too-high altitude provides vague guidance that fails to give concrete signals for desired behavior. Aim for heuristic-driven instructions: specific enough to guide behavior, flexible enough to generalize — for example, numbered steps with room for judgment at each step.\n\nStart minimal, then add instructions reactively based on observed failure modes rather than preemptively stuffing edge cases. Curate diverse, canonical few-shot examples that portray expected behavior instead of listing every possible scenario.\n\n**Tool Definitions**\nWrite tool descriptions that answer three questions: what the tool does, when to use it, and what it returns. Include usage context, parameter defaults, and error cases — agents cannot disambiguate tools that a human engineer cannot disambiguate either.\n\nKeep the tool set minimal. Consolidate overlapping tools because bloated tool sets create ambiguous decision points and consume disproportionate context after JSON serialization (tool schemas typically inflate 2-3x compared to equivalent plain-text descriptions).\n\n**Retrieved Documents**\nMaintain lightweight identifiers (file paths, stored queries, web links) and load data into context dynamically using just-in-time retrieval. This mirrors human cognition — maintain an index, not a copy. Strong identifiers (e.g., `customer_pricing_rates.json`) let agents locate relevant files even without search tools; weak identifiers (e.g., `data/file1.json`) force unnecessary loads.\n\nWhen chunking large documents, split at natural semantic boundaries (section headers, paragraph breaks) rather than arbitrary character limits that sever mid-concept.\n\n**Message History**\nMessage history serves as the agent's scratchpad memory for tracking progress, maintaining task state, and preserving reasoning across turns. For long-running tasks, it can grow to dominate context usage — monitor and apply compaction before it crowds out active instructions.\n\nCyclically refine history: once a tool has been called deep in the conversation, the raw result rarely needs to remain verbatim. Replace stale tool outputs with compact summaries or references to reduce low-signal bulk.\n\n**Tool Outputs**\nTool outputs typically dominate context — research shows observations can reach 83.9% of total tokens in agent trajectories. Apply observation masking: replace verbose outputs with compact references once the agent has processed the result. Retain only the five most recently accessed file contents; compress or evict older ones.\n\n### Context Windows and Attention Mechanics\n\n**The Attention Budget**\nFor n tokens, the attention mechanism computes n-squared pairwise relationships. As context grows, the model's ability to maintain these relationships degrades — not as a hard cliff but as a performance gradient. Models trained predominantly on shorter sequences have fewer specialized parameters for context-wide dependencies, creating an effective ceiling well below the nominal window size.\n\nDesign for this gradient: assume effective capacity is 60-70% of the advertised window. A 200K-token model starts degrading around 120-140K tokens, and complex retrieval accuracy can drop to as low as 15% at extreme lengths.\n\n**Position Encoding Limits**\nPosition encoding interpolation extends sequence handling beyond training lengths but introduces degradation in positional precision. Expect reduced accuracy for information retrieval and long-range reasoning at extended contexts compared to performance on shorter inputs.\n\n**Progressive Disclosure in Practice**\nImplement progressive disclosure at three levels:\n\n1. **Skill selection** — load only names and descriptions at startup; activate full skill content on demand.\n2. **Document loading** — load summaries first; fetch detail sections only when the task requires them.\n3. **Tool result retention** — keep recent results in full; compress or evict older results.\n\nKeep the boundary crisp: if a skill or document is activated, load it fully rather than partially — partial loads create confusing gaps that degrade reasoning quality.\n\n### Context Quality Versus Quantity\n\nReject the assumption that larger context windows solve memory problems. Processing cost grows disproportionately with context length — not just linear cost scaling, but degraded model performance beyond effective capacity thresholds. Long inputs remain expensive even with prefix caching.\n\nApply the signal-density test: for each piece of context, ask whether removing it would change the model's output. If not, remove it. Redundant content does not merely waste tokens — it actively dilutes attention from high-signal content.\n\n## Practical Guidance\n\n### File-System-Based Access\n\nAgents with filesystem access implement progressive disclosure naturally. Store reference materials, documentation, and data externally. Load files only when the current task requires them. Leverage the filesystem's own structure as metadata: file sizes suggest complexity, naming conventions hint at purpose, timestamps serve as proxies for relevance.\n\n### Hybrid Context Strategies\n\nPre-load stable context for speed (CLAUDE.md files, project rules, core instructions) but enable autonomous exploration for dynamic content. The decision boundary depends on content volatility:\n\n- **Low volatility** (project conventions, team standards): pre-load at session start.\n- **High volatility** (code state, external data, user-specific info): retrieve just-in-time to avoid stale context.\n\nFor complex multi-hour tasks, maintain a structured notes file (e.g., NOTES.md) that the agent updates as it works. This enables coherence across context resets without keeping everything in the active window.\n\n### Context Budgeting\n\nAllocate explicit budgets per component and monitor during development. Implement compaction triggers at 70-80% utilization — do not wait for the window to fill. Design systems that degrade gracefully: when compaction fires, preserve architectural decisions, unresolved bugs, and implementation details while discarding redundant outputs.\n\nFor sub-agent architectures, enforce a compression ratio: a sub-agent may explore using tens of thousands of tokens but must return a condensed summary of 1,000-2,000 tokens. This converts exploration breadth into context-efficient results.\n\n## Examples\n\n**Example 1: Organizing System Prompts**\n```markdown\n
` tags to preserve breaks\n3. **Remove front/back matter** - Copyright and TOC pollute the dataset\n\n``"},{"path":"examples/digital-brain-skill/SKILL.md","content":"---\nname: digital-brain\ndescription: This skill should be used when the user asks to \"write a post\", \"check my voice\", \"look up contact\", \"prepare for meeting\", \"weekly review\", \"track goals\", or mentions personal brand, content creation, network management, or voice consistency.\nversion: 1.0.0\n---\n\n# Digital Brain\n\nA structured personal operating system for managing digital presence, knowledge, relationships, and goals with AI assistance. Designed for founders building in public, content creators growing their audience, and tech-savvy professionals seeking AI-assisted personal management.\n\n**Important**: This skill uses progressive disclosure. Module-specific instructions are in each subdirectory's `.md` file. Only load what's needed for the current task.\n\n## When to Activate\n\nActivate this skill when the user:\n\n- Requests content creation (posts, threads, newsletters) - load identity/voice.md first\n- Asks for help with personal brand or positioning\n- Needs to look up or manage contacts/relationships\n- Wants to capture or develop content ideas\n- Requests meeting preparation or follow-up\n- Asks for weekly reviews or goal tracking\n- Needs to save or retrieve bookmarked resources\n- Wants to organize research or learning materials\n\n**Trigger phrases**: \"write a post\", \"my voice\", \"content ideas\", \"who is [name]\", \"prepare for meeting\", \"weekly review\", \"save this\", \"my goals\"\n\n## Core Concepts\n\n### Progressive Disclosure Architecture\n\nThe Digital Brain follows a three-level loading pattern:\n\n| Level | When Loaded | Content |\n|-------|-------------|---------|\n| **L1: Metadata** | Always | This SKILL.md overview |\n| **L2: Module Instructions** | On-demand | `[module]/[MODULE].md` files |\n| **L3: Data Files** | As-needed | `.jsonl`, `.yaml`, `.md` data |\n\n### File Format Strategy\n\nFormats chosen for optimal agent parsing:\n\n- **JSONL** (`.jsonl`): Append-only logs - ideas, posts, contacts, interactions\n- **YAML** (`.yaml`): Structured configs - goals, values, circles\n- **Markdown** (`.md`): Narrative content - voice, brand, calendar, todos\n- **XML** (`.xml`): Complex prompts - content generation templates\n\n### Append-Only Data Integrity\n\nJSONL files are **append-only**. Never delete entries:\n- Mark as `\"status\": \"archived\"` instead of deleting\n- Preserves history for pattern analysis\n- Enables \"what worked\" retrospectives\n\n## Detailed Topics\n\n### Module Overview\n\n```\ndigital-brain/\n├── identity/ → Voice, brand, values (READ FIRST for content)\n├── content/ → Ideas, drafts, posts, calendar\n├── knowledge/ → Bookmarks, research, learning\n├── network/ → Contacts, interactions, intros\n├── operations/ → Todos, goals, meetings, metrics\n└── agents/ → Automation scripts\n```\n\n### Identity Module (Critical for Content)\n\n**Always read `identity/voice.md` before generating any content.**\n\nContains:\n- `voice.md` - Tone, style, vocabulary, patterns\n- `brand.md` - Positioning, audience, content pillars\n- `values.yaml` - Core beliefs and principl"},{"path":"examples/interleaved-thinking/generated_skills/comprehensive-research-agent/SKILL.md","content":"---\nname: comprehensive-research-agent\ndescription: \"Ensure thorough validation, error recovery, and transparent reasoning in research tasks with multiple tool calls\"\n---\n\n# Comprehensive Research Agent Best Practices\n\nThis skill addresses common failures in multi-step research tasks: unhandled tool errors, missing validation, opaque reasoning, and premature conclusions. It provides structured protocols for source validation, error recovery, and thinking transparency that significantly improves research quality and reliability.\n\n## When to Activate\n\n- Task involves web research with search, read_url, or fetch operations\n- Task requires gathering information from multiple sources\n- Task has explicit requirements for completeness or verification\n- Task includes file operations that need validation (save, write, read)\n- Any research or information-gathering workflow with 3+ tool interactions\n\n## Core Concepts\n\n- Validation Checkpoints: Explicit verification steps at phase transitions to confirm tool outputs, source relevance, and information completeness before proceeding\n- Error Recovery Protocols: Mandatory acknowledgment and handling of tool failures with fallback strategies rather than silent continuation\n- Source Traceability: Maintaining clear tracking of which sources were actually retrieved vs. referenced from prior knowledge to prevent hallucination\n- Substantive Thinking Blocks: Detailed reasoning traces that document insights, connections, gaps, and decision rationale at each step\n- Cross-Source Validation: Verifying key claims against multiple sources and explicitly noting consensus, contradictions, and information gaps\n\n## Patterns to Avoid\n\n- *Silent Tool Failure**: A tool call returns an error (404, timeout, invalid URL) but the agent proceeds without acknowledging it, potentially missing critical information. Always log failures and attempt recovery or document the gap.\n- *Vague Completion Claims**: Agent declares 'I have enough information' or 'research is comprehensive' without specifying what was learned, what sources support claims, or what gaps remain. Replace with specific summaries of coverage.\n- *Unvalidated Source Selection**: Agent reads URLs from search results without evaluating relevance, credibility, or recency first. This wastes tool calls on low-quality sources. Always rank and prioritize sources before deep reading.\n- *Generic Thinking Blocks**: Thinking contains only next-action descriptions ('Now I will search for X') without analysis of what was learned, how it connects to the goal, or what questions remain. Thinking should be substantive and reflective.\n- *Verification Method Error**: Using list_directory to verify file creation can produce false negatives due to caching. Always use read_file for actual content verification.\n- *Citation Without Retrieval**: Citing sources (URLs, paper titles) in the final report that were never successfully fetched or read. Track sources explicitly and prohibit citing unretrieved"},{"path":"examples/interleaved-thinking/SKILL.md","content":"---\nname: reasoning-trace-optimizer\ndescription: \"Debug and optimize AI agents by analyzing reasoning traces. Activates on 'debug agent', 'optimize prompt', 'analyze reasoning', 'why did the agent fail', 'improve agent performance', or when diagnosing agent failures and context degradation.\"\n---\n\n# Reasoning Trace Optimizer\n\nDebug and optimize AI agents by analyzing their reasoning traces. This skill uses MiniMax M2.1's interleaved thinking to provide deep insight into agent decision-making and generate concrete improvements.\n\n## When to Activate\n\n- User asks to \"debug agent\", \"analyze reasoning\", or \"optimize prompt\"\n- Agent task fails and user wants to understand why\n- User mentions \"context degradation\", \"tool confusion\", or \"instruction drift\"\n- Request to improve agent performance or reduce errors\n- User wants to generate shareable learnings from debugging sessions\n- After repeated failures on similar tasks\n\n## Core Concepts\n\n### Interleaved Thinking\n\nUnlike standard reasoning models that think once at the start, interleaved thinking allows reasoning BETWEEN each tool interaction. This is critical because:\n\n1. **Long-horizon tasks** require maintaining focus across many turns\n2. **External perturbations** (tool outputs, environment changes) need real-time adaptation\n3. **Debugging** requires seeing HOW decisions were made, not just WHAT was output\n\n### The Optimization Loop\n\n```\nExecute Agent → Capture Traces → Analyze Patterns → Optimize Prompt → Re-run\n ↑____________|\n```\n\nEach iteration improves the prompt based on detected patterns until convergence.\n\n### Pattern Detection\n\nCommon failure patterns the analyzer detects:\n\n| Pattern | Description |\n|---------|-------------|\n| `context_degradation` | Model loses track of information over long contexts |\n| `tool_confusion` | Model misunderstands tool capabilities or outputs |\n| `instruction_drift` | Model gradually deviates from original instructions |\n| `goal_abandonment` | Model stops pursuing the original goal |\n| `circular_reasoning` | Model repeats similar actions without progress |\n| `premature_conclusion` | Model concludes before completing the task |\n\n## Usage Modes\n\n### Mode 1: M2.1 Agent Debugging\n\nRun a task through M2.1 and analyze its reasoning:\n\n```python\nfrom reasoning_trace_optimizer import TraceCapture, TraceAnalyzer\n\ncapture = TraceCapture()\ntrace = capture.run(\n task=\"Search for Python tutorials and summarize them\",\n system_prompt=\"You are a research assistant.\",\n tools=[search_tool],\n tool_executor=execute_search\n)\n\nanalyzer = TraceAnalyzer()\nanalysis = analyzer.analyze(trace)\n\nprint(f\"Score: {analysis.overall_score}/100\")\nfor pattern in analysis.patterns:\n print(f\"Found: {pattern.type.value} - {pattern.suggestion}\")\n```\n\n### Mode 2: Full Optimization Loop\n\nAutomatically iterate until the prompt is optimized:\n\n```python\nfrom reasoning_trace_optimizer import OptimizationLoop, LoopConfig\n\nconfig = LoopCo"},{"path":"SKILL.md","content":"---\nname: context-engineering-collection\ndescription: A comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.\n---\n\n# Agent Skills for Context Engineering\n\nThis collection provides structured guidance for building production-grade AI agent systems through effective context engineering.\n\n## When to Activate\n\nActivate these skills when:\n- Building new agent systems from scratch\n- Optimizing existing agent performance\n- Debugging context-related failures\n- Designing multi-agent architectures\n- Creating or evaluating tools for agents\n- Implementing memory and persistence layers\n\n## Skill Map\n\n### Foundational Context Engineering\n\n**Understanding Context Fundamentals**\nContext is not just prompt text—it is the complete state available to the language model at inference time, including system instructions, tool definitions, retrieved documents, message history, and tool outputs. Effective context engineering means understanding what information truly matters for the task at hand and curating that information for maximum signal-to-noise ratio.\n\n**Recognizing Context Degradation**\nLanguage models exhibit predictable degradation patterns as context grows: the \"lost-in-middle\" phenomenon where information in the center of context receives less attention; U-shaped attention curves that prioritize beginning and end; context poisoning when errors compound; and context distraction when irrelevant information overwhelms relevant content.\n\n### Architectural Patterns\n\n**Multi-Agent Coordination**\nProduction multi-agent systems converge on three dominant patterns: supervisor/orchestrator architectures with centralized control, peer-to-peer swarm architectures for flexible handoffs, and hierarchical structures for complex task decomposition. The critical insight is that sub-agents exist primarily to isolate context rather than to simulate organizational roles.\n\n**Memory System Design**\nMemory architectures range from simple scratchpads to sophisticated temporal knowledge graphs. Vector RAG provides semantic retrieval but loses relationship information. Knowledge graphs preserve structure but require more engineering investment. The file-system-as-memory pattern enables just-in-time context loading without stuffing context windows.\n\n**Filesystem-Based Context**\nThe filesystem provides a single interface for storing, retrieving, and updating effectively unlimited context. Key patterns include scratch pads for tool output offloading, plan persistence for long-horizon tasks, sub-agent communication via shared files, and dynamic skill loading. Agents use `ls`, `glob`, `grep`, and `read_file` for targeted context discovery, often outperforming semantic search for structural queries.\n\n**Hosted Agent Infrastructure**\nBackground coding agents run in remote sandboxed environments rather than on local machines"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"A comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, o... Skill: Agent Skills For Context Engineering Owner: sanguoxxx Summary: A comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, o... Tags: latest:1.0.0 Version history: v1.0.0 | 2026-04-29T22:47:01.626Z | auto - Initial release of a comprehensive skill collection for context engineering in AI agent systems. - Provides st","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":2112,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-12T02:25:23.583Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-12T02:25:23.583Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T18:46:22.746Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}