What is SKILL.md?
SKILL.md is the core file of every agent skill. It is a Markdown file with a YAML frontmatter block at the top. The frontmatter provides machine-readable metadata (name, description, version, tags) that AI tools read at startup. The Markdown body contains the actual instructions that are loaded into the agent's context when the skill is activated.
Required fields: name and description
Only two fields are required: name (a human-readable string under 50 characters) and description (a one-line summary that is loaded at startup as part of the skill discovery metadata). The description is the most important field to get right — it is the only text the AI sees before deciding whether to activate the skill. Make it specific and actionable, not generic.
Recommended fields
version (semver string), authors (array of GitHub usernames), tags (array of searchable keywords), and platforms (array of compatible platform slugs) are all recommended. They improve discoverability in directories like agentskills.my and help tools surface the right skill for the right context.
Writing effective instruction bodies
The instruction body is plain Markdown loaded on demand. Best practices: use imperative language ('Always use X', 'Never do Y'), organize with level-2 headings by topic, include code block examples for rules that might be ambiguous, and aim for 200-800 words. Shorter is better if the rules are clear. Avoid vague advice — every instruction should be specific enough that the AI can implement it unambiguously.
Common mistakes to avoid
1) Vague descriptions: 'Helps with React' tells the AI nothing — write 'Enforces functional components and custom hooks patterns for React codebases' instead. 2) Overloading one skill: a 2000-word SKILL.md trying to cover React, TypeScript, testing, and CI all at once will dilute each rule. Create separate focused skills. 3) Forgetting the version field: without versioning, teams cannot track when skill instructions changed or roll back breaking changes.