happy-technologies-llc/skill-kit-custom

Custom Now Assist Skills with Skill Kit

Overview

This skill covers creating custom Now Assist skills using the Skill Kit framework:

• Designing custom skills with defined inputs, outputs, and processing logic
• Building prompt templates with dynamic variable injection
• Configuring skill triggers and invocation contexts
• Implementing multi-step skills with chained LLM calls
• Testing skills with Automated Test Framework (ATF) integration
• Deploying and versioning custom skills across instances
• Building specialized AI capabilities (summarization, classification, generation, extraction)

When to use: When the built-in Now Assist skills do not meet your requirements and you need custom AI capabilities such as domain-specific summarization, automated classification, content generation, or data extraction.

Prerequisites

• Roles: now_assist_admin, admin, atf_test_designer (for testing)
• Plugins: sn_now_assist (Now Assist), com.snc.generative_ai_controller (Generative AI Controller), sn_gen_ai (Generative AI), com.snc.atf (ATF for testing)
• Access: sn_now_assist_skill, sn_now_assist_skill_input, sn_now_assist_skill_output, sys_atf_test tables
• Knowledge: Prompt engineering, LLM capabilities and limitations, ATF testing
• Related Skills: genai/now-assist-qa for Q&A configuration, genai/ai-search-rag for RAG integration

Procedure

Step 1: Design the Custom Skill

Define the skill's purpose and interface before implementation.

Skill design checklist:

• Purpose: What specific AI capability does this skill provide?
• Trigger: How is the skill invoked (automatic, user-initiated, API)?
• Inputs: What data does the skill need (record fields, user input, context)?
• Processing: What LLM operations are performed (summarize, classify, generate, extract)?
• Outputs: What results does the skill produce (text, structured data, actions)?
• Context: Where does the skill run (agent workspace, portal, mobile, API)?

Common custom skill patterns:

| Pattern | Description | Example Use Case | |---------|-------------|-----------------| | Summarization | Condense long text into key points | Incident summarization, meeting notes | | Classification | Categorize input into predefined labels | Ticket routing, sentiment analysis | | Generation | Create new content from instructions | Email drafts, knowledge articles | | Extraction | Pull structured data from unstructured text | Entity extraction, field population | | Translation | Convert between formats or languages | Technical to plain language | | Recommendation | Suggest actions based on context | Resolution suggestions, next best action |

Step 2: Create the Custom Skill Record

MCP Approach:

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 Approach:

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"
}

Invocation types:

| Type | Value | Description | |------|-------|-------------| | User Initiated | user_initiated | User clicks a button or menu item | | Automatic | automatic | Triggered on record events | | API | api | Called via REST API or script | | Contextual | contextual | Triggered based on workspace context |

Step 3: Define Skill Inputs

Inputs define what data the skill receives for processing.

MCP Approach:

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

Input source types:

| Source | Value | Description | |--------|-------|-------------| | Record Field | record_field | Value from the target record | | User Input | user_input | Prompted from user at invocation | | Context | context | Derived from workspace context | | Static | static | Hardcoded value | | Computed | computed | Calculated via script |

REST Approach:

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
}

Step 4: Define Skill Outputs

Outputs define what the skill returns after processing.

MCP Approach:

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

Output display types:

| Display Type | Value | Description | |-------------|-------|-------------| | Plain Text | text | Simple text display | | Rich Text | rich_text | Formatted HTML/markdown | | Badge | badge | Color-coded label | | Link List | link_list | Clickable reference links | | JSON | json | Structured data display | | Action Button | action | Clickable action trigger |

Step 5: Configure Skill Prompts

Prompts are the core of the skill -- they instruct the LLM on what to do.

MCP Approach:

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

Multi-step prompt (chained LLM call):

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

Prompt types:

| Type | Value | Order | Description | |------|-------|-------|-------------| | Preprocessing | preprocessing | 1-49 | Extract/transform inputs before main analysis | | System | system | 50-99 | Main system instructions for the LLM | | User | user | 100+ | Dynamic user context injection | | Postprocessing | postprocessing | 200+ | Format/validate LLM output |

Step 6: Configure LLM Settings for the Skill

MCP Approach:

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

Link to skill:

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 guidelines by skill type:

| Skill Type | Temperature | Rationale | |------------|-------------|-----------| | Summarization | 0.1-0.3 | Factual accuracy is critical | | Classification | 0.0-0.2 | Deterministic categorization | | Root Cause Analysis | 0.2-0.4 | Balanced reasoning with accuracy | | Content Generation | 0.5-0.7 | Creative but coherent output | | Email Drafting | 0.4-0.6 | Professional tone with variation | | Code Generation | 0.1-0.3 | Syntactic correctness required |

Step 7: Create ATF Tests for the Skill

Automated testing ensures skill quality across updates.

Create ATF Test:

MCP Approach:

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"

Create Test Steps:

Step 1 -- Set up test incident:

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>"
      }
    }'

Step 2 -- Invoke the skill:

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}"
    }'

Step 3 -- Validate output format:

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}
      ]
    }'

Step 4 -- Clean up test data:

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 Approach:

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

Step 8: Create Skill Test Cases

Dedicated skill test cases for quality validation.

MCP Approach:

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

Step 9: Deploy and Activate the Skill

MCP Approach:

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

Verify all components are in place:

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

Step 10: Monitor Skill Performance

Query skill execution logs:

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

Track feedback:

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

Monitor token usage:

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

Tool Usage

| Tool | Purpose | When to Use | |------|---------|-------------| | SN-Query-Table | Find existing skills, test results, feedback | Discovery and monitoring | | SN-Create-Record | Create skills, inputs, outputs, prompts, tests | Building skill components | | SN-Update-Record | Modify prompts, activate skills, version updates | Iteration and deployment | | SN-Get-Table-Schema | Discover skill table fields | Understanding available configurations |

Best Practices

1. Design inputs carefully -- only include fields that are genuinely needed for the LLM task
2. Use structured prompt templates with clear sections and output format specifications
3. Keep temperature low for analytical skills (classification, extraction) and moderate for generative skills
4. Write comprehensive ATF tests covering edge cases, empty inputs, and expected failure modes
5. Version your skills using semantic versioning (major.minor.patch)
6. Use preprocessing prompts to extract entities before the main analysis prompt
7. Set max_tokens appropriately -- too low truncates output, too high wastes tokens
8. Include postprocessing to validate and format LLM output before displaying to users
9. Monitor token usage to manage costs and identify optimization opportunities
10. Iterate on prompts based on feedback -- small prompt changes can significantly impact quality

Troubleshooting

| Issue | Cause | Resolution | |-------|-------|------------| | Skill not appearing in Now Assist | Status is draft or skill inactive | Publish and activate the skill | | Inputs not populated | Source field mapping incorrect | Verify source_field and source_table match target record | | Output format inconsistent | Prompt template lacks explicit format instructions | Add structured output format with examples in prompt | | ATF test fails intermittently | LLM non-determinism at higher temperatures | Lower temperature or use fuzzy assertions | | Skill execution timeout | Prompt too large or chained LLM calls too many | Reduce input size, simplify prompt chain | | Empty output returned | LLM config not linked or inactive | Verify gen_ai_config is active and linked to skill | | Confidence score always low | Insufficient context in inputs | Add more relevant input fields or knowledge context | | Prompt injection vulnerability | User input not sanitized | Add input validation in preprocessing step |

Examples

Example 1: Incident Summarization Skill

Create a custom skill to summarize incident history:

• Inputs: short_description, description, work_notes, comments, state, priority
• Prompt: Summarize incident timeline, key actions taken, current status in 3-5 bullet points
• Outputs: summary (rich_text), key_dates (text), next_action (text)
• LLM Config: Temperature 0.2, max 400 tokens
• Tests: Network incident with 10+ work notes, simple incident with minimal notes

Example 2: Ticket Classification Skill

Create a custom skill for automated ticket categorization:

• Inputs: short_description, description, caller_id.department
• Prompt: Classify into category/subcategory from predefined taxonomy, return JSON
• Outputs: suggested_category (text), suggested_subcategory (text), confidence (badge)
• LLM Config: Temperature 0.0, max 200 tokens for deterministic classification
• Tests: 10+ test cases covering each category with known correct classifications

Example 3: Resolution Notes Generator

Create a custom skill to generate resolution documentation:

• Inputs: short_description, description, work_notes, close_code, resolved_by
• Prompt: Generate professional resolution notes documenting the problem, investigation steps, root cause, and fix applied
• Outputs: resolution_notes (rich_text), knowledge_candidate (text), reusable_solution (text)
• LLM Config: Temperature 0.4, max 600 tokens for structured but readable output
• Tests: Hardware failure, software bug, user error scenarios with expected resolution patterns

Related Skills

• genai/now-assist-qa - Q&A skill configuration that complements custom skills
• genai/ai-search-rag - RAG configuration for knowledge-grounded custom skills
• genai/flow-generation - Flows that can trigger custom skills as actions
• genai/playbook-generation - Playbooks that incorporate custom skill invocations
• development/atf-testing - ATF framework for comprehensive skill testing