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
Exploreagent to research patterns - System prompt testing: Use
Taskagent to run adversarial test suites - Code review: Delegate to
code-revieweragent for integration code
If the
promptskill 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