Claude Skills (SKILL.md): Make Your Workflow Portable

Claude Skills (SKILL.md): Make Your Workflow Portable

Hi there.
If you search for Claude skills, you will find a lot about the SKILL.md file format.
I'm not a developer, and I use that format to keep my work procedures out of any single AI tool.
Here is how my setup looks, what I check, and what still only works in Claude Code.

A checklist document turning into one SKILL.md file card that connects to two different laptop windows

Why I stopped writing procedures into chats

Early on, I explained each job to the AI again in every new chat.
It worked, but the explanation lived in one conversation and disappeared with it.
I wanted the steps stored in files I own, so I could hand the same steps to a different tool later.

A person typing on a laptop that is running AI software

Photo: Matheus Bertelli on Pexels

What a skill file looks like

A skill is one folder with one file named SKILL.md.
I follow the open skills format (agentskills.io/specification).
The top of the file holds a name and a description, and the body holds the steps.

A single file card opened to show three stacked sections: Name, Description and Steps

A few rules I keep:

  • The name uses lowercase letters, numbers and hyphens, and matches the folder name.
  • The description says when the skill should be used, because that is what the assistant reads to decide.
  • I add a version and an updated date, so I can see what changed and when.
  • Most of my skills begin by pointing to one shared rules skill, so I don't repeat the same rules in each file.

I have 20 skills now, one per recurring job such as writing, reviewing, publishing and image prompts.
My checker script reports "20 skills, 0 errors, 0 warnings" after every change.

A computer screen showing a chat interface in a dark room

Photo: Matheus Bertelli on Pexels

The four rules that make it portable

  1. Procedures live in SKILL.md files, not in a tool's settings.
  2. Memory lives in plain Markdown and JSON files in the project folder.
  3. My small web app never calls an AI tool. It only reads and writes local files.
  4. Anything that works only in Claude Code goes on a written list.

That list matters most.
Right now it names things like the project instructions file that Claude Code reads automatically, helper agents, and the shortcut folder that lets Claude Code find the skills folder.
For each item, the list says what to do in another tool instead.

Using the same skills in Codex

I pointed Codex at the same project folder, with a short instructions file that sends it to the same rules.
That is the setup I describe in I Switched From Claude Code to Codex: The Project Files That Preserved Context.

The skills themselves are plain files, so the content moves from one tool to another.

Wrap-up

  • Keep repeatable procedures in SKILL.md files you own.
  • Write a clear description, add a version, and run a checker after each edit.
  • List the Claude-only features so a move to another tool is a checklist, not a rescue.

Which job would you turn into a skill first?
Tell me in the comments, and I'll try writing about it.

Related post:

Thanks for reading.

Comments

Popular posts from this blog

Claude Code on Windows for Non-Developers: 6 Snags I Hit and How I Got Past Them

Day One With an AI Agent Team: 6 Things That Broke (and the Fixes)

Updating 20 Live Blogger Posts at Once Without Changing a Single URL