Writing Effective Skill Descriptions
A well-written skill description helps the AI understand when to use the skill and what it does. This directly impacts how accurately your AI Colleague responds to queries.
Structure
A good skill description answers three questions:
- What does this skill do?
- When should it be used?
- What inputs does it need (if any)?
Best Practices
| 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 Descriptions
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, or
password 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 pending
actions. Requires employee ID and notification message.Poor 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
- Include synonyms: "PTO, vacation, leave, time-off" helps match varied queries
- Keep it under 50 words: Concise descriptions perform better
Updated 2 days ago