Mastering Agent Skills: 8 Essential Tips for Writing Effective Extensions

Skills have become the most common extension mechanism for AI Agents. They're flexible, easy to create, and simple to distribute—but this flexibility also makes it challenging to know best practices. This article shares eight proven tips for writing high-quality Agent skills.

---

Table of Contents

1. Understand the Nature of Skills
2. Define Trigger Conditions Precisely
3. Write Instructions, Not Essays
4. Keep Content Lean
5. Set Appropriate Freedom Levels
6. Consider Negative Cases
7. Test Thoroughly Before Shipping
8. Retire Skills When Appropriate

---

1. Understand the Nature of Skills

A skill is a folder containing a SKILL.md file, with optional helper files:

my-skill/
├── SKILL.md ← The only required file
├── scripts/ ← Reusable code the agent can run
├── references/ ← Docs the agent reads when needed
└── assets/ ← Templates, images, or output files

Skills consist of three layers:

• Name and Description Frontmatter: Goes into every prompt and tells the agent when to use the skill
• SKILL.md Body: Markdown instructions telling the agent how to execute the task
• Asset Files (optional): scripts/, references/, and assets/ folders

Skills typically fall into two categories:

• Capability Skills: Help agents complete tasks that base models can't perform consistently (e.g., PDF form filling). These may become unnecessary as models improve—evaluations will tell you when.
• Preference Skills: Encode your specific workflow (e.g., your team's code review process). These are durable but need to stay in sync with your actual processes.

---

2. Define Trigger Conditions Precisely

The description in your SKILL.md is the trigger mechanism. Too vague, and the agent won't know when to activate the skill. Too broad, and the skill fires on every request. Be specific about what the skill does and when to use it. The skill body only loads after the skill triggers.

❌ Too Vague	✅ Specific and Actionable
"Helps with documents"	"Create, edit, and analyze .docx files, use for tracked changes, comments, formatting, or text extraction"
"API helper"	"Use when writing code that calls the Gemini API for text generation, multi-turn chat, image generation, or streaming"

I've seen 50% improvements just by improving the description.

---

3. Write Instructions, Not Essays

Agents are smart. Your job is to tell them what they don't already know. Research shows that longer, more comprehensive content with too much context actually hurts performance.

• Use imperatives: "Always use interactions.create()" rather than "The Interactions API is the recommended approach." The first is an instruction; the second is trivia the agent won't act on.
• Lead with examples: A 5-line code snippet beats a 5-paragraph explanation.
• Explain the why: When a rule matters, explain why. "Use model X, model Y is deprecated and will return errors" helps the agent generalize beyond specific test cases rather than just memorize.
• Avoid overfitting: Don't make changes that only pass your three test prompts. Write skills that work across millions of invocations.

---

4. Keep Content Lean

Don't dump everything into one file. Agents load information in layers:

1. Always loaded: SKILL.md frontmatter—name + description
2. Loaded when skill triggers: SKILL.md body (keep under 500 lines)
3. Loaded on demand: Reference files, scripts, assets

If your skill covers multiple topics (e.g., AWS vs. GCP deployment), split them into separate reference files. The agent only reads the one it needs, saving context for the actual task.

Tip: If a reference file exceeds 500 lines, add a table of contents with "line hints" at the top so the agent can quickly find what it needs.

---

5. Set Appropriate Freedom Levels

A common mistake in creating skills is turning them into step-by-step workflows: "Step 1: Read the file. Step 2: Parse the JSON. Step 3: Extract the fields..." When you dictate every step, you take away the agent's ability to adapt, recover from errors, or find better approaches. Describe what you want, not the path to get there.

Tell the agent what to achieve:

• ❌ "Step 1: Read the config file. Step 2: Find the database URL. Step 3: Update the port number. Step 4: Write the file back."
• ✅ "Update the database port in the config file to the value specified by the user."

Provide constraints, not procedures:

• ❌ "Step 1: Create a branch. Step 2: Make the change. Step 3: Run tests. Step 4: Open a PR."
• ✅ "Always run tests before opening a PR. Never push directly to main."

If exact steps matter, write a script. If the task is fragile and doing step 3 before step 2 breaks everything, that's not a skill problem—it's a scripting problem.

---

6. Consider Negative Cases

Think about when the skill should not fire. A description like "Use for any coding task" will hijack every request.

"Use when working with PDF files. Do NOT use for general document editing, spreadsheets, or plain text files."

Testing both "should trigger" and "shouldn't trigger" cases is essential. Without this, you'll optimize the skill in only one direction.

---

7. Test Thoroughly Before Shipping

Don't ship a skill without evaluating it. Each run might behave differently, so a single check isn't enough.

1. Run it manually a few times with different prompts. Watch where it breaks. Does it assume a dependency exists? Does it skip steps?
2. Define what "success" looks like measurably. Does the output compile? Does it use the right API? Did it follow the steps? Grade outcomes, not paths.
3. Try 10–20 test prompts. Mix prompts the skill should handle, prompts it should ignore, and tricky edge cases. Each prompt should have its own success criteria.
4. Run multiple trials. Agent output is nondeterministic. Run 3–5 trials per prompt and look at the distribution instead of a single pass/fail.
5. Isolate each run. Use a clean environment for each test. Context bleeding between runs masks real failures.
6. Fix the description first. Most problems are in the trigger, not the instructions.

---

8. Retire Skills When Appropriate

Run evaluations without the skill. If they pass, the model has absorbed the skill's value and the skill is no longer necessary. Retire it. This is especially true for capability skills—as models improve, the gap narrows.

For a practical step-by-step evaluation workflow, see Practical Guide to Evaluating and Testing Agent Skills.

---

Frequently Asked Questions

When should I create a capability skill versus a preference skill?

Create capability skills when base models can't perform a task consistently. Create preference skills when you need to encode specific team workflows. Capability skills may become obsolete as models improve; preference skills are more durable.

How do I know if my skill description is specific enough?

If the skill triggers when it shouldn't, or doesn't trigger when it should, the description needs improvement. A specific description should include both "what it does" and "when to use it."

How long should the skill body be?

Keep it under 500 lines. If it's longer, split content into separate reference files that the agent loads on demand.

Why should I avoid step-by-step instructions?

Step-by-step instructions limit the agent's adaptability. Describing goals and constraints is more effective than prescribing specific paths, unless the task is extremely fragile and requires precise sequencing.

What's the most effective way to test skills?

Use 10-20 test prompts, run 3-5 trials per prompt, isolate each run, define clear success criteria, and prioritize fixing trigger mechanism issues first.