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
1---
2name: expert-instruction
3description: |
4 System prompt design and instruction crafting for AI agents. Covers persona definition, constraint specification, output formatting, tool use instructions, multi-turn behavior, and guardrail design.
5
6 Use when writing system prompts for AI products, designing agent personas, specifying behavioral constraints, crafting tool-use instructions, or building multi-step agent workflows.
7license: MIT
8metadata:
9 author: oakoss
10 version: '1.0'
11user-invocable: false
12---
13
14# Expert Instruction Design
15
16## Overview
17
18Expert 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.
19
20**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.
21
22**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.
23
24## Quick Reference
25
26| Pattern | Purpose | Key Points |
27| ------------------------ | ---------------------------------------- | ------------------------------------------------ |
28| Identity block | Define who the agent is | Role, expertise, communication style |
29| Capability declaration | State what the agent can do | Explicit tool list, domain boundaries |
30| Constraint specification | Define behavioral boundaries | Hard limits, soft preferences, escalation rules |
31| Output format rules | Ensure consistent response structure | Templates, progressive disclosure, length limits |
32| Tool use instructions | Guide when and how to use tools | Selection criteria, error handling, sequencing |
33| Multi-turn behavior | Handle conversation continuity | Context tracking, topic switching, memory |
34| Guardrails | Prevent harmful or out-of-scope behavior | Content boundaries, instruction hierarchy |
35| Escalation triggers | Define when to hand off to humans | Confidence thresholds, scope boundaries |
36
37## Common Mistakes
38
39| Mistake | Correct Pattern |
40| ---------------------------------------- | ------------------------------------------------------------- |
41| System prompt over 4000 tokens | Keep under 2000 tokens, move details to reference docs |
42| Contradictory instructions | Audit for conflicts, establish priority order |
43| Vague persona ("be helpful") | Specific: expertise domain, response style, knowledge bounds |
44| No escalation path | Define when agent should defer to human or say "I don't know" |
45| Listing every edge case | State principles, provide examples for ambiguous cases only |
46| Mixing identity and task instructions | Separate: identity block first, task instructions second |
47| No output format specification | Define structure: headings, lists, code blocks, length |
48| Tool instructions without error handling | Include fallback behavior when tools fail or return errors |
49| Testing only happy-path inputs | Test adversarial, off-topic, and edge case inputs |
50| Deploying without versioning | Track system prompt versions, log changes, enable rollback |
51
52## Delegation
53
54- **Prompt technique exploration**: Use `Explore` agent to research patterns
55- **System prompt testing**: Use `Task` agent to run adversarial test suites
56- **Code review**: Delegate to `code-reviewer` agent for integration code
57
58> If the `prompt` skill is available, delegate general prompt engineering techniques (CoT, few-shot, structured output) to it.
59> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s prompt -a claude-code -y`
60
61## References
62
63- [System prompt design: anatomy, personas, tools, and multi-turn behavior](references/system-prompt-design.md)
64- [Guardrails and testing: behavioral boundaries, versioning, and production readiness](references/guardrails-and-testing.md)
oakoss