/skill-copilot

name: skill-copilot
description: "AL Copilot capability development for Business Central. Use when implementing PromptDialog pages, AI generation features, or integrating with the Copilot toolkit."

Skill: AL Copilot Development (Full Lifecycle)

Purpose

Build AI-powered Copilot experiences in Business Central end-to-end: capability registration, PromptDialog page design, Azure OpenAI generation codeunit, and testing with AI Test Toolkit.

When to Load

This skill should be loaded when:

• A new Copilot/AI feature is being designed or implemented
• A PromptDialog page needs to be created or modified
• Azure OpenAI integration is required (chat completions, JSON mode)
• AI Test Toolkit tests need to be created for a Copilot feature
• Prompt engineering guidance is needed (system/user prompt design)
• A capability needs to be registered in BC's Copilot admin page

Phase 1: Capability Registration

Objects Required

1. **Enum Extension** — extend `"Copilot Capability"` to register your feature 2. **Install Codeunit** — register the capability on app install 3. **Isolated Storage Wrapper** — manage Azure OpenAI secrets securely

Pattern: Enum Extension

namespace Contoso.CopilotFeatures;

using System.AI;

enumextension 50100 "Contoso Copilot Capabilities" extends "Copilot Capability"
{
    value(50100; "Sales Forecasting")
    {
        Caption = 'Sales Forecasting with Copilot';
    }
}

Pattern: Install Codeunit

namespace Contoso.CopilotFeatures;

using System.AI;

codeunit 50100 "Contoso Copilot Setup"
{
    Subtype = Install;
    InherentEntitlements = X;
    InherentPermissions = X;
    Access = Internal;

    trigger OnInstallAppPerDatabase()
    begin
        RegisterCapability();
    end;

    local procedure RegisterCapability()
    var
        CopilotCapability: Codeunit "Copilot Capability";
        LearnMoreUrlTxt: Label 'https://learn.microsoft.com/dynamics365/business-central/', Locked = true;
    begin
        if not CopilotCapability.IsCapabilityRegistered(
            Enum::"Copilot Capability"::"Sales Forecasting") then
            CopilotCapability.RegisterCapability(
                Enum::"Copilot Capability"::"Sales Forecasting",
                Enum::"Copilot Availability"::Preview,
                LearnMoreUrlTxt);
    end;
}

**Availability options:** `Preview` (opt-in), `GA` (general availability).

After publishing, verify the capability appears in BC: search **"Copilot & AI Capabilities"** page.

Pattern: Isolated Storage Wrapper (Secrets)

codeunit 50101 "Contoso Isolated Storage"
{
    Access = Internal;

    procedure GetSecretKey(): SecretText
    var
        Secret: Text;
    begin
        if IsolatedStorage.Get('AzureOpenAIKey', DataScope::Module, Secret) then
            exit(Secret);
        Error('Azure OpenAI key not configured.');
    end;

    procedure SetSecretKey(NewKey: SecretText)
    begin
        IsolatedStorage.Set('AzureOpenAIKey', NewKey, DataScope::Module);
    end;

    procedure GetEndpoint(): Text
    var
        Endpoint: Text;
    begin
        if IsolatedStorage.Get('AzureOpenAIEndpoint', DataScope::Module, Endpoint) then
            exit(Endpoint);
        Error('Azure OpenAI endpoint not configured.');
    end;

    procedure SetEndpoint(NewEndpoint: Text)
    begin
        IsolatedStorage.Set('AzureOpenAIEndpoint', NewEndpoint, DataScope::Module);
    end;

    procedure GetDeployment(): Text
    var
        Deployment: Text;
    begin
        if IsolatedStorage.Get('AzureOpenAIDeployment', DataScope::Module, Deployment) then
            exit(Deployment);
        exit('gpt-4o');   // default model
    end;

    procedure SetDeployment(NewDeployment: Text)
    begin
        IsolatedStorage.Set('AzureOpenAIDeployment', NewDeployment, DataScope::Module);
    end;
}

**Production vs Development:**

• **Development**: configure own Azure OpenAI credentials via `SetSecretKey`/`SetEndpoint`/`SetDeployment`
• **Production**: use `SetManagedResourceAuthorization` (Microsoft-managed, no secrets needed)

Phase 2: PromptDialog Page

Page Areas

| Area | Purpose | Contains | |---|---|---| | `PromptOptions` | User settings/filters | Option/Enum fields only | | `Prompt` | User text input | Free-text field with `InstructionalText` | | `Content` | AI output display | Text field or `part` subpage with results | | `PromptGuide` (actions) | Example prompts | Actions that pre-fill the Prompt field | | `SystemActions` (actions) | Generate / OK / Cancel | `systemaction(Generate)`, `systemaction(OK)`, etc. |

PromptMode Options

| Mode | Behavior | Use when | |---|---|---| | `Prompt` | Shows input first, user clicks Generate | User needs to provide context | | `Generate` | Auto-runs generation when page opens | Context is pre-filled from calling page | | `Content` | Shows content only, no generation | Displaying previously generated results |

Pattern: Complete PromptDialog Page

namespace Contoso.CopilotFeatures;

using System.AI;

page 50110 "Contoso Sales Forecast Copilot"
{
    PageType = PromptDialog;
    Extensible = false;
    IsPreview = true;
    Caption = 'Sales Forecast with Copilot';
    PromptMode = Prompt;

    layout
    {
        area(PromptOptions)
        {
            field(ForecastPeriod; SelectedPeriod)
            {
                ApplicationArea = All;
                Caption = 'Forecast Period';
                ToolTip = 'Select the forecast time horizon.';
            }
        }

        area(Prompt)
        {
            field(UserInput; UserPromptText)
            {
                ShowCaption = false;
                MultiLine = true;
                ApplicationArea = All;
                InstructionalText = 'Describe what you want to forecast (e.g., "top 10 items for next quarter")';

                trigger OnValidate()
                begin
                    CurrPage.Update();
                end;
            }
        }

        area(Co