Write a skill description that explains when to use it
Translated from Korean. View original
If a skill works when called explicitly but is not used for everyday requests, inspect its description. It helps the tool decide when to select the skill. Instead of promotional copy, describe the material it handles and the requests it serves. Collecting three frequent requests gives you a starting point.
How is the description different from the body?
The description identifies when to use the skill; the body contains the actual workflow and criteria. Identify the target if the title alone is unclear. ‘Proofread a Korean customer announcement’ suggests a more specific situation than ‘proofreading.’
Do not squeeze the whole procedure into the description. Rules about checking the original, preserving numbers and output format can go in the body.
How do I improve a vague description?
‘The best writing expert’ does not identify the task. Describe an observable action, such as correcting awkward translated phrasing and repetition in customer notices.
Example: description: Proofread Korean notices sent to customers. Use when asked to polish awkward sentences, translated phrasing or repetition in an announcement draft.
The body can contain rules such as preserving figures and dates, separately marking legal text and noting places where a revision might change meaning.
- The best writing assistant
- Improve all content quality
- Support efficient work
- Target: customer notices
- Task: correct awkward sentences
- Situation: polish an announcement draft
Should I include the user's own wording?
If people usually ask ‘This sentence sounds awkward’ rather than using a technical term for editing, reflect that wording. Avoid a long list of near-synonyms that blurs the skill's scope; a few expressions for the same task are enough.
Write down three recent requests. If ‘polish the announcement tone,’ ‘fix translated phrasing in a customer email’ and ‘make the notice sound natural’ use the same criteria, one skill description may cover them.
What if it is repeatedly selected for other tasks?
Look for overly broad wording such as ‘all writing.’ If a customer-notice proofreading skill is selected for a novel draft, clarify the target and exclusions. If unrelated purposes keep accumulating in one skill, consider splitting it.
Include counterexamples in tests: it should be used for ‘Polish this notice,’ but not merely proofread and stop when asked to investigate an article's factual claims.
How do I compare a revised description?
Test requests with the same meaning in different words. Use an explicit invocation to inspect the body, and a request without the name to check selection. Where possible, compare under the same conditions in a new conversation.
Example record: request ‘Make this notice sound natural’ / expected ‘Use the notice proofreading skill’ / actual ‘General summary’ / candidate fix ‘Add polishing announcement drafts to the description.’ Change one part at a time to see what helped.
Frequently asked questions
Q. Does writing ‘always’ guarantee automatic invocation? A. No. First check whether the file is in a discoverable location and whether a setting prevents automatic invocation.
Q. Is a shorter description always better? A. The useful information matters more than length. Include enough to identify the target and use case, and remove repeated modifiers.