Start with one workflow
The first rule of writing a SKILL.md is to pick exactly one workflow. A skill that does a single job well beats a skill that tries to do five jobs adequately. Before you write a line, finish this sentence out loud: "This skill helps the agent do ___ when ___." If you cannot, the scope is too fuzzy.
Choose something you actually do often and understand deeply. Your tacit knowledge — the order of steps, the easy mistakes — is the real value you are packaging.
Write the description first
The metadata at the top of the file includes a description, and it deserves more care than people give it. This description is how the agent decides whether to load your skill. Write it as a clear trigger, not a marketing line.
A weak description says "helps with code." A strong one says "use when reviewing a pull request diff for correctness bugs and style issues, before approval." The strong version tells the agent precisely when to reach for the skill and, by implication, when not to. Name the situation, the input, and the goal.
Lay out the steps like a runbook
The body of SKILL.md is where you teach the workflow. Write it as an ordered, concrete procedure. Favor imperative sentences: "Read the diff." "List each changed file." "Flag any function over fifty lines." Vague guidance produces vague behavior.
A few habits that pay off:
- Put the most common path first and edge cases later.
- State the expected output format explicitly so results are consistent.
- Include the checks people forget — the validation step, the naming convention.
- Add a short "when not to use this" note so the skill stays in its lane.
Use supporting files for depth
Keep the main file readable. If your workflow has long reference material — a style guide, a list of error codes, a template — put it in a separate file in the skill folder and point to it. The agent can open that material only when the task needs it. This keeps SKILL.md lean while still giving the agent depth on demand.
Be honest about scripts and access
If your skill calls a helper script, touches the network, or needs credentials, say so plainly and keep it minimal. Reviewers and users will look for exactly this. A skill that quietly runs an opaque script is a skill people will refuse to install, and rightly so. Prefer the smallest amount of automation that gets the job done, and explain what each piece does.
Test it on real tasks
Before you ship, run the skill against several real cases, including a messy one. Watch where the agent hesitates or guesses. Each hesitation is a missing instruction. Tighten the wording, re-run, and repeat until the behavior is steady.
Match the bar reviewers use
Curated directories judge skills on trigger clarity, focus, documentation quality, portability, and risk. Writing toward that bar from the start saves rework. The criteria are spelled out in how to evaluate agent skills. For inspiration, study examples in the development category and compare their source files.
Keep the main file lean
A frequent beginner mistake is to pour everything into SKILL.md — every edge case, every reference table, every long example. The result is a file so dense the agent loses the thread of the core workflow. Resist it. The main file should read like a clear summary a busy colleague could follow. Move depth into supporting files and reference them, so the agent pulls in detail only when a step actually needs it. A lean main file is easier for the agent to follow and easier for a human to review before installing.
Make it portable
If you want others to use your skill, avoid baking in assumptions about your particular setup. Hard-coded paths, a dependency on one obscure tool, or an unstated assumption about the environment all make a skill fragile in someone else's project. Where you must depend on something specific, say so plainly near the top so a reader knows the prerequisites before they commit. The more your skill leans only on capabilities most agents already have, the more cleanly it travels — and the more likely it is to be installed and kept.
Document the boundaries
Finally, tell readers what the skill does not do. A short note on its limits and on situations where it should be avoided prevents misuse and builds trust. It signals that you understand the workflow well enough to know its edges, which is exactly the signal a careful reviewer is looking for.