skill-kit-custom

使用 Skill Kit 自定义 Now Assist 技能

概述

本技能介绍如何使用 Skill Kit 框架创建自定义 Now Assist 技能：

• 设计包含明确输入、输出和处理逻辑的自定义技能
• 使用动态变量注入构建提示词模板
• 配置技能触发条件和调用上下文
• 实现通过串联 LLM 调用执行的多步骤技能
• 集成 Automated Test Framework（ATF）测试技能
• 在多个实例中部署和管理自定义技能的版本
• 构建专用 AI 功能（摘要、分类、生成、提取）

适用场景： 内置 Now Assist 技能无法满足需求，且需要自定义 AI 功能时，例如特定领域的摘要、自动分类、内容生成或数据提取。

先决条件

• 角色： now_assist_admin、admin、atf_test_designer（用于测试）
• 插件： sn_now_assist（Now Assist）、com.snc.generative_ai_controller（Generative AI Controller）、sn_gen_ai（Generative AI）、com.snc.atf（用于测试的 ATF）
• 访问权限： sn_now_assist_skill、sn_now_assist_skill_input、sn_now_assist_skill_output、sys_atf_test 表
• 知识： 提示词工程、LLM 的能力和限制、ATF 测试
• 相关技能： genai/now-assist-qa（用于问答配置），genai/ai-search-rag（用于 RAG 集成）

操作步骤

步骤 1：设计自定义技能

在实现前，先定义技能的用途和接口。

技能设计检查清单：

• 用途： 此技能提供什么具体的 AI 功能？
• 触发方式： 如何调用技能（自动、用户发起、API）？
• 输入： 技能需要哪些数据（记录字段、用户输入、上下文）？
• 处理： 执行哪些 LLM 操作（摘要、分类、生成、提取）？
• 输出： 技能会生成哪些结果（文本、结构化数据、操作）？
• 上下文： 技能在哪里运行（Agent 工作区、门户、移动端、API）？

常见的自定义技能模式：

模式	说明	示例用例
摘要	将长文本浓缩为要点	事件摘要、会议纪要
分类	将输入归入预定义类别	工单路由、情感分析
生成	根据指令创建新内容	电子邮件草稿、知识文章
提取	从非结构化文本中提取结构化数据	实体提取、字段填充
转换	在不同格式或语言之间转换	将技术语言转换为通俗语言
建议	根据上下文提出操作建议	解决方案建议、下一步最佳操作

步骤 2：创建自定义技能记录

MCP 方式：

Use SN-Create-Record on sn_now_assist_skill:
  - name: "Incident Root Cause Analyzer"
  - description: "Analyzes incident description, work notes, and related records to suggest probable root causes"
  - skill_type: "custom"
  - context: "agent_workspace"
  - active: true
  - status: "draft"
  - category: "itsm"
  - invocation_type: "user_initiated"
  - target_table: "incident"
  - version: "1.0.0"

REST 方式：

POST /api/now/table/sn_now_assist_skill
Body: {
  "name": "Incident Root Cause Analyzer",
  "description": "Analyzes incident details to suggest probable root causes",
  "skill_type": "custom",
  "context": "agent_workspace",
  "active": true,
  "status": "draft",
  "category": "itsm",
  "invocation_type": "user_initiated",
  "target_table": "incident"
}

调用类型：

类型	值	说明
用户发起	user_initiated	用户点击按钮或菜单项
自动	automatic	由记录事件触发
API	api	通过 REST API 或脚本调用
上下文	contextual	根据工作区上下文触发

步骤 3：定义技能输入

输入定义技能接收哪些数据来进行处理。

MCP 方式：

Use SN-Create-Record on sn_now_assist_skill_input:
  - skill: "<skill_sys_id>"
  - name: "incident_description"
  - label: "Incident Description"
  - type: "string"
  - source: "record_field"
  - source_field: "description"
  - source_table: "incident"
  - mandatory: true
  - order: 100

Use SN-Create-Record on sn_now_assist_skill_input:
  - skill: "<skill_sys_id>"
  - name: "work_notes"
  - label: "Work Notes"
  - type: "string"
  - source: "record_field"
  - source_field: "work_notes"
  - source_table: "incident"
  - mandatory: false
  - order: 200

Use SN-Create-Record on sn_now_assist_skill_input:
  - skill: "<skill_sys_id>"
  - name: "category"
  - label: "Category"
  - type: "string"
  - source: "record_field"
  - source_field: "category"
  - source_table: "incident"
  - mandatory: true
  - order: 300

Use SN-Create-Record on sn_now_assist_skill_input:
  - skill: "<skill_sys_id>"
  - name: "affected_ci"
  - label: "Affected CI"
  - type: "reference"
  - source: "record_field"
  - source_field: "cmdb_ci"
  - source_table: "incident"
  - mandatory: false
  - order: 400

输入源类型：

来源	值	说明
记录字段	record_field	目标记录中的值
用户输入	user_input	调用时向用户提示输入
上下文	context	从工作区上下文中获取
静态	static	硬编码值
计算	computed	通过脚本计算

REST 方式：

POST /api/now/table/sn_now_assist_skill_input
Body: {
  "skill": "<skill_sys_id>",
  "name": "incident_description",
  "label": "Incident Description",
  "type": "string",
  "source": "record_field",
  "source_field": "description",
  "source_table": "incident",
  "mandatory": true,
  "order": 100
}

第 4 步：定义技能输出

输出定义技能处理后返回的内容。

MCP 方式：

Use SN-Create-Record on sn_now_assist_skill_output:
  - skill: "<skill_sys_id>"
  - name: "root_cause_summary"
  - label: "Root Cause Summary"
  - type: "string"
  - display_type: "rich_text"
  - order: 100

Use SN-Create-Record on sn_now_assist_skill_output:
  - skill: "<skill_sys_id>"
  - name: "confidence_score"
  - label: "Confidence Score"
  - type: "decimal"
  - display_type: "badge"
  - order: 200

Use SN-Create-Record on sn_now_assist_skill_output:
  - skill: "<skill_sys_id>"
  - name: "suggested_category"
  - label: "Suggested Category"
  - type: "string"
  - display_type: "text"
  - order: 300

Use SN-Create-Record on sn_now_assist_skill_output:
  - skill: "<skill_sys_id>"
  - name: "related_kb_articles"
  - label: "Related Knowledge Articles"
  - type: "string"
  - display_type: "link_list"
  - order: 400

输出显示类型：

显示类型	值	描述
纯文本	text	简单文本显示
富文本	rich_text	格式化的 HTML/markdown
徽章	badge	颜色编码标签
链接列表	link_list	可点击的参考链接
JSON	json	结构化数据展示
操作按钮	action	可点击的操作触发器

第 5 步：配置技能提示词

提示词是技能的核心，它们会指示大模型要执行的操作。

MCP 方式：

Use SN-Create-Record on sn_now_assist_skill_prompt:
  - skill: "<skill_sys_id>"
  - name: "root_cause_analysis_prompt"
  - prompt_type: "system"
  - order: 100
  - template: |
      You are an expert IT incident analyst. Your task is to analyze incident
      information and determine the most probable root cause.

      Analyze the following incident details:

      Category: {category}
      Description: {incident_description}
      Work Notes: {work_notes}
      Affected CI: {affected_ci}

      Provide your analysis in the following format:

      ## Root Cause Summary
      [2-3 sentence summary of the most likely root cause]

      ## Contributing Factors
      - [Factor 1]
      - [Factor 2]
      - [Factor 3]

      ## Confidence Level
      [High/Medium/Low] - [Brief justification]

      ## Recommended Actions
      1. [Action 1]
      2. [Action 2]
      3. [Action 3]

      ## Suggested Category
      [If the incident appears miscategorized, suggest the correct category]

      Guidelines:
      - Base your analysis only on the provided information
      - If insufficient data, state what additional information would help
      - Consider common patterns for the given category
      - Prioritize actionable recommendations
  - active: true

多步提示词（链式大模型调用）：

Use SN-Create-Record on sn_now_assist_skill_prompt:
  - skill: "<skill_sys_id>"
  - name: "extract_entities_prompt"
  - prompt_type: "preprocessing"
  - order: 50
  - template: |
      Extract the following entities from the incident description:

      Description: {incident_description}

      Return a JSON object with:
      {
        "affected_systems": ["list of systems mentioned"],
        "error_codes": ["any error codes found"],
        "timestamps": ["any times/dates mentioned"],
        "user_actions": ["what the user was doing when the issue occurred"]
      }
  - active: true

提示词类型：

类型	值	顺序	描述
预处理	preprocessing	1-49	在主要分析前提取/转换输入
系统	system	50-99	为大模型提供主要系统指令
用户	user	100+	注入动态用户上下文
后处理	postprocessing	200+	格式化/验证大模型输出

第 6 步：配置技能的大模型设置

MCP 方式：

Use SN-Create-Record on sn_gen_ai_config:
  - name: "Root Cause Analyzer LLM Config"
  - description: "LLM parameters optimized for root cause analysis"
  - active: true
  - llm_provider: "now_llm"
  - model: "default"
  - temperature: 0.2
  - max_tokens: 800
  - top_p: 0.9
  - frequency_penalty: 0.2
  - presence_penalty: 0.1

链接到技能：

Use SN-Create-Record on sn_now_assist_skill_config:
  - skill: "<skill_sys_id>"
  - name: "llm_config"
  - config_type: "gen_ai_config"
  - value: "<gen_ai_config_sys_id>"
  - active: true

不同技能类型的温度指南：

技能类型	温度	原因
摘要	0.1-0.3	事实准确性至关重要
分类	0.0-0.2	确保分类具有确定性
根因分析	0.2-0.4	平衡推理能力与准确性
内容生成	0.5-0.7	生成有创意且连贯的内容
邮件起草	0.4-0.6	兼顾专业语气与变化
代码生成	0.1-0.3	需要确保语法正确

第 7 步：为技能创建 ATF 测试

自动化测试可确保技能在更新后仍保持高质量。

创建 ATF 测试：

MCP 方式：

Use SN-Create-Record on sys_atf_test:
  - name: "Test - Root Cause Analyzer Skill"
  - description: "Validates the root cause analyzer skill produces expected output format and quality"
  - active: true
  - test_type: "automated"
  - category: "now_assist_skill"

创建测试步骤：

第 1 步 —— 设置测试事件：

Use SN-Create-Record on sys_atf_step:
  - test: "<atf_test_sys_id>"
  - order: 100
  - step_type: "create_record"
  - table: "incident"
  - description: "Create test incident with known root cause pattern"
  - step_config: '{
      "table": "incident",
      "fields": {
        "short_description": "Email server not responding since 2AM",
        "description": "Users reporting inability to send or receive emails. Exchange server shows high CPU utilization. Error code 0x80040115 in Outlook clients. Issue started after scheduled maintenance window at 2AM.",
        "category": "email",
        "priority": 2,
        "cmdb_ci": "<email_server_ci_sys_id>"
      }
    }'

第 2 步 —— 调用技能：

Use SN-Create-Record on sys_atf_step:
  - test: "<atf_test_sys_id>"
  - order: 200
  - step_type: "invoke_now_assist_skill"
  - description: "Execute root cause analyzer skill on test incident"
  - step_config: '{
      "skill": "<skill_sys_id>",
      "record_table": "incident",
      "record_sys_id": "${test_incident_sys_id}"
    }'

第 3 步 —— 验证输出格式：

Use SN-Create-Record on sys_atf_step:
  - test: "<atf_test_sys_id>"
  - order: 300
  - step_type: "validate_output"
  - description: "Verify skill output contains required sections"
  - step_config: '{
      "assertions": [
        {"field": "root_cause_summary", "operator": "is_not_empty"},
        {"field": "root_cause_summary", "operator": "contains", "value": "Root Cause"},
        {"field": "confidence_score", "operator": "greater_than", "value": 0},
        {"field": "confidence_score", "operator": "less_than_or_equal", "value": 1}
      ]
    }'

第 4 步 —— 清理测试数据：

Use SN-Create-Record on sys_atf_step:
  - test: "<atf_test_sys_id>"
  - order: 400
  - step_type: "delete_record"
  - description: "Remove test incident"
  - step_config: '{
      "table": "incident",
      "sys_id": "${test_incident_sys_id}"
    }'

REST 方式：

POST /api/now/table/sys_atf_test
Body: {
  "name": "Test - Root Cause Analyzer Skill",
  "description": "Validates root cause analyzer skill output",
  "active": true
}

第 8 步：创建技能测试用例

为技能创建专用测试用例，以验证质量。

MCP 方式：

Use SN-Create-Record on sn_now_assist_skill_test:
  - skill: "<skill_sys_id>"
  - name: "Network Incident Root Cause"
  - description: "Tests root cause analysis for network-related incidents"
  - test_input: '{
      "incident_description": "Multiple users in Building A unable to access network resources. Switch in MDF room showing amber lights on ports 1-24. Issue started after power fluctuation at 3PM.",
      "category": "network",
      "work_notes": "Checked switch logs - multiple port flaps detected. UPS battery backup depleted during power event.",
      "affected_ci": "SW-BLDGA-MDF-01"
    }'
  - expected_output_contains: "power"
  - expected_confidence_min: 0.7
  - active: true

Use SN-Create-Record on sn_now_assist_skill_test:
  - skill: "<skill_sys_id>"
  - name: "Software Crash Root Cause"
  - description: "Tests root cause analysis for application crash incidents"
  - test_input: '{
      "incident_description": "CRM application crashing with OutOfMemoryError after latest patch deployment. Heap dump shows memory leak in report generation module.",
      "category": "software",
      "work_notes": "Application team confirmed new patch v2.4.1 deployed yesterday. No issues on staging environment.",
      "affected_ci": "APP-CRM-PROD-01"
    }'
  - expected_output_contains: "memory"
  - expected_confidence_min: 0.8
  - active: true

第 9 步：部署并激活技能

MCP 方式：

Use SN-Update-Record on sn_now_assist_skill:
  - sys_id: "<skill_sys_id>"
  - status: "published"
  - active: true
  - version: "1.0.0"

验证所有组件均已就绪：

Use SN-Query-Table on sn_now_assist_skill_input:
  - query: skill=<skill_sys_id>^active=true
  - fields: name,type,source,mandatory
  - limit: 20

Use SN-Query-Table on sn_now_assist_skill_output:
  - query: skill=<skill_sys_id>
  - fields: name,type,display_type
  - limit: 20

Use SN-Query-Table on sn_now_assist_skill_prompt:
  - query: skill=<skill_sys_id>^active=true
  - fields: name,prompt_type,order
  - limit: 10

第 10 步：监控技能性能

查询技能执行日志：

Use SN-Query-Table on sn_now_assist_skill_execution:
  - query: skill=<skill_sys_id>^sys_created_on>javascript:gs.daysAgo(7)
  - fields: sys_id,status,execution_time,input_tokens,output_tokens,error_message
  - limit: 50
  - orderBy: sys_created_on
  - orderDirection: desc

跟踪反馈：

Use SN-Query-Table on sn_now_assist_feedback:
  - query: skill=<skill_sys_id>^rating<3
  - fields: query,response,rating,feedback_text
  - limit: 20

监控令牌用量：

Use SN-Query-Table on sn_now_assist_skill_execution:
  - query: skill=<skill_sys_id>^sys_created_on>javascript:gs.daysAgo(30)
  - fields: input_tokens,output_tokens,execution_time
  - limit: 100

工具用法

工具	用途	适用场景
SN-Query-Table	查找现有技能、测试结果和反馈	发现与监控
SN-Create-Record	创建技能、输入、输出、提示词和测试	构建技能组件
SN-Update-Record	修改提示词、激活技能、更新版本	迭代与部署
SN-Get-Table-Schema	发现技能表字段	了解可用配置

最佳实践

1. 谨慎设计输入 —— 仅包含大模型任务确实需要的字段
2. 使用结构化提示词模板，明确划分各个部分并指定输出格式
3. 对分析型技能（分类、提取）将温度设低，对生成型技能则设为适中
4. 编写全面的 ATF 测试，覆盖边缘情况、空输入和预期的失败模式
5. 使用语义化版本号（major.minor.patch）为技能设置版本
6. 使用预处理提示词，在主要分析提示词前提取实体
7. 合理设置 max_tokens —— 过低会截断输出，过高则会浪费令牌
8. 加入后处理，在向用户显示大模型输出前进行验证和格式化
9. 监控令牌用量，以管理成本并发现优化机会
10. 根据反馈迭代提示词 —— 微小的提示词改动也可能显著影响质量

故障排除

问题	原因	解决方法
技能未显示在 Now Assist 中	状态为草稿或技能未激活	发布并激活该技能
未填充输入项	源字段映射不正确	确认 source_field 和 source_table 与目标记录匹配
输出格式不一致	提示词模板缺少明确的格式说明	在提示词中添加包含示例的结构化输出格式
ATF 测试间歇性失败	温度较高时，大模型的输出具有非确定性	降低温度或使用模糊断言
技能执行超时	提示词过长或链式大模型调用过多	减小输入规模，简化提示词链
返回空输出	未关联或未激活 LLM 配置	确认 gen_ai_config 已激活并关联到技能
置信度始终较低	输入中的上下文不足	添加更多相关输入字段或知识上下文
提示词注入漏洞	用户输入未经净化	在预处理步骤中添加输入验证

示例

示例 1：事件摘要技能

创建自定义技能以汇总事件历史记录：

• 输入项： short_description、description、work_notes、comments、state、priority
• 提示词： 用 3-5 个要点概述事件时间线、已采取的关键措施和当前状态
• 输出项： summary (rich_text)、key_dates (text)、next_action (text)
• LLM 配置： 温度 0.2，最多 400 个 token
• 测试： 包含 10 条以上 work_notes 的网络事件，以及备注极少的简单事件

示例 2：工单分类技能

创建用于自动工单分类的自定义技能：

• 输入项： short_description、description、caller_id.department
• 提示词： 根据预定义分类体系对工单进行分类，返回 JSON
• 输出项： suggested_category (text)、suggested_subcategory (text)、confidence (badge)
• LLM 配置： 温度 0.0，最多 200 个 token，以实现确定性分类
• 测试： 10 个以上测试用例，涵盖每个类别，并包含已知的正确分类

示例 3：解决说明生成器

创建自定义技能以生成解决方案文档：

• 输入项： short_description、description、work_notes、close_code、resolved_by
• 提示词： 生成专业的解决说明，记录问题、调查步骤、根本原因和已应用的修复方法
• 输出项： resolution_notes (rich_text)、knowledge_candidate (text)、reusable_solution (text)
• LLM 配置： 温度 0.4，最多 600 个 token，以生成结构化且易读的输出
• 测试： 针对硬件故障、软件 Bug 和用户错误场景，验证预期的解决方案模式

相关技能

• genai/now-assist-qa - 与自定义技能互补的问答技能配置
• genai/ai-search-rag - 为自定义技能提供知识依据的 RAG 配置
• genai/flow-generation - 可将自定义技能作为操作触发的工作流
• genai/playbook-generation - 包含自定义技能调用的操作手册
• development/automated-testing - 用于全面测试技能的 ATF 框架