---
sourceDocument: Brazil Employee Service Management
sourceDocumentLink: https://www.servicenow.com/docs/r/employee-service-management

 Release :

    - brazil

ft:locale :

    - en-US

ft:publication_title :

    - Brazil Employee Service Management

ft:clusterId :

    - emplsm

bundleId :

    - emplsm

workflow :

    - Employee


---

# AI insights skill info

# AI insights skill reference {#ariaid-title1}

Release version: Brazil  
Updated January 27, 2025  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read  
Build a custom Now Assist skill that generates AI insights for the task details widget. Use this reference for the input, output, and error contract your skill must follow.

## AI insights skill overview {#empworks-ai-insights-skill-ref__overview}

Build your skill to match the input and output format in this topic. Administrators select your skill in the AI insights skill field
(`aix_ai_insights_skill`) on the AI insights tab of the `sn_ex_sp_task_configuration` table. {#empworks-ai-insights-skill-ref__empworks-ai-insights-skill-ref-para-1}

To set a skill for a task type, see [Configure a custom AI insights skill for a task type](https://www.servicenow.com/docs/zszJT1qIuRHSTCpsSPxkqw "Configure a task to use a custom Now Assist skill for AI insights in the Task details widget. Optionally add a custom script to pre-process input or post-process the skill response.").  
* When a task page loads, the task details widget runs your skill through `ActivityHubUtilSNC.generateAiInsights`. The widget then displays the results in the AI response card.
* When a skill is not selected, the AI insights section doesn't appear.
* Administrators can select the available skills such as the out-of-the-box Checklist Generation skill instead of building a custom one. For example, when you select the Approval summary checklist generation skill to show the approval checklist behavior, the checklist appears only while the approval (sysapproval_approver) is still actionable.  
  Note:  
  Approval checklist generation skill does not support other types of approvals.
{#empworks-ai-insights-skill-ref__ul_zv2_2zt_5jc}

## Example use cases {#empworks-ai-insights-skill-ref__example-use-cases}

Build a skill that helps you get the contextual insights and details relevant to the task type:

* A policy-check skill for Concur approval tasks.
* A skill that surfaces CLM field-level insights for contract tasks.
* A skill that shows the time-off balance details.
{#empworks-ai-insights-skill-ref__ul_mgx_j15_5jc}

## Skill input specification {#empworks-ai-insights-skill-ref__skill-input}

Your skill receives the following payload.
{#empworks-ai-insights-skill-ref__skill-input__entry__3}

| Field | Type | Description |
|-|-|-|
| `sys_id` | String | The sys_id of the record on the task page. |
| `table` | String | The table name of the record on the task page. |
[Table 1. Input fields]

## Custom skill requirements {#empworks-ai-insights-skill-ref__skill-development-requirements}

When you build custom skills, follow these guidelines

Task context
:   Design your skill for the specific task type and the data available on that task.

Performance
:   Make your skill execute efficiently so it does not slow the task page.

Error handling
:   Handle failures using the format in error handling for your skill.

## Skill output specification {#empworks-ai-insights-skill-ref__skill-output}

Return the following JSON structure from your skill, as a string or object:
{#empworks-ai-insights-skill-ref__skill-output__entry__4}

| Field | Type | Required | Description |
|-|-|-|-|
| `summary` | String | Yes | The insight text shown in the AI response card. Supports HTML formatting. |
| `references` | Array | No | List of reference links. Each entry includes `number`, `title`, and `url` fields. |
[Table 2. Output fields]

Structure each object in your `references` array as explained in the following table:
{#empworks-ai-insights-skill-ref__skill-output__entry__16}

| Field | Type | Required | Description |
|-|-|-|-|
| `number`(Optional) | String | Yes | Reference identifier displayed in the card. |
| `title` | String | Yes | Link text displayed to users. |
| `url` | String | Yes | Target URL for the reference link. |
[Table 3. Reference fields]

## Error handling {#empworks-ai-insights-skill-ref__error-handling}

If your skill fails, return the following error structure:
/b{#empworks-ai-insights-skill-ref__error-handling__entry__4}

| Field | Type | Required | Description |
|-|-|-|-|
| `status` | String | Yes | Must be set to `error`. |
| `message` | String | Yes | Error message displayed to users in the AI response card. |
[Table 4. Error response fields]

Note:  
If your skill returns an empty or unreadable response, the AI response card shows a generic error message instead.

## Configuration options {#empworks-ai-insights-skill-ref__configuration-options}

Administrators control when your skill runs using this property:
{#empworks-ai-insights-skill-ref__configuration-options__entry__3}

| Property | Value | Behavior |
|-|-|-|
| `sn_ex_ai_portal.task_insights_gen_mode` | `auto` | Insights are generated automatically when the task page loads. |
| `sn_ex_ai_portal.task_insights_gen_mode` | `on_demand` | Insights are generated when you select Summarize this task to generate insights. |
[Table 5. Generation mode settings]

**Related tasks**   

* [Configure a custom AI insights skill for a task type](https://www.servicenow.com/docs/zszJT1qIuRHSTCpsSPxkqw "Configure a task to use a custom Now Assist skill for AI insights in the Task details widget. Optionally add a custom script to pre-process input or post-process the skill response.")