context-assembly

Context Assembly for External Models

Purpose

Guide context assembly decisions when sharing conversation context with external CLI models (Codex, Gemini). The core challenge: Claude has full conversation context, but spawned CLI tools start completely cold. This skill helps decide what to include and how much based on the question type.

Context Levels

Light Context

Include minimal context for self-contained questions.

When to use:

• General knowledge questions ("What's the best pattern for X?")
• Questions not referencing specific files in the conversation
• Quick opinion requests
• Architecture/design philosophy questions

What to include:

• The question verbatim
• Brief task summary (1-2 sentences)
• File paths only (no contents) if relevant
• Key constraints mentioned in conversation

Heavy Context

Include full context for code-specific questions.

When to use:

• Questions about specific code discussed in the conversation
• Code review requests
• Architecture decisions requiring codebase knowledge
• Debugging or troubleshooting questions
• Questions where CLAUDE.md conventions are relevant

What to include:

• The question verbatim
• Detailed task description
• Relevant CLAUDE.md sections (not the entire file — select relevant sections)
• File contents (up to 5 most relevant files)
• Git diff when reviewing changes
• Decisions already made and constraints
• Instructions tailored to the question type

Assembly Decision Process

1. Read the question — classify it as general vs code-specific
2. Scan conversation history — identify files read, decisions made, constraints discussed
3. Select context level — light for general, heavy for code-specific
4. Choose relevant files — pick the 3-5 most relevant files from the conversation (not every file ever mentioned)
5. Summarize conventions — extract only the CLAUDE.md sections relevant to the question
6. Write clear instructions — tell the model its role and expected output format

Writing Effective Instructions

The --instructions parameter tells the external model how to approach the question. Write instructions that:

• Define the model's role ("You are a senior engineer reviewing...")
• Specify the output format ("For each issue, provide file, line, severity...")
• Set scope boundaries ("Focus only on the changed files")
• Mention what to prioritize ("Prioritize security issues over style nits")

Using the Assembly Script

The assemble-context.sh script in ${CLAUDE_PLUGIN_ROOT}/scripts/ handles file writing. Pass arguments based on context level decisions:

Key parameters:

• --question: Always include the full question text
• --task: Brief summary of the current task/conversation context
• --conventions: Relevant project standards (selected from CLAUDE.md)
• --files: Comma-separated file paths to include
• --instructions: Role and output format for the external model
• --level: light or heavy (controls whether file contents are included)
• --include-diff: Add when reviewing code changes
• --diff-base: Branch to diff against (default: HEAD)
• --output: Custom output path (optional, auto-generated if omitted)

Context Size Guidelines

External CLI tools have context limits too. Keep packages reasonable:

• Light: Aim for <2,000 words total
• Heavy: Aim for <15,000 words total
• Files: Include at most 5 files; prefer smaller, focused files
• Diff: For large diffs, summarize and include only relevant hunks
• Conventions: Extract 5-15 bullet points, not the full CLAUDE.md

Common Patterns

For /second-opinion

Determine level from the question. Most questions are light unless they reference specific code or files from the conversation.

For /review-models

Always heavy. Include the full diff, changed file contents, and relevant code standards.

For /debate

Usually light. The models need the topic and project constraints, but full file contents are rarely needed for a position argument.