What Is SKILL.md? Standardizing Repeatable AI Work
What you’ll learn
- How SKILL.md standardizes recurring specialist work
- The difference between one-time requests, general instructions, and procedures that belong in a Skill
- How to define a Skill’s scope, inputs, steps, output, and verification conditions
Standardize Repeated AI Work in SKILL.md
SKILL.md is an instruction file that gives AI the scope, procedures, constraints, output, and verification conditions for recurring specialist work. On this site, moving repeated procedures out of conversations reduced missing premises and checks. One-time requests and policy that applies to every task remain separate.
By the end of this article, you will have practical criteria for answering “Which instructions belong in SKILL.md, and which should remain one-time requests?” in your own context.
Package Recurring Specialist Work in SKILL.md
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 Using AI to Support Blog Drafting.
SKILL.md Makes Procedures, Constraints, and Output Formats Reusable
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.
In this article, SKILL.md refers to the task-definition files I use inside this site. It may differ from official feature names and loading behavior in tools such as Claude Code Skills, Codex Skills, or GitHub Copilot-related skill systems.
A curry recipe provides a useful analogy. A list of ingredients alone will not produce a consistent dish. Recording the quantities, preparation, order, heat, and checks for doneness reduces variation when a different person cooks it.
In this analogy, the ingredients are the input, the cooking method is the procedure, unavailable ingredients or equipment are constraints, the finished curry is the deliverable, and tasting is the verification step. A Skill can therefore be understood as a portable work recipe: it turns craft knowledge and tacit knowledge that once lived in one person’s head into instructions that another person or an AI can consult.
The analogy has a limit. A recipe cannot remove differences in ingredients or equipment, and a Skill cannot guarantee an identical result. It reduces variation in repeated work when combined with the actual input, operating environment, and human review.
This Site Separates Writing, Review, and Documentation Skills
Here are a few skill files I actually integrated into the harness (the set of rules, procedures, and validation that guides AI work in a project) for this site.
Blog writing skill (my-blog-writing/SKILL.md)
The blog-writing skill 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 (the metadata at the top of a Markdown article, such as title, description, and date), 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)
The editorial-review skill 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)
The documentation skill defines the structural rules for documentation pages, including quiz requirements, heading hierarchy, and whether to include audience description blocks.
Ad Hoc Instructions Are Temporary; Skill Definitions Carry into Later Work
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.
Define Trigger Conditions, Procedure, Deliverable, and Verification for 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: Keep Only Recurring Specialist Work in SKILL.md
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.
Start with one recurring task and write down its scope, input, steps, output, and verification conditions. Do not pack one-time requests or policy that applies to every task into a Skill; keep those in the conversation or shared rules.