| 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:
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 encounters an error. |
Critical keyword rules:
- Page, field, and action names MUST match exactly what the agent sees in its profile
- MEMORIZE must include an example format:
**Memorize**: "Customer: ACME Corp | Credit: 50,000"
- Reply keywords should include structured output patterns for programmatic parsing
- The agent does NOT have access to "Tell Me" — all navigation must be via explicit page names
Step-by-step creation workflow
- Gather inputs: agent purpose (1 sentence), pages in scope, fields to read/write, actions to invoke, decision criteria, output format, safety gates
- Draft RESPONSIBILITY: one sentence with domain + outcome
- Draft GUIDELINES: 3-7 rules — at least one ALWAYS, one DO NOT, one safety gate
- Draft INSTRUCTIONS per task: navigate → read+MEMORIZE → branch → execute → Reply
- Validate with the checklist below
- Test and iterate: deploy → observe timeline → refine. Simpler instructions often perform better.
Validation checklist
Anti-patterns
| Anti-pattern | Problem | Fix |
|---|
| No MEMORIZE before cross-page use | Agent loses field values when navigating away | Add MEMORIZE immediately after reading the value |
| Vague field names ("the amount") | Agent cannot resolve which field to set | Use exact field name: Set field "Estimated Budget" |
| Missing error handling | Agent halts or produces confusing output | Add error Reply for each failure scenario |
| Too many guidelines (>7) | Agent behavior becomes inconsistent | Consolidate into fewer, broader rules |
| Referencing pages not in profile | Agent cannot navigate there | Verify all pages are in the agent's profile |
| No user intervention on critical ops | Agent posts/sends/releases without human check | Add Request user intervention or Request a review |
| Contradictory guidelines | Unpredictable behavior on each run | Remove contradictions, prioritize by specificity |
| Hard-coded environment values | Instructions break across environments | Use generic references, let setup tables hold specifics |
| Referencing specific tools by name | Tool renames cause regressions | Describe WHAT to do, not WHICH tool to use |
Advanced concepts
Page-specific dynamic instructions
For SDK agents, IAgentTaskExecution.GetAgentTaskPageContext injects dynamic context per page using Liquid-style conditionals:
Consider the following fields:
{% if page.id == 42 %}
Field "The Answer" — the meaning of the universe
{% else %}
Field "Business Data" — standard business field
{% endif %}
Multi-task instructions
When an agent handles multiple tasks, create separate ## Task: sections. The agent selects the task based on input message content. Use distinct keywords in the Reply for programmatic routing:
## Task: Qualify Lead
...Reply: "qualification successful | ..."
## Task: Re-evaluate Lead
...Reply: "re-evaluation complete | ..."
Agent-to-agent handoff
When one agent creates tasks for another:
- Verify the target agent is configured (check setup fields)
- Use page actions that trigger task creation (the action handles the API call)
- MEMORIZE the handoff result for the final reply
- Include fallback instructions if the handoff action is unavailable
Examples
