# 7 Tips to Write Great Skills for Your AI Agents

DevFeed: [7 Tips to Write Great Skills for Your AI Agents](<https://devfeed.tech/articles/7-tips-to-write-great-skills-for-your-ai-agents-109928.md>)

Original publisher: [Read original article](<https://craftbettersoftware.com/p/7-tips-to-write-great-skills-for>)

Author: Daniel Moka

Published: 2026-10-31T06:01:38Z

Content type: article

Language: en

Sources: [Craft Better Software](<https://devfeed.tech/sources/craft-better-software.md>)

Topics: [Agent Skills](<https://devfeed.tech/topics/agent-skills.md>), [Developer skills](<https://devfeed.tech/topics/developer-skills.md>), [Learning](<https://devfeed.tech/topics/learning.md>)

Tags: [agent-skills](<https://devfeed.tech/tags/agent-skills.md>), [agentic](<https://devfeed.tech/tags/agentic.md>), [agentic-engineering](<https://devfeed.tech/tags/agentic-engineering.md>), [agents](<https://devfeed.tech/tags/agents.md>), [how-to](<https://devfeed.tech/tags/how-to.md>), [skills](<https://devfeed.tech/tags/skills.md>), [tips](<https://devfeed.tech/tags/tips.md>)

## AI overview

The article argues that reliable agent skills need concise, task-specific instructions supported by files and scripts. It recommends keeping SKILL.md under 500 lines, linking supporting files directly, and using clear names and tables of contents for long references so details load only when needed. Put repeatable mechanics such as builds and checks in scripts, while leaving context-dependent decisions to the model. Write skill descriptions with the words users use to trigger them; record real recurring failures in a short GOTCHAS.md; provide a finished output example; and remove generic instructions that do not change behavior. Finally, maintain shared skills in one Git repository: use linked global skills for common tasks and keep project-specific skills in the project. The text says the same skill folder can work with Claude Code, Codex, and Cursor.

## Source excerpt

The 7 mistakes I find in almost every skill, and how to fix them