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:
{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/core.ts — identity + voice markers + failure modes
{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/themes.ts — theme-specific layers (metanoia, movemental, mdna)
{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/modes.ts — pedagogical modes (teacher, coach, reflection, mentor, companion)
{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/styles.ts — interaction styles (conversation, challenge, socratic, evaluative, explainer)
{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/context.ts — dynamic user context per run
- Read the writing assistant instruction pattern:
{{PROJECT_ROOT}}/{{AGENTS_DIR}}/writing-assistant/instructions.ts — buildWritingAssistantPrompt() with pluggable content sources
{{PROJECT_ROOT}}/{{AGENTS_DIR}}/writing-assistant/instructions/identity.ts — voice identity template
{{PROJECT_ROOT}}/{{AGENTS_DIR}}/writing-assistant/instructions/content-forms.ts — content form templates
{{PROJECT_ROOT}}/{{AGENTS_DIR}}/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
brandConfig 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: write-instructions3description: Author or refine agent instructions — use when asked to write a system prompt, create or update agent instructions, compose instruction layers (identity, theme, mode, style, dynamic context), or tune agent voice and behavior.4metadata:5 source: https://skillmd.com/skills/joshuashepherd/write-instructions6---78Author or refine agent instructions: $ARGUMENTS910## Before Starting11121. Search OpenAI docs for prompt engineering guidance:13 - Use `mcp__openai-docs__search_openai_docs` with query "system instructions best practices" for latest recommendations14 - Use `mcp__openai-docs__search_openai_docs` with query "agent instructions" for agents-specific patterns152. Read the existing instruction architecture to understand the composable pattern:16 - `{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/core.ts` — identity + voice markers + failure modes17 - `{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/themes.ts` — theme-specific layers (metanoia, movemental, mdna)18 - `{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/modes.ts` — pedagogical modes (teacher, coach, reflection, mentor, companion)19 - `{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/styles.ts` — interaction styles (conversation, challenge, socratic, evaluative, explainer)20 - `{{PROJECT_ROOT}}/{{AGENTS_DIR}}/ai-lab/instructions/context.ts` — dynamic user context per run213. Read the writing assistant instruction pattern:22 - `{{PROJECT_ROOT}}/{{AGENTS_DIR}}/writing-assistant/instructions.ts` — `buildWritingAssistantPrompt()` with pluggable content sources23 - `{{PROJECT_ROOT}}/{{AGENTS_DIR}}/writing-assistant/instructions/identity.ts` — voice identity template24 - `{{PROJECT_ROOT}}/{{AGENTS_DIR}}/writing-assistant/instructions/content-forms.ts` — content form templates25 - `{{PROJECT_ROOT}}/{{AGENTS_DIR}}/writing-assistant/instructions/examples.ts` — voice calibration examples2627## Instruction Architecture2829Instructions are composed from **layers** that are concatenated at runtime:3031```32┌─────────────────────────────────┐33│ STATIC (cached by dimension key)│34│ ┌───────────────────────────┐ │35│ │ Core Identity │ │ — who the agent IS, voice markers, failure modes36│ │ + Theme Layer │ │ — theological/framework lens37│ │ + Mode Layer │ │ — pedagogical approach38│ │ + Style Layer │ │ — interaction pattern39│ └───────────────────────────┘ │40├─────────────────────────────────┤41│ DYNAMIC (fresh per run) │42│ ┌───────────────────────────┐ │43│ │ User Context │ │ — name, role, language, kairos, engagement44│ │ + Conversation History │ │ — continuity from prior turns45│ │ + Page/Content Context │ │ — what the user is currently viewing46│ └───────────────────────────┘ │47└─────────────────────────────────┘48```4950### Static sections are cached by key `{theme}-{mode}-{style}` (max 100 entries) for performance.51### Dynamic sections are NEVER cached — they change per run.5253## Writing Instructions5455### Core Identity Section56Define who the agent is. Include:57- **Role statement**: "You are [name], a [role] who [purpose]."58- **Voice markers**: 3-5 dimensions that define the voice (e.g., Christocentric Anchoring, Pastoral Warmth, Narrative Imagery, Theological Depth, Prophetic Intensity)59- **Signature elements**: Recurring phrases, metaphors, or framing devices the voice uses60- **Failure modes**: What the agent must NOT do (e.g., "Never simplify theological terms", "Never invent citations")6162### Theme/Mode/Style Layers63Each adds a focused paragraph or two. Keep them modular — they should make sense in any combination.6465### Dynamic Context Section66Built from `RunContext` at runtime. Use the `DynamicInstructionsGenerator` pattern:6768```typescript69export const myDynamicInstructions: DynamicInstructionsGenerator = async (70 baseInstructions: string,71 context: Record<string, unknown>72) => {73 const sections: string[] = [baseInstructions];7475 if (context.userName) {76 sections.push(`## User Context\nYou are speaking with ${context.userName}.`);77 }7879 return sections.join('\n\n');80};81```8283## For Writing Assistant Instructions8485Use the pluggable content source pattern from movemental-dashboard:8687```typescript88export function buildWritingAssistantPrompt(content: AgentPromptContent): string {89 return [90 content.headerTemplate, // from voice_identities table91 content.coreIdentity, // from voice_identities table92 content.platformContext, // from voice_identities table93 buildContentFormSection(content.contentForms), // from content_form_templates table94 buildExamplesSection(content.examples), // from writing_examples table95 ].filter(Boolean).join('\n\n');96}97```9899This allows org-specific voice swapping without code changes.100101## Rules102103- Never hardcode tenant-specific names, content, or theological positions — use `brandConfig` or DB-backed content104- Keep total instruction length under 10,000 tokens (static + dynamic combined)105- Voice markers should be descriptive enough for the LLM to calibrate tone106- Failure modes are as important as positive instructions — always include them107- Test instruction changes by running the agent and checking voice fidelity108- For book-related agents, include mandatory retrieval instructions ("Always use file_search before answering questions about specific books")109- Use markdown formatting in instructions — LLMs parse it well110- Check OpenAI docs MCP for any changes to instruction handling or token limits