Best Practices for Skill Creators

This is how to write clearly defined skills that are appropriate for the task!

Start with Practical Expertise

A common mistake in skill creation is asking LLMs to generate skills without providing specific domain context—relying solely on the LLM's general training knowledge. The result is vague, generic processes ('handle errors appropriately', 'follow best practices for validation') instead of specific API patterns, exceptions, and project conventions that make skills valuable.

Effective skills are built upon practical expertise. The key is to provide specific field context into the skill development process.

Extracted from a Real-world Task

Complete a practical task within a conversation with an agent, providing context, input, and preferences throughout the process. Then, extract a reusable template to create a skill. Pay attention to:

• The steps that worked - the sequence of actions that led to success.
• The edits you made – the places where you instructed the agent's approach (e.g., 'use library X instead of Y', 'check exception Z')
• Input/Output Format - What does input and output data look like?
• The context you provided —specific project events, conventions, or constraints that the agent is unaware of.

Compiled from Existing Project Documents

Once you have a body of existing knowledge, you can feed it into an LLM and ask it to synthesize a skill. A data path skill synthesized from your team's actual incident reports and operating manuals will perform better than one synthesized from a generic article on 'data engineering best practices,' because it captures your schema, failure modes, and recovery processes. The key is project-specific documentation, not generic references. Good sources include:

• Internal documents, operating manuals, and style guides.
• API specifications, schema, and configuration files.
• Provide feedback on the code and troubleshooting tools (record common concerns and expectations of the reviewers).
• Version control history, especially bug fixes and patches (reveals patterns through what actually changed).
• Real-world error scenarios and how to resolve them.

Refine Through Practical Implementation

The first draft of a skill often needs refinement. Run the skill with real-world tasks, then feed the results—everything, not just the errors—back into the creation process. Ask yourself: what caused the false positives? What was missed? What can be eliminated?

Even a single trial run followed by revisions can significantly improve quality, and complex fields often benefit from multiple such runs.

? Read the agent's execution trail, not just the final output. If the agent wastes time on inefficient steps, common causes include overly vague instructions (the agent tries several approaches before finding one that works), instructions that don't apply to the current task (the agent still follows them), or too many options provided without a clear default option.

To adopt a more structured approach to the iterative process, including test cases, validation, and scoring.

Use Context Wisely

Once a skill is activated, its entire SKILL.md file is loaded into the agent's context window along with conversation history, system context, and other active skills. Every word in your skill competes for the agent's attention with everything else in that window.

Add What the Agent Is Missing, Ignore What Is Already Known

Focus on what the agent wouldn't know without your skills: project-specific conventions, industry-specific processes, unclear exceptions, and specific tools or APIs to use. You don't need to explain what PDFs are, how HTTP works, or what database migration entails.

Ask yourself about each item: 'Would the agent make a mistake doing this without instructions?' If the answer is no, eliminate it. If you're unsure, double-check. And if the agent handled the entire task well without that skill, then that skill might not be valuable.

Design Coherent Units

Deciding what a skill should include is similar to deciding what a function should do: You want it to encompass a coherent unit of work that integrates well with other skills. Skills that are too narrow force multiple skills to be loaded for a single task, leading to wasted resources and instruction conflicts. Skills that are too broad become difficult to trigger correctly. A skill for querying a database and formatting results might be a coherent unit, while a skill that also includes database administration might be trying to do too much.

Aiming for a Moderate Level of Detail

Overly comprehensive skills can do more harm than good – the agent will struggle to extract relevant information and may pursue inefficient paths due to instructions that don't apply to the current task. Concise, step-by-step instructions with practical examples are often more effective than overly detailed documentation. When you find yourself dealing with numerous exceptions, consider whether most of those cases could be handled better by the agent's judgment.

The Structure of Major Skills Is Revealed Gradually

The recommended specifications suggest keeping SKILL.md under 500 lines and 5,000 tokens – only the core instructions the agent needs for each run. When a skill truly requires more content, move detailed references to separate files in the references/ directory or similar folders.

It's important to tell the agent when to load each file. 'Read references/api-errors.md if the API returns a status code other than 200' is more useful than the general statement 'see references/ for details'. This allows the agent to load the context on demand rather than right from the start, which is how incremental disclosure is designed to work.

Adjusting Control

Not every part of a skill needs the same level of detail. Adjust the specificity of the instructions to match the sensitivity of the task.

The Right Balance Between Specificity and Vulnerability

Allowing agents freedom of action when multiple valid methods and tasks permit variation is important. For flexible instructions, explaining the reasoning can be more effective than rigid directives – an agent that understands the purpose behind the instruction will make better context-dependent decisions. Code review skills can describe what to look for without specifying precise steps:

English example text

Provide specific guidance when activities are susceptible to disruption, consistency is important, or a particular sequence needs to be followed:

English example text

Most skills require a combination of many factors. Adjust each part independently.

Provides Default Settings, Not Menus

When multiple tools or methods might be effective, choose a default setting and briefly mention the alternatives instead of presenting them as equally good options.

English example textEnglish example text

Prioritize Process Over Claims

A skill should teach learners how to approach a group of problems, not how to create a product for a specific case. Compare:

English example textEnglish example text

This doesn't mean skills can't include specific details—output formatting templates, constraints like 'never output personally identifiable information,' and tool-specific instructions are all valuable. The point is that the approach should be general even when individual details are very specific.

Effective Guidance Templates

These are reusable techniques for structuring skill content. You don't need every skill – use only those that are relevant to your tasks.

Important Notes

The most valuable content in many skills is the list of unforeseen problems—specific environmental facts that contradict reasonable assumptions. This isn't general advice ('handle errors appropriately') but rather specific remedies for mistakes the agent would make if not instructed otherwise:

English example text

Store common errors (gotchas) in the SKILL.md file so the agent can read them before encountering a situation. A separate reference file is also useful if you tell the agent when to load it, but for unclear issues, the agent might not recognize the trigger.

? When the agent makes a mistake that you need to fix, add a bug fix to the gotchas. This is one of the most direct ways to improve skills through iterative practice.

Output Format Template

When you need the agent to produce output in a specific format, provide a template. This is more reliable than describing the format in prose, as agents match patterns well to specific structures. Short templates can be stored directly in SKILL.md; for longer templates or templates only needed in certain cases, store them in the assets/ directory and reference them from SKILL.md so they are only loaded when needed.

English example text

Checklist for a Multi-step Workflow

A clear checklist helps the implementer track progress and avoid missing steps, especially those involving dependencies or validation checks.

English example text

Validation Loop

Instruct the agent to self-validate its job before proceeding. The model is: Perform the job, run the validator (a script, reference checklist, or self-check), fix any issues, and repeat until the validation process is successful.

English example text

References can also serve as a 'verification tool' – guiding the agent to check their work against the references before completion.

Plan -- Verify -- Execute

For batch or destructive operations, have the agent create an intermediate plan in a structured format, verify it against the correct information source, and only then execute it.

English example text

The crucial component is step 3: A validation script checks the plan (field_values.json) against the correct data source (form_fields.json). Errors like 'Field 'signature_date' not found - available fields: customer_name, order_total, signature_date_signed' provide the agent with enough information to self-correct.

Package Reusable Scripts

When iterating through the development of a skill, compare the agent's execution trace across test cases. If you notice the agent automatically regenerating the same logic each time—building graphs, parsing a specific format, validating output—that's a sign that you need to write a script that has been tested once and package it in the scripts/ directory.

FAQ

What is the main point of best practices for skill creators?

This is how to write clearly defined skills that are appropriate for the task! Read the key facts, context, and practical takeaways.

Why is this development important?

Key takeaway: This is how to write clearly defined skills that are appropriate for the task!

What are the key takeaways?

This is how to write clearly defined skills that are appropriate for the task!