Author or refine agent instructions: $ARGUMENTS
Before Starting
- Search OpenAI docs for prompt engineering guidance:
- Use
mcp__openai-docs__search_openai_docs with query "system instructions best practices" for latest recommendations
- Use
mcp__openai-docs__search_openai_docs with query "agent instructions" for agents-specific patterns
- Read the existing instruction architecture to understand the composable pattern:
/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/core.ts — identity + voice markers + failure modes
/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/themes.ts — theme-specific layers (metanoia, movemental, mdna)
/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/modes.ts — pedagogical modes (teacher, coach, reflection, mentor, companion)
/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/styles.ts — interaction styles (conversation, challenge, socratic, evaluative, explainer)
/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/context.ts — dynamic user context per run
- Read the writing assistant instruction pattern:
/Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions.ts — buildWritingAssistantPrompt() with pluggable content sources
/Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions/identity.ts — voice identity template
/Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions/content-forms.ts — content form templates
/Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions/examples.ts — voice calibration examples
Instruction Architecture
Instructions are composed from layers that are concatenated at runtime:
┌─────────────────────────────────┐
│ STATIC (cached by dimension key)│
│ ┌───────────────────────────┐ │
│ │ Core Identity │ │ — who the agent IS, voice markers, failure modes
│ │ + Theme Layer │ │ — theological/framework lens
│ │ + Mode Layer │ │ — pedagogical approach
│ │ + Style Layer │ │ — interaction pattern
│ └───────────────────────────┘ │
├─────────────────────────────────┤
│ DYNAMIC (fresh per run) │
│ ┌───────────────────────────┐ │
│ │ User Context │ │ — name, role, language, kairos, engagement
│ │ + Conversation History │ │ — continuity from prior turns
│ │ + Page/Content Context │ │ — what the user is currently viewing
│ └───────────────────────────┘ │
└─────────────────────────────────┘
Static sections are cached by key {theme}-{mode}-{style} (max 100 entries) for performance.
Dynamic sections are NEVER cached — they change per run.
Writing Instructions
Core Identity Section
Define who the agent is. Include:
- Role statement: "You are [name], a [role] who [purpose]."
- Voice markers: 3-5 dimensions that define the voice (e.g., Christocentric Anchoring, Pastoral Warmth, Narrative Imagery, Theological Depth, Prophetic Intensity)
- Signature elements: Recurring phrases, metaphors, or framing devices the voice uses
- Failure modes: What the agent must NOT do (e.g., "Never simplify theological terms", "Never invent citations")
Theme/Mode/Style Layers
Each adds a focused paragraph or two. Keep them modular — they should make sense in any combination.
Dynamic Context Section
Built from RunContext at runtime. Use the DynamicInstructionsGenerator pattern:
export const myDynamicInstructions: DynamicInstructionsGenerator = async (
baseInstructions: string,
context: Record<string, unknown>
) => {
const sections: string[] = [baseInstructions];
if (context.userName) {
sections.push(`## User Context\nYou are speaking with ${context.userName}.`);
}
return sections.join('\n\n');
};
For Writing Assistant Instructions
Use the pluggable content source pattern from movemental-dashboard:
export function buildWritingAssistantPrompt(content: AgentPromptContent): string {
return [
content.headerTemplate, // from voice_identities table
content.coreIdentity, // from voice_identities table
content.platformContext, // from voice_identities table
buildContentFormSection(content.contentForms), // from content_form_templates table
buildExamplesSection(content.examples), // from writing_examples table
].filter(Boolean).join('\n\n');
}
This allows org-specific voice swapping without code changes.
Rules
- Never hardcode tenant-specific names, content, or theological positions — use
tenantConfig or DB-backed content
- Keep total instruction length under 10,000 tokens (static + dynamic combined)
- Voice markers should be descriptive enough for the LLM to calibrate tone
- Failure modes are as important as positive instructions — always include them
- Test instruction changes by running the agent and checking voice fidelity
- For book-related agents, include mandatory retrieval instructions ("Always use file_search before answering questions about specific books")
- Use markdown formatting in instructions — LLMs parse it well
- Check OpenAI docs MCP for any changes to instruction handling or token limits
1---2name: agent-instructions3description: Author or refine agent system prompts using composable instruction layers (identity, theme, mode, style, context). Use when writing or tuning agent behavior.4user-invocable: true5allowed-tools: Read, Write, Edit, Grep, Glob, Agent, mcp__openai-docs__search_openai_docs, mcp__openai-docs__fetch_openai_doc6metadata:7 source: https://skillmd.com/skills/joshuashepherd/agent-instructions8---910Author or refine agent instructions: $ARGUMENTS1112## Before Starting13141. Search OpenAI docs for prompt engineering guidance:15 - Use `mcp__openai-docs__search_openai_docs` with query "system instructions best practices" for latest recommendations16 - Use `mcp__openai-docs__search_openai_docs` with query "agent instructions" for agents-specific patterns172. Read the existing instruction architecture to understand the composable pattern:18 - `/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/core.ts` — identity + voice markers + failure modes19 - `/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/themes.ts` — theme-specific layers (metanoia, movemental, mdna)20 - `/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/modes.ts` — pedagogical modes (teacher, coach, reflection, mentor, companion)21 - `/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/styles.ts` — interaction styles (conversation, challenge, socratic, evaluative, explainer)22 - `/Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/context.ts` — dynamic user context per run233. Read the writing assistant instruction pattern:24 - `/Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions.ts` — `buildWritingAssistantPrompt()` with pluggable content sources25 - `/Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions/identity.ts` — voice identity template26 - `/Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions/content-forms.ts` — content form templates27 - `/Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions/examples.ts` — voice calibration examples2829## Instruction Architecture3031Instructions are composed from **layers** that are concatenated at runtime:3233```34┌─────────────────────────────────┐35│ STATIC (cached by dimension key)│36│ ┌───────────────────────────┐ │37│ │ Core Identity │ │ — who the agent IS, voice markers, failure modes38│ │ + Theme Layer │ │ — theological/framework lens39│ │ + Mode Layer │ │ — pedagogical approach40│ │ + Style Layer │ │ — interaction pattern41│ └───────────────────────────┘ │42├─────────────────────────────────┤43│ DYNAMIC (fresh per run) │44│ ┌───────────────────────────┐ │45│ │ User Context │ │ — name, role, language, kairos, engagement46│ │ + Conversation History │ │ — continuity from prior turns47│ │ + Page/Content Context │ │ — what the user is currently viewing48│ └───────────────────────────┘ │49└─────────────────────────────────┘50```5152### Static sections are cached by key `{theme}-{mode}-{style}` (max 100 entries) for performance.53### Dynamic sections are NEVER cached — they change per run.5455## Writing Instructions5657### Core Identity Section58Define who the agent is. Include:59- **Role statement**: "You are [name], a [role] who [purpose]."60- **Voice markers**: 3-5 dimensions that define the voice (e.g., Christocentric Anchoring, Pastoral Warmth, Narrative Imagery, Theological Depth, Prophetic Intensity)61- **Signature elements**: Recurring phrases, metaphors, or framing devices the voice uses62- **Failure modes**: What the agent must NOT do (e.g., "Never simplify theological terms", "Never invent citations")6364### Theme/Mode/Style Layers65Each adds a focused paragraph or two. Keep them modular — they should make sense in any combination.6667### Dynamic Context Section68Built from `RunContext` at runtime. Use the `DynamicInstructionsGenerator` pattern:6970```typescript71export const myDynamicInstructions: DynamicInstructionsGenerator = async (72 baseInstructions: string,73 context: Record<string, unknown>74) => {75 const sections: string[] = [baseInstructions];7677 if (context.userName) {78 sections.push(`## User Context\nYou are speaking with ${context.userName}.`);79 }8081 return sections.join('\n\n');82};83```8485## For Writing Assistant Instructions8687Use the pluggable content source pattern from movemental-dashboard:8889```typescript90export function buildWritingAssistantPrompt(content: AgentPromptContent): string {91 return [92 content.headerTemplate, // from voice_identities table93 content.coreIdentity, // from voice_identities table94 content.platformContext, // from voice_identities table95 buildContentFormSection(content.contentForms), // from content_form_templates table96 buildExamplesSection(content.examples), // from writing_examples table97 ].filter(Boolean).join('\n\n');98}99```100101This allows org-specific voice swapping without code changes.102103## Rules104105- Never hardcode tenant-specific names, content, or theological positions — use `tenantConfig` or DB-backed content106- Keep total instruction length under 10,000 tokens (static + dynamic combined)107- Voice markers should be descriptive enough for the LLM to calibrate tone108- Failure modes are as important as positive instructions — always include them109- Test instruction changes by running the agent and checking voice fidelity110- For book-related agents, include mandatory retrieval instructions ("Always use file_search before answering questions about specific books")111- Use markdown formatting in instructions — LLMs parse it well112- Check OpenAI docs MCP for any changes to instruction handling or token limits