Overview

Custom Skills give Bolt Agents more precise instructions, but they still need clear triggers, correct availability settings, active agent configuration, and well-structured actions. When a skill does not behave as expected, start by checking whether it was available, enabled, evaluated, and matched.

The fastest troubleshooting path is to reproduce the issue in Test Agent and inspect Debug Trace. Debug Trace shows which skills were evaluated, which skill matched, and which skills were skipped.

Below, we will cover:

A quick troubleshooting checklist
Why a skill did not fire
Why the wrong skill fired
Why the agent did not take the expected action
How to troubleshoot inbound and outbound conversations
When to escalate to your Element451 team

Quick troubleshooting checklist

Use this checklist before editing the skill:

Confirm the skill is saved
Confirm the skill is enabled on the correct agent
Confirm the correct channel is selected in Availability
Confirm the schedule allows the skill to run at the test time
Confirm the trigger clearly matches the user's message
Confirm the skill is high enough in priority order
Test in Test Agent using the same channel
Open Debug Trace and review why the skill matched or was skipped

The skill did not fire

If a Custom Skill did not fire, check whether the skill was available and enabled before changing the trigger.

Common causes include:

Cause	What to check
Skill not enabled on the agent	Open the agent's Skills page and confirm the Custom Skill toggle is on
Channel not selected	Open Conditions > Channels and confirm the conversation's channel is selected
Schedule restricted	Check Restrict by schedule and confirm the test time falls inside the window
Trigger too narrow	Compare the student's exact message to the trigger wording
Higher-priority skill matched first	Review Debug Trace and the active skill order on the agent
Skill not saved	Return to the skill editor and confirm changes were saved

The wrong skill fired

If the wrong skill fired, the issue is usually priority or overlapping triggers.

To fix it:

Open the agent's Settings > Skills page
Review the active Custom Skills
Identify which skills could match the same message
Move the more specific skill higher in the priority order
Narrow broad triggers so they do not capture unrelated messages
Retest in Test Agent

✨ Pro Tip: Write broad skills last. Start with the specific, high-value scenarios first, then add broader routing skills once the specific skills are working.

The agent response was too generic

If the skill fired but the response was too generic, the action instructions may not be specific enough.

Improve the Action by adding:

A clear goal
Required qualifying questions
Decision logic for common paths
Tool chips for specific system actions
Rules that tell the agent what not to do
Escalation or task creation instructions when the agent cannot complete the request

For example, instead of writing "Help the student schedule a visit," tell the agent exactly how to identify the visit type, when to use Register for Event, when to use Schedule Appointment, and when to use Create Task.

The agent used the wrong tool or did not use a tool

If the agent did not take the expected action, check whether the tool is included in the Action instructions and configured correctly.

Review these areas:

The tool chip appears in the Action Description or Rules
The selected event, appointment type, label, task, or transfer destination is correct
The action tells the agent when to use the tool
The action tells the agent when not to use the tool
The student clearly confirmed the required choice before the tool action

🚨 Important: Do not rely on vague wording when a specific system action is required. Use a configured tool chip whenever the agent should register for an event, schedule an appointment, create a task, add a label, or transfer a call.

The skill works in one channel but not another

Custom Skills can behave differently across channels because each channel has different conversation patterns and response expectations.

If the skill works in one channel but not another:

Confirm the channel is selected in Conditions > Channels
Test the same intent in each enabled channel
Review Debug Trace for each channel
Update the trigger if students phrase the same intent differently on that channel
Add channel-specific rules if needed

For example, a voice caller may say "Can I talk to someone?" while a Messenger visitor may type "Can someone help me with financial aid?" Both may need the same routing outcome, but the trigger should account for the intent across channels.

The skill behaves unexpectedly in an outbound Job conversation

For outbound Jobs, confirm that the Custom Skill is enabled on the same agent running the Job and that the skill is designed to match the recipient's reply.

Troubleshoot the path this way:

Identify the agent used by the Job
Open that agent's Settings > Skills page
Confirm the Custom Skill is active
Confirm the skill's channel availability matches the Job channel
Reproduce the student reply in Test Agent
Open Debug Trace to confirm whether the skill matched
If the skill does not match, revise the trigger around the reply intent

📌 Note: A Job starts the outreach. A Custom Skill handles the conversation when the recipient's reply matches the skill's trigger and the skill is available for that channel.

The skill should not have fired

If a Custom Skill fired when it should not have, the trigger is probably too broad or the skill priority is too high.

To fix it:

Read the exact student message
Compare it to the trigger
Add exclusions or more specific intent language
Move broader skills lower in priority
Add a rule telling the agent when not to proceed
Retest with both matching and non-matching examples

Bad trigger:

"Student asks about campus."

Better trigger:

"Prospective student or family member asks about visiting campus, taking a tour, attending an open house, joining an information session, or seeing campus before applying or enrolling."

Escalate when the issue looks like a product bug

Escalate the issue to your Element451 team when configuration appears correct but the skill still does not behave as expected.

Include this information when escalating:

Agent name
Custom Skill name
Channel
Approximate date and time of the conversation
Student message that should have triggered the skill
Expected behavior
Actual behavior
Screenshot of Debug Trace
Whether the issue occurred in live conversation, Test Agent, or a Job conversation

Troubleshooting examples

Example 1: Skill skipped because of channel

A campus visit skill is configured for Messenger and Email, but the student replies by SMS. The skill is skipped because SMS is not selected in Channels.

Fix: Add SMS to the skill's channel availability, then test again.