Writing Effective Skill Names & Descriptions
Structure
The name follows a simple pattern:
[Action Verb] + [Object] + [Optional: System/Scope]
The description answers three questions:
- What does this skill do?
- When should it be used?
- What inputs does it need (if any)?
Best Practices
For names:
| Do | Don't |
|---|---|
| Start with an action verb (Fetch, Create, Update, Send) | Start with the system name ("ServiceNow…") |
| Name the specific object or outcome | Use generic nouns ("Data", "Helper", "Tool") |
| Keep it short—ideally 3–6 words | Pack the full description into the name |
| Make it unique across your skill set | Reuse near-identical names that confuse routing |
| Match the user's vocabulary | Use internal jargon or acronyms users won't say |
For descriptions:
| Do | Don't |
|---|---|
| Be specific about the action | Use vague terms like "handles" or "manages" |
| Mention the system/data source | Assume context is obvious |
| Specify required inputs | Leave input requirements unclear |
Examples
Good
Skill: Fetch Employee Leave Balance
Retrieves remaining leave balance for an employee from Workday.Use when employee asks about PTO, vacation days, sick leave,or remaining holidays. Requires employee ID.
Skill: Create IT Support Ticket
Creates a new incident ticket in ServiceNow for IT issues.Use for hardware problems, software access, VPN issues, orpassword resets. Requires issue description and urgency level.
Skill: Send Manager Notification
Sends an email notification to the employee's direct manager.Use within approval workflows to alert managers of pendingactions. Requires employee ID and notification message.
Poor
Names
| Name | Problem |
|---|---|
| "Password Skill" | No action verb; "Skill" adds nothing |
| "Workday Integration" | Names a connection, not an action |
| "Ticket Stuff" | Vague—no clear object or outcome |
Descriptions
| Description | Problem |
|---|---|
| "Handles leave requests" | Too vague—fetch, submit, or approve? |
| "ServiceNow integration" | Doesn't explain what action it performs |
| "Employee data skill" | No indication of when to use it |
Tips
- Use action verbs: Fetch, Create, Update, Send, Calculate, Validate—in both the name and description.
- Keep the name and description in agreement: The name is the headline, the description is the detail—they should describe the same thing.
- Be distinct: If two skills could match the same query (e.g. Fetch Leave Balance vs. Submit Leave Request), make the difference obvious in the name.
- Include synonyms in the description: "PTO, vacation, leave, time-off" helps match varied queries.
- Keep descriptions under 50 words: Concise descriptions perform better.
- Stay scannable: A human (and the AI) should grasp the purpose at a glance.