/skill-agent-instructions

name: skill-agent-instructions
description: "Generate, review, and optimize natural language instructions for Business Central agents (Designer or SDK). Triggers on: agent instructions, InstructionsV1.txt, InstructionsV2.txt, MEMORIZE, qualification rules, agent behavior, instruction keywords, agent task instructions, iterate instructions, or improve agent accuracy. Single source of truth for the Responsibilities-Guidelines-Instructions framework and runtime keywords."
argument-hint: "Describe the agent's purpose and tasks, or paste existing instructions to review"

BC Agent Instructions Skill

Single source of truth for writing the natural-language instructions that guide Business Central agents. These instructions tell the agent runtime how to navigate the UI, read/set fields, invoke actions, and communicate with users.

For SDK architecture and how instructions are loaded see `skill-agent-toolkit`. For task-creation patterns (Public API, attachments, multi-turn) see `skill-agent-task-patterns`.

Storage modes

| Mode | Storage | Loaded by | | ------------ | ------------------------------------------ | -------------------------------------------------- | | **SDK** | `.resources/Instructions/InstructionsV1.txt` | `NavApp.GetResourceAsText()` → `SecretText` → `Agent.SetInstructions()` | | **Designer** | Paste into Agent Designer wizard text field | Runtime reads directly from configuration |

**References**:

• [Write effective instructions](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-instructions)
• [Instruction keywords](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-instruction-keywords)
• [Best practices](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-best-practices)

Key facts about the runtime

• Instructions are the PRIMARY lever for controlling agent behavior
• The runtime has specific tools: field setting, lookups, action invocation, page navigation, email composition
• Instructions must use specific keywords to activate these tools effectively
• Only English is fully supported — safeguards are optimized for English
• Shorter, well-structured instructions often outperform verbose ones
• The agent retains action history but NOT page state — use **MEMORIZE**

Framework: Responsibilities → Guidelines → Instructions

Every instruction file follows this three-part structure.

1. RESPONSIBILITY (one line)

A single sentence defining the agent's accountability. Anchors all behavior.

**RESPONSIBILITY**: {What the agent is accountable for — one sentence}

Rules:

• One sentence only — no paragraphs
• State the business outcome, not technical implementation
• Include the key domain nouns ("leads", "sales orders", "credit checks")

2. GUIDELINES (cross-task rules)

Rules that apply across all tasks.

**GUIDELINES**:
- ALWAYS {mandatory behavior}
- DO NOT {prohibited action}
- ALWAYS {safety/review gate}

Rules:

• **ALWAYS** (bold) for mandatory behaviors
• **DO NOT** (bold) for prohibited actions
• Gate ALL critical actions (posting, sending, releasing, deleting) with user intervention
• Include data access boundaries (read-only vs. read-write)
• Include reply/output keywords the agent should use for structured responses
• Keep to 3-7 guidelines — more causes confusion

3. INSTRUCTIONS (step-by-step per task)

Ordered steps for each task, using runtime keywords.

**INSTRUCTIONS**:

## Task: {Task Name}

1. {Action using keyword}
   a. {Sub-step with detail}
   b. {Sub-step with detail}
2. If {condition}: {action}
   a. **DO NOT** {prohibited action in this context}
3. {Next action}

Rules:

• One `## Task:` section per distinct workflow
• Numbered steps with lettered sub-steps
• Use official keywords (table below) to activate runtime tools
• Place **MEMORIZE** BEFORE the value is needed in later steps
• Include error handling at the end of each task
• Provide example formats for memorized data

Official runtime keywords

| Keyword | Runtime tool | Usage | | ----------------------------- | ---------------------- | --------------------------------------------------------------------- | | `Navigate to "{Page Name}"` | Page navigation | Opens a page. Name MUST match the agent's profile pages exactly. | | `Search for {value} in "{Field}"` | List filtering | Filters a list page by a field value. | | `Set field "{Field}" to {value}` | Field setter | Sets a field. Field name must match the page exactly. | | `Use lookup` | Lookup trigger | Opens a lookup on the current field. | | `Invoke action "{Action}"` | Action invocation | Triggers a page action. Name must match the action caption exactly. | | `Read "{Field}"` | Value retrieval | Reads a field's current value for decision-making. | | `**Memorize**` | State retention | Stores a key-value pair for reference in later steps. | | `**Reply**` | Message output | Agent responds to the task. All outgoing messages require review. | | `Write an email` | Email composition | Composes an email. Requires user review before sending. | | `Request user intervention` | Human-in-the-loop | Pauses the agent and asks the user for input/decision. | | `Request a review` | Review gate | Asks user to review work before the agent continues. | | `Ask for assistance` | Help request | Agent seeks help when stuck or enc