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
• Instruction keywords
• 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 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

1. Gather inputs: agent purpose (1 sentence), pages in scope, fields to read/write, actions to invoke, decision criteria, output format, safety gates
2. Draft RESPONSIBILITY: one sentence with domain + outcome
3. Draft GUIDELINES: 3-7 rules, at least one ALWAYS, one DO NOT, one safety gate
4. Draft INSTRUCTIONS per task: navigate → read+MEMORIZE → branch → execute → Reply
5. Validate with the checklist below
6. Test and iterate: deploy → observe timeline → refine. Simpler instructions often perform better.

Validation checklist

• Page names match agent profile and page customizations exactly
• Field names match the fields visible on the agent's pages exactly
• Action names match the action captions visible on the agent's pages
• MEMORIZE placed BEFORE the memorized value is needed in later steps
• MEMORIZE includes example format (e.g., "Key: value | Key: value")
• All critical actions (posting, sending, releasing, deleting) gated by user intervention or review
• Written in English, agent safeguards are optimized for English
• Environment-agnostic, no hardcoded company names, URLs, user IDs
• Concise, no redundant prose; each line serves a purpose
• Error handling section covers: not found, unavailable pages, failed actions
• Reply formats use consistent keywords for structured parsing
• No references to "Tell Me" (agents cannot use it)
• Guidelines count is 3-7 (not too few, not too many)
• Each task has numbered steps with lettered sub-steps

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

Load an example only when you need a concrete template:

• When writing a minimal single-task agent, see Simple instructions (credit check).
• When building a multi-task agent with handoff and error handling, see Advanced instructions (lead qualifier).
• If you need to look up a runtime keyword, see Keywords reference.