Defining AI Specialist Tasks with SKILL.md: How Skill Design Improves Reproducibility
The problem of repeating the same instructions
Repeating a task’s procedure, constraints, and output format in every AI request creates room for omissions and inconsistent interpretation. I introduced skill files (SKILL.md) to make those instructions reusable.
This article covers general principles for defining a skill’s scope, procedure, and prohibitions. I keep the blog-specific application in Configuring an AI Blog Writer.
What a skill file is
A skill file is a Markdown file that defines a specific task: what to do, in what order, with what constraints, and in what output format.
Using a cooking analogy: instead of explaining “add a teaspoon of salt, then crack the eggs…” aloud every time you cook, you write one recipe card. With the recipe card available, you can follow the same steps every time without explaining from scratch.
The same applies to AI. When AI is configured to refer to a skill file, it follows the predefined procedure without needing a full explanation in every conversation.
Examples of skills I built for this site
Here are a few skill files I actually integrated into the harness for this site.
Blog writing skill (my-blog-writing/SKILL.md)
This defines the author voice rules (formal register, no exaggeration, first-person constraints), the article writing procedure (write Japanese first, then translate to English), how to write frontmatter, and the reference citation format when citing external sources. Referencing this skill means I no longer need to re-explain style and structure rules for every article.
Content editorial review skill (editorial-review/SKILL.md)
This defines the checklist of items to verify before publishing an article, along with the criteria for classifying issues as Critical (publication blocked) or Recommended (suggested fix).
Documentation writing skill (docs-content/SKILL.md)
This defines the structural rules for documentation pages, including quiz requirements, heading hierarchy, and whether to include audience description blocks.
The difference between ad hoc instructions and skill definitions
Ad hoc instructions are only active for the conversation in which they are given. When the conversation changes, they reset. Skill files exist as files in the repository, so they can be referenced in the next conversation as well.
Skill files can also be shared across contributors. When multiple people are asking AI for help, pointing everyone to the same skill file makes it easier to maintain consistent quality even as contributors change.
What to decide when designing a skill
When I create a skill file, I start by clarifying three things.
- What task does this cover: Make the scope explicit (“write a blog post for this site in the author voice” rather than “write something”).
- What are the steps: List the procedure in concrete terms.
- What is prohibited: Call out the choices where AI tends to go wrong.
Skills with too broad a scope produce less reproducible results. Narrowing the task scope — from “writing in general” to “writing a blog post for this specific site” — leads to more stable output.
Summary
SKILL.md is a mechanism for defining repeat instructions to AI as a file so they can be reused. Moving the content of per-conversation instructions into skill files improves reproducibility and reduces the quality variance that comes from leaving things out.
As a next step, it becomes necessary to periodically check that existing skill files match the actual code and configuration — a process called drift detection, which I cover in a separate article.