8 useful tips for writing agent skills.

But this flexibility also makes it difficult to know which skills are good and which are effective. Which skills are worth creating? What's the secret to writing a good skill? When should you share them with others?

Skills are currently being used a lot. Here are some helpful tips for the process!

1. Understand what a skill is.

Skill is a folder containing the SKILL.md file and may include some supporting files:

my-skill/ ├── SKILL.md ← File bắt buộc duy nhất ├── scripts/ ← Code có thể tái sử dụng mà agnet có thể chạy ├── references/ ← Tài liệu mà agent đọc khi cần └── assets/ ← Template, hình ảnh hoặc file được sử dụng trong đầu ra

A skill consists of 3 layers:

1. nameand description( Frontmatter ): Included in every prompt and tells the agent when to use the skill.
2. The body of the code provides SKILL.mdMarkdown instructions (below the introduction) to tell the agent how to perform the task.
3. Assets (optional): The folders scripts/, references/and assets/.

Skills are always divided into two types:

1. Capability skills enable agents to perform tasks that the basic model cannot consistently do (e.g., filling out PDF forms) without them. These skills may become unnecessary as the model improves; evaluations will tell you when.
2. Preference skills define your specific workflow (e.g., your team's code review steps). These skills are robust but need to align with your actual processes.

2. Complete the description.

The descriptioncore SKILL.mdof your code is the activation mechanism. If it's vague, the agent won't know when to activate the skill. If it's too general, the skill will be activated on every request. Be specific about what the skill does AND when to use it. Include both "what" and "when" in the description. The body of the skill is only loaded after the skill is activated.

Performance can be improved by 50% simply by improving the description.

3. Write instructions, not an essay.

Agents are very intelligent. Your job is to tell them what they don't know. Research shows that long, comprehensive descriptions with too much context actually reduce performance.

1. Use the directive : "Always use interactions.create()", not "Interactions API is the recommended method". The first sentence is a directive, the second is irrelevant information that the agent will not implement.
2. Include an example : A five-line code snippet is better than a five-paragraph explanation.
3. Explain the reason : When a rule is important, state the reason clearly. "Use model X, model Y is outdated and will return an error" helps the agent generalize beyond specific test cases, rather than just memorizing it.
4. Don't overtrain : Avoid "cumbersome" changes that only pass your 3 prompt tests. Write skills that work across millions of calls.

4. Keep your skills concise.

Don't put everything in one file. The agent loads information in layers:

1. Always loaded: Frontmatter of SKILL.md, name+description
2. Loaded when the skill is activated: the body of SKILL.md(keep below 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 file it needs. This saves context for the actual task.

Tip : If a referenced file is longer than 500 lines, add a table of contents with "line hints" at the beginning so the agent can quickly find what it needs.

5. Set the appropriate level of freedom.

A common mistake when creating a skill is turning it into a step-by-step workflow: "Step 1: Read the file. Step 2: Parse the JSON. Step 3: Extract the fields…" By specifying each step, you deprive them of the ability to adapt, troubleshoot, or find a better approach. Describe what you want, not the path to achieving it.

Tell the agent the goal to be achieved:

❌ "Step 1: Read the configuration file. Step 2: Find the database URL. Step 3: Update the port number. Step 4: Save the file."

✅ "Update the database port in the configuration file to the user-specified value."

Provide constraints, not procedures:

❌ "Step 1: Create a branch. Step 2: Make changes. Step 3: Run tests. Step 4: Open a pull request (PR)."

✅ "Always run tests before opening a pull request. Never push directly to the main branch."

If specific steps are crucial, write a script . If the task is prone to errors and performing step 3 before step 2 breaks everything, it's not a skill issue, but rather a scripting problem.

6. Don't overlook negative cases!

Think about when a skill shouldn't be activated. A description like "Use for any programming task" will take control of all requests.

"Use this when working with PDF files. Do NOT use it for editing documents in general, spreadsheets, or plain text files."

It's essential to check both "should activate" and "shouldn't activate" scenarios. Otherwise, you'll be optimizing the skill in only one direction.

7. Pre-release testing

Don't release a skill without testing it. Each run might work differently, so one test isn't enough.

1. Run it manually a few times with different prompts. Observe where the error occurs. Does it assume a dependency exists? Does it skip steps?
2. Document what constitutes a "success ." Does the output compile? Does it use the correct API? Does it follow the steps? Evaluate the result, not the path.
3. Try 10-20 prompt tests . Combine prompts that the skill should handle, prompts that the skill should ignore, and difficult exceptions. Each prompt should have its own success criteria.
4. Run multiple trials . The agent's output is not deterministic. Run 3-5 trials for each prompt and observe the distribution instead of just a single success/failure result.
5. Separate each run . Use a clean environment for each test. Context leaks between runs hide real errors.
6. Please revise the description first . Most of the problems lie in the trigger, not the instructions.

8. Know when to remove a skill.

Run assessments without that skill. If they succeed, the model has absorbed the value of the skill, and that skill is no longer needed. Eliminate it! This is especially true for capability skills; as models improve, the gap will narrow.