A good skill is small, specific, and triggers on the right tasks. Here's the workflow — agent-agnostic, so the result works across Hermes, Cursor, Codex, Gemini CLI, OpenCode, Claude Code and more.
The best skills do one thing well. "Generate Conventional Commit messages" is a skill; "help with git" is a category. A tight scope makes the description easy to write and the triggering reliable.
---
name: conventional-commits
description: Write Conventional Commits messages from a staged git diff.
Use when the user is committing code or asks for a commit message.
license: MIT
---State what it does and when to use it. The agent matches the user's task against this text, so be concrete. See the frontmatter reference for every field.
Speak to the agent. Short sections, numbered steps, concrete examples. Cut anything the model already knows — you're adding your conventions, not a tutorial. Because some agents read only the body (not the frontmatter), make the body self-contained.
Drop helper scripts in scripts/ and longer docs in references/. Reference them from the SKILL.md by relative path; the agent loads them on demand. Keep the SKILL.md itself lean — point to references rather than inlining everything.
Install it (see the install guide) and try the tasks it should fire on — and a few it shouldn't. If it doesn't load when expected, tighten the description. If it loads too eagerly, narrow it.
Avoid hard-coding one agent's tool names or paths in the instructions. If a step needs a specific tool, describe the goal ("run the test suite") so any agent can satisfy it. Portable skills reach the widest audience across the 40+ compatible clients.