Writing effective skill instructions
The words you use to describe a skill matter more than the code behind it. How to write instructions that agents actually follow.
You can build the most powerful skill in the world, and it won’t matter if the agent doesn’t know when to use it. The description you write, the parameters you name, the examples you include: that’s the real interface. Not the code. The words.
This is true whether you’re a developer writing tool definitions for an API, or someone configuring custom instructions for ChatGPT or a Claude project. The principle is the same. You’re writing for an audience that takes your instructions literally, has no background context, and needs to make split-second decisions about which tool fits the job.
The description is the interface
When an agent receives a user request, it looks at the list of available skills and picks one (or several) based on their descriptions. That’s it. The agent doesn’t read your source code. It doesn’t understand your architecture diagram. It reads a short block of text and decides: “Is this the right tool for what the user just asked?”
If your description is vague, the agent will either skip your skill entirely or use it in the wrong situations. Too clever or abstract? Same problem. The agent needs plain, specific language about what the skill does, when to use it, and what it gives back.
Think of it like writing a sign for a door. “Conference Room B - seats 8, has projector, book via calendar app” is useful. “Collaborative Ideation Space” is not.
What good instructions include
A strong skill description covers five things. You don’t need to write an essay for each one, but you should at least think through all of them.
1. What it does
Start with the basics. One or two sentences about the skill’s purpose, written in concrete terms.
Weak: “Manages files.”
Better: “Searches for files by name or content within a specified directory. Returns matching file paths and a preview of each match.”
The weak version could mean anything. Does it create files? Delete them? Move them? The better version tells you exactly what to expect.
2. When to use it
This is where most descriptions fall short. You need to tell the agent what situations call for this skill. Be specific about the trigger conditions.
“Use this skill when the user asks to find a file, locate code, or search for text within their project. This is the right choice for any request that involves looking for something in the codebase.”
3. When NOT to use it
Saying when not to use a skill is just as important as saying when to use it. Agents don’t have your judgment. They need guardrails.
“Do not use this skill for reading the full contents of a known file. If the user specifies an exact file path, use the read_file skill instead. This skill is for searching, not reading.”
Without that negative instruction, the agent might use your search skill every time someone mentions a file, even when a simpler tool would be better.
4. What it returns
Agents need to know what they’ll get back so they can plan their next step. If your skill returns a list of file paths, say so. If it returns a summary, say so. If it returns raw JSON, describe the structure.
“Returns a list of objects, each containing: the file path, the line number of the match, and a three-line preview centered on the matching text.”
5. Edge cases and limitations
Every skill has boundaries. Be honest about them.
“Maximum of 50 results per search. If the directory contains more than 10,000 files, the search may take several seconds. Does not search binary files or files larger than 5MB.”
Before and after
Let’s look at a few skill descriptions and see how they improve with better instructions.
Example: a weather skill
Before:
“Gets weather information.”
This tells the agent almost nothing. Weather for where? Current conditions or forecast? What format? The agent is left guessing.
After:
“Retrieves the current weather conditions for a given city or zip code. Returns temperature (Fahrenheit), conditions (sunny, cloudy, rain, etc.), humidity percentage, and wind speed in mph. Use this when the user asks about current weather. For multi-day forecasts, use the get_forecast skill instead.”
Now the agent knows what data it gets back, what input it needs, and when to pick a different skill. That last sentence does a lot of the heavy lifting.
Example: a send-email skill
Before:
“Sends emails to recipients.”
After:
“Sends an email from the user’s connected account. Requires a recipient address, subject line, and body text. Optionally accepts CC addresses and attachments. Always confirm the recipient and message content with the user before sending. Do not use this for drafting emails the user hasn’t asked to send. Returns a confirmation with the message ID and timestamp.”
Notice the behavioral instruction: “Always confirm with the user before sending.” You can embed guidelines like this directly in the description. The agent will follow them.
Example: custom instructions for a ChatGPT project
You don’t have to be a developer to write skill instructions. If you’ve set up a custom GPT or a Claude project, you’ve already written instructions for an agent. The same principles apply.
Before:
“You help with cooking.”
After:
“You’re a cooking assistant. When the user asks for a recipe, always ask about dietary restrictions and how many servings they need before giving the recipe. Keep recipes practical for a home kitchen. Don’t suggest techniques that require professional equipment. If a user asks about food safety (like whether something is safe to eat), always err on the side of caution and recommend they check with official guidelines.”
The second version gives the agent a clear decision framework. It knows to ask follow-up questions, to stay practical, and to be cautious on safety topics.
Common mistakes
Being too terse. “Searches files” doesn’t tell the agent what kind of search, what parameters it needs, or what it returns. You’ve given the agent a toolbox with no labels.
Being too abstract. “Provides a unified interface to the file system for resource discovery and content retrieval across heterogeneous storage backends.” Nobody talks like this. More importantly, it doesn’t help the agent decide when to pick this skill. Describe what it does, not how impressive it sounds.
Assuming context. Your agent doesn’t know your project structure, your naming conventions, or your team’s preferences unless you tell it. A description like “processes the standard input format” is useless because the agent has no idea what “standard” means to you.
Writing overlapping descriptions. If two skills have descriptions that sound similar, the agent will pick the wrong one half the time. Make sure each skill’s description clearly distinguishes it from related skills. “Use this for X, use [other_skill] for Y” goes a long way.
Forgetting about output. Many descriptions explain what the skill does but not what it returns. The agent needs to know what it’s getting back so it can use that information in its next step. Always describe the output format.
Testing your instructions
Here’s a practical exercise. Once you’ve written your skill descriptions, test them with ambiguous requests. Give the agent a prompt that could plausibly match more than one skill and see which one it picks.
For instance, if you have both a search_files and a read_file skill, try: “What’s in the config file?” Does the agent search for it or try to read it directly? If it picks the wrong one, your descriptions need work.
Try these kinds of tests:
- A request that could match two skills. Does it pick the right one?
- A request that matches no skill. Does it gracefully say it can’t help, or does it force-fit a wrong tool?
- A request where the skill will fail (bad input, missing data). Does the agent handle the failure or get stuck?
If the agent consistently picks the right skill for the right situation, your descriptions are doing their job. If not, the fix is almost always in the words, not the code.
This applies to everyone
You might be thinking this is only for developers building tools. It isn’t. Anyone who writes custom instructions for an AI assistant is doing the same thing. You’re telling a system how to behave, when to do what, and what to watch out for.
If you’ve set up a custom GPT for your team, or configured a Claude project with specific instructions, or even just written a detailed system prompt, you’ve been writing skill instructions. The tips here (being specific about when to act, describing what you expect, mentioning what to avoid) will make those instructions work better too.
For a broader look at how skills are structured under the hood, see Anatomy of a Well-Designed Skill. And if you want to get better at the prompting side of things, Tips for Better Results covers how to communicate with AI more effectively.
The short version
Write for an agent that knows nothing about your project, your preferences, or your intentions. Be specific about what the skill does, when to use it, when not to use it, what it returns, and where it breaks. Test with ambiguous requests. Revise based on what the agent actually does, not what you think it should do.
The best skill in the world is the one the agent actually uses correctly. That comes down to how you describe it.