Skill Agent Instructions

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](./examples/agent-simple-instructions.txt) (credit check).
• When building a multi-task agent with handoff and error handling, see [Advanced instructions](./examples/agent-advanced-instructions.txt) (lead qualifier).
• If you need to look up a runtime keyword, see [Keywords reference](./references/agent-keywords-reference.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Louage
• Source: Louage/frw-agentic-coding
• License: MIT

Install and usage instructions live in the source repository linked above.