A skill packages instructions, resources, and optional scripts so that you don’t need to tell your agents to so something over and over again.

Fix 1: Build clear skills

Don’t just build whatever skill you think you might need. Instead it should be a more careful process, following the guidelines below:

• Keep each skill scoped to one job.
• Think about the kinds of trigger phrases a user would actually say.
• Get a workflow working first. Then make it a skill.
• Include scripts or extra assets only when they improve reliability.

Once a skill works really well and you observe that it needs to be run periodically, you can turn it into an automation.

To evaluate how good a skill is, follow these criteria. If a skill is poor at these, don’t be scared to get rid of/redesign it because this will help you do much better work:

• Atomic Scoping: Each tool should do one thing well (e.g., copy_file, move_file instead of manage_files).
• Gerund Naming: Use the ing form for skill names (e.g., fixing-bugs, testing-code) to imply an ongoing capability.
• Strict Contracts: Use strong typing and JSON Schemas for inputs/outputs. Trim outputs to minimize token usage.
• Informative Errors: Return structured error messages that explain why a tool failed so the agent can self-correct.
• Progressive Disclosure: Keep core instructions concise; move detailed reference material (error codes, complex schemas) to separate assets loaded only when needed.