prompt-efficiency

Prompt Efficiency

Request Classification (Runtime)

The classify-request hook injects task complexity on each prompt:

• MINIMAL: Direct edit preferred. Skip Agent Teams and heavy delegation.
• STANDARD: Normal flow. No special action.
• HEAVY: Check context budget before spawning Agent Teams. If > 40%, prefer single subagent.

Skill Profile Filtering

If .context/architecture/.skill-profile.json exists (generated by /init), check it when a skill auto-loads. If the skill is listed in irrelevant_skills, deprioritize its patterns — the project doesn't use that stack. Skills can still load if genuinely needed (e.g., adding a new technology).

Unpopulated Skill Guard

• Skills containing only HTML comment placeholders (<!-- ... -->) and no actionable content should be treated as unpopulated
• When an auto-loaded skill is unpopulated (e.g., testing-conventions or api-conventions before /init), skip it — do not apply its patterns or reference its content
• To populate: run /init (auto-detects), /update-skill [name] (from .context/ knowledge), or /create-skill [name] (full pipeline)
• After populating, the skill loads normally on subsequent triggers

Delegation Rules

• Pass only the task + relevant file paths to subagents — not full context summaries
• Agent reads .context/ independently — don't duplicate its content in the delegation prompt
• Each Agent Team teammate gets only their file scope, not the full PRP

Context Loading Rules

• Read only the section needed from .context/ files, not the full file
• Skills with a REFERENCE.md file: load only SKILL.md (Tier 1) by default; read REFERENCE.md only when editing MCP configs or the user explicitly asks for setup details
• Shared instructions in .claude/instructions/ are referenced, not inlined — agents and commands point to them instead of duplicating content

Context Budget Thresholds

• < 40%: Full Agent Teams allowed
• 40-50%: Prefer single subagent over Agent Team
• > 50%: Save state, prepare to /clear + /resume
• > 60%: Stop. /clear. /resume.

The context-budget hook monitors tool call count as a proxy and warns at thresholds.

Output Budgeting Rules

• Grep: Always set head_limit — default 50 for exploratory searches, 250 max for targeted
• Read: Use limit parameter for files > 200 lines; read only the section needed
• Read PDF: Always specify pages; never read > 10 pages at once
• Bash: Pipe through head/tail when output may be large (ls, find, git log)
• MCP tools: When a tool accepts maxLength, limit, count, or similar parameters, always set them to the minimum needed
• Post-output rule: If a tool returns large output (~5KB+), summarize relevant findings in 5-10 bullets before continuing — do not echo or reference the raw output verbatim

MCP Delegation Rules

• When a task requires 3+ MCP tool calls, delegate to mcp-researcher agent (or researcher as fallback)
• Browser automation sequences (navigate + interact + inspect): always delegate
• Database exploration (multiple queries to understand schema/data): always delegate
• Single MCP lookups (one query-docs, one list_pages): direct calls acceptable
• Raw MCP output stays in the subagent's context; only the summary enters the lead agent's context

Anti-Patterns (Token Waste)

• Repeating agent instructions in command prompts (agents have their own instructions)
• Loading full MCP config blocks when only querying data
• Summarizing .context/ docs in delegation prompts (agent reads them directly)
• Spawning Agent Teams for < 3 independent steps
• Loading skills flagged as irrelevant_skills in the skill profile