expert-instruction

Expert Instruction Design

Overview

Expert instruction design focuses on crafting system prompts that define how an AI agent behaves, what it can and cannot do, and how it responds across interactions. Unlike general prompt engineering (which optimizes individual queries), this skill covers the persistent behavioral layer that shapes an agent's identity, capabilities, and constraints.

When to use: Writing system prompts for AI products, defining agent personas for customer-facing tools, specifying behavioral guardrails, crafting tool-use guidance, or designing multi-step agent workflows.

When NOT to use: One-off prompt optimization (use the prompt skill), fine-tuning or training-time configuration, infrastructure-level safety (use model provider safety features), or tasks that do not involve LLM agent behavior.

Quick Reference

Pattern	Purpose	Key Points
Identity block	Define who the agent is	Role, expertise, communication style
Capability declaration	State what the agent can do	Explicit tool list, domain boundaries
Constraint specification	Define behavioral boundaries	Hard limits, soft preferences, escalation rules
Output format rules	Ensure consistent response structure	Templates, progressive disclosure, length limits
Tool use instructions	Guide when and how to use tools	Selection criteria, error handling, sequencing
Multi-turn behavior	Handle conversation continuity	Context tracking, topic switching, memory
Guardrails	Prevent harmful or out-of-scope behavior	Content boundaries, instruction hierarchy
Escalation triggers	Define when to hand off to humans	Confidence thresholds, scope boundaries

Common Mistakes

Mistake	Correct Pattern
System prompt over 4000 tokens	Keep under 2000 tokens, move details to reference docs
Contradictory instructions	Audit for conflicts, establish priority order
Vague persona ("be helpful")	Specific: expertise domain, response style, knowledge bounds
No escalation path	Define when agent should defer to human or say "I don't know"
Listing every edge case	State principles, provide examples for ambiguous cases only
Mixing identity and task instructions	Separate: identity block first, task instructions second
No output format specification	Define structure: headings, lists, code blocks, length
Tool instructions without error handling	Include fallback behavior when tools fail or return errors
Testing only happy-path inputs	Test adversarial, off-topic, and edge case inputs
Deploying without versioning	Track system prompt versions, log changes, enable rollback

Delegation

• Prompt technique exploration: Use Explore agent to research patterns
• System prompt testing: Use Task agent to run adversarial test suites
• Code review: Delegate to code-reviewer agent for integration code

If the prompt skill is available, delegate general prompt engineering techniques (CoT, few-shot, structured output) to it. Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s prompt -a claude-code -y

References

• System prompt design: anatomy, personas, tools, and multi-turn behavior
• Guardrails and testing: behavioral boundaries, versioning, and production readiness