How to Create a Claude Code Skill Without Being a Developer
By Alexandre Saint-Jean
Audio version
Audio version produced by text-to-speech from the article. Our AI charter
A Claude Code skill is a set of instructions written in plain language, stored in a dedicated folder, that the agent invokes to apply a precise, repeatable procedure. No code to write: you describe a method once, and the agent reuses it every time the context matches. If "artifact", "skill" or "hook" still feel fuzzy, our full Claude Code glossary defines each one before you go further.
What is a skill, in practice?
A skill looks like an internal procedure sheet, but one the agent can read. Technically, it is one or more text files in markdown format, preceded by a short header that describes the skill's name and role. The body of the file holds the detailed instructions: the method to follow, the points to check, the expected output format.
What sets a skill apart from a simple message is its scope: it is not written for a single conversation, it is re-read automatically, session after session, whenever the matching task comes up. The agent consults it, applies the procedure, and produces a result consistent with the first time.
Why write a skill instead of retyping the same instructions?
Anyone who uses an AI agent regularly ends up retyping the same phrases: "check the tone before publishing", "structure this report into three parts", "cross-reference these two files in this specific way". Those repeated instructions are a signal: the task is stable, only its execution changes each time.
Turning that instruction into a skill avoids three common losses: forgetting a step when writing too fast, the result drifting as the prompt gets simplified session after session, and time lost retyping an explanation that was already fine-tuned. The skill captures the know-how once, for good.
How do you spot a task worth turning into a skill?
Three signs point to a good candidate. The task comes up at least once a week in an almost identical form. It follows a method you could explain to a new hire in a few minutes, with no grey areas. And the expected result has a recognisable shape (a template, a checklist, a report).
A pre-publication check, a meeting report template, a method for reviewing a quote before approval: these are natural candidates. A decision that requires case-by-case judgement, on the other hand, does not lend itself well to a skill.
How do you write a skill, step by step?
The process comes down to four simple moves, with no prior technical knowledge required.
- Name the task with a clear label ("pre-send check", "creative brief template").
- Describe in one sentence when the agent should use it: this description is what lets the agent recognise the right moment, so make it precise rather than vague.
- Write the procedure step by step, the way you would explain it to a colleague: the steps in order, the validation criteria, the mistakes to avoid.
- Test it by asking the agent to run the task, then adjust the text if the result drifts from what was expected.
As a simplified teaching example (the exact file syntax depends on the current version, check the official documentation when you set it up), a skill can look like this in its logic:
name: pre-publication-checklist
description: use before publishing a blog article
---
1. Check that the title answers a question.
2. Check that no figure appears without a source.
3. Read it aloud once to catch awkward, artificial-sounding phrasing.
This skeleton illustrates the principle (a header that identifies and describes, a body that details the method) without claiming to reproduce a guaranteed syntax.
How does this work in practice, tool by tool?
The good news: this is not a principle unique to Claude Code. The skill format (a folder with an instruction file and metadata) is an open standard published by Anthropic, and adopted as is by several major agentic environments. A skill written once can be reused across tools without adaptation.
On Claude (Claude Code / Claude Cowork)
Claude Code offers a packaged skills feature stored in dedicated folders, officially documented by Anthropic. Claude Cowork, Anthropic's collaborative workspace, relies on the same logic of reusable procedures shared across team members.
On ChatGPT / Codex
Codex, OpenAI's coding agent, adopts the same open SKILL.md format as Claude Code: an instruction folder invokable individually depending on the task, portable across tools. ChatGPT, on its side, offers custom instructions and project configurations that pre-set the agent's behaviour, a single-context-per-project logic closer to a persistent prompt than a packaged skill.
On Antigravity
Antigravity, Google's agentic development environment, also adopts the open SKILL.md format, stored in a dedicated folder at project level or globally on the machine. A skill written for Claude Code is invoked there in the same way.
What mistakes should you avoid when writing your first skill?
A description that is too vague is the most common mistake: if it does not specify when to use the skill, the agent will either fail to invoke it at the right moment or invoke it wrongly. A second mistake is mixing several procedures into a single skill: a short, focused skill per task works better.
Finally, a skill is never set in stone: correct it as soon as a result disappoints, rather than compensating by hand every time. It is a one-off investment that keeps paying off as long as the procedure stays relevant. To build these agentic working methods in a structured way, funded AI training for your team covers this kind of good practice in business.
Frequently asked questions
- Do you need to know how to code to create a Claude Code skill?
- No. A skill is structured plain-language text, not code. The only skill you need is the ability to clearly describe a procedure you already apply mentally: the steps, the order, the points to watch for. Formatting it (name, description) stays very simple.
- Where should a skill be stored so the agent finds it?
- In a dedicated folder, at project or account level, with a description precise enough for the agent to recognise when to invoke it. The exact file structure evolves between versions, so it is worth checking the current official documentation at the time you set it up rather than following a fixed syntax from memory.
- What is the difference between a skill and a prompt you retype every time?
- A retyped prompt depends on the user's memory and degrades through repeated copy-pasting. A skill is written once, stored, and the agent retrieves it itself as soon as it detects the right context. You gain consistency: the same procedure applies identically, even six months later.
- Can a skill replace a deeper technical integration?
- No, not for everything. A skill formalises a textual or methodological procedure. As soon as you need to read from or write to an ERP, a database or a complex business tool, you move beyond what a skill covers and into proper integration work.