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 テスト
• 関連スキル： Q&A の設定については genai/now-assist-qa、RAG との連携については genai/ai-search-rag

手順

ステップ 1：カスタムスキルを設計する

実装の前に、スキルの目的とインターフェイスを定義します。

スキル設計チェックリスト：

• 目的： このスキルが提供する具体的な AI 機能は何ですか？
• トリガー： スキルはどのように呼び出されますか（自動、ユーザー起動、API）？
• 入力： スキルにはどのようなデータが必要ですか（レコードのフィールド、ユーザー入力、コンテキスト）？
• 処理： どのような LLM 操作を実行しますか（要約、分類、生成、抽出）？
• 出力： スキルはどのような結果を生成しますか（テキスト、構造化データ、アクション）？
• コンテキスト： スキルはどこで実行されますか（エージェントワークスペース、ポータル、モバイル、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：スキルのプロンプトを設定する

プロンプトはスキルの中核であり、LLM に何をすべきかを指示します。

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

複数ステップのプロンプト（連鎖的な LLM 呼び出し）：

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	LLM への主なシステム指示
ユーザー	user	100+	動的なユーザーコンテキストの挿入
後処理	postprocessing	200+	LLM の出力を整形／検証します

ステップ 6：スキルの LLM 設定を構成する

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

スキルの種類ごとの Temperature の指針：

スキルの種類	Temperature	理由
要約	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. 入力を慎重に設計する -- LLM のタスクで本当に必要なフィールドだけを含めます
2. 明確なセクションと出力形式の指定を含む、構造化されたプロンプトテンプレートを使用する
3. 分析スキル（分類、抽出）では Temperature を低くし、生成スキルでは中程度にする
4. エッジケース、空の入力、想定される失敗パターンを網羅した包括的な ATF テストを作成する
5. セマンティックバージョニング（major.minor.patch）を使用してスキルをバージョン管理する
6. 前処理プロンプトを使って、主な分析プロンプトの前にエンティティを抽出する
7. max_tokens を適切に設定する -- 少なすぎると出力が途中で切れ、多すぎるとトークンを無駄に消費します
8. ユーザーに表示する前に LLM の出力を検証・整形するため、後処理を含める
9. トークン使用量を監視してコストを管理し、最適化の機会を特定する
10. フィードバックに基づいてプロンプトを反復的に改善する -- わずかな変更でも品質に大きく影響する場合があります

トラブルシューティング

問題	原因	解決方法
Now Assist にスキルが表示されない	ステータスが下書き、またはスキルが無効になっている	スキルを公開して有効化します
入力が設定されない	ソースフィールドのマッピングが正しくない	source_field と source_table が対象レコードと一致していることを確認します
出力形式に一貫性がない	プロンプトテンプレートに明示的な形式の指示がない	プロンプトに例を含む構造化出力形式を追加します
ATF テストが断続的に失敗する	温度が高い場合の LLM の非決定性	温度を下げるか、あいまい一致のアサーションを使用します
スキルの実行がタイムアウトする	プロンプトが大きすぎる、または連鎖する LLM 呼び出しが多すぎる	入力サイズを縮小し、プロンプトの連鎖を簡素化します
空の出力が返される	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 トークン
• テスト： work_notes が 10 件以上あるネットワークインシデント、および記録が最小限の単純なインシデント

例 2：チケット分類スキル

チケットを自動分類するカスタムスキルを作成します：

• 入力： short_description、description、caller_id.department
• プロンプト： 定義済みの分類体系からカテゴリ／サブカテゴリに分類し、JSON を返します
• 出力： suggested_category（text）、suggested_subcategory（text）、confidence（badge）
• LLM 設定： 決定論的な分類のため、温度 0.0、最大 200 トークン
• テスト： 正しい分類が既知の各カテゴリを網羅する 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 トークン
• テスト： 想定される解決パターンに基づく、ハードウェア障害、ソフトウェアのバグ、ユーザーエラーのシナリオ

関連スキル

• genai/now-assist-qa - カスタムスキルを補完する Q&A スキル設定
• genai/ai-search-rag - ナレッジに基づくカスタムスキルのための RAG 設定
• genai/flow-generation - カスタムスキルをアクションとして実行できるフロー
• genai/playbook-generation - カスタムスキルの呼び出しを組み込むプレイブック
• development/automated-testing - スキルを包括的にテストするための ATF フレームワーク