How to Write AI Skills That Actually Work (Not Just Look Good)
A practical guide to writing, auditing, and maintaining custom AI skills for Claude and ChatGPT, instead of collecting random ones off GitHub.
What is an AI skill, really?
A skill is a packaged set of instructions that an AI agent loads at a specific moment to complete a task, like a recipe it follows only when the job matches. Technically, it’s a directory containing a markdown file (often called SKILL.md) plus supporting material such as templates, scripts, or examples. Unlike an app on your phone, a skill doesn’t load all at once. The agent first sees only the name and description. It loads the full body of instructions only when the task at hand matches that description closely enough. That loading order is the whole game, and most people writing or installing skills don’t account for it.
TL;DR
- A skill is not an app you install and forget. It’s a layered set of instructions that an agent reads in stages: name and description first, full body only when invoked.
- Randomly grabbing skills from GitHub repos is risky because you don’t know if the source is trustworthy or how the skill interacts with your existing setup and tasks.
- Skills are written for two audiences at once. If a human can’t read and audit the file, you’ve lost control. If an agent can’t parse it efficiently, you get none of the benefit.
- A vague or overly broad description means the agent either never calls the skill or calls it constantly in the wrong contexts, which wastes context window and confuses output.
- A bloated main file with every edge case crammed in forces the agent to spend effort navigating the manual instead of doing the actual work.
- Good skills evolve through forking and modification, not blind installation. Taking someone else’s skill and adjusting it to your workflow is normal and often necessary.
- Talking through your goals out loud, using voice input or dictation, is an effective way to surface the implicit judgment you want a skill to encode before you write it down.
Remy doesn't build the plumbing. It inherits it.
Other agents wire up auth, databases, models, and integrations from scratch every time you ask them to build something.
Remy ships with all of it from MindStudio — so every cycle goes into the app you actually want.
Why does randomly installing skills backfire?
Treating skills like collectible cards, grabbing whatever looks impressive in a demo and stuffing it into your setup, creates two distinct problems.
First, there’s a trust problem. A skill you didn’t write and don’t fully understand could contain instructions that behave in ways you didn’t intend, including genuinely malicious ones. You’re accepting someone else’s decisions about what “done” means for a task, what shortcuts are acceptable, and what tools get used, often without reading the fine print.
Second, there’s a compatibility problem. Skills don’t exist in isolation. A new skill has to coexist with whatever else is already loaded, and with the actual task you’re trying to accomplish. A skill that looked great in someone else’s demo video can fail silently in your setup because the description doesn’t match how you phrase requests, or because it conflicts with other instructions your agent already has.
The result is that installation succeeds at the file-system level (the skill is there, it’s technically loaded) while being functionally useless. You added something, but nothing changed about how your AI performs.
How do agents actually load and use a skill?
Understanding the loading mechanism explains almost every failure mode in bad skill writing.
When an agent is deciding what to do, it first scans available skills by their name and description only, not their full contents. This is a lightweight lookup, not a full read. Only when a task matches a skill’s description closely does the agent load the complete instruction set, and only then does it reach into supporting files like templates or scripts if the instructions point there.
This staged loading is actually an advantage over pasting a giant prompt into every conversation. It means the agent isn’t carrying every possible instruction in its “head” for every single exchange. But it also means the description is doing critical work. If it’s too vague, the agent never recognizes when to use the skill. If it’s too broad, the skill fires in contexts where it doesn’t belong, eating up context window space it didn’t need to use.
The main instruction file has its own failure mode: if it tries to cover every conceivable edge case, the agent spends its effort parsing a manual instead of executing the task. A skill file bloated with exhaustive detail is often worse than a short, clear one.
Who is a skill actually written for?
This is the core confusion driving most bad skills: they’re written for an unfocused audience somewhere between “human” and “agent,” without anyone deciding which.
A skill needs to work for both, deliberately. It has to be readable by a human, because if you can’t open the file and understand what judgment or business logic you’ve handed to your AI, you’ve lost the ability to audit your own system. That matters more as skills increasingly encode real decisions, tone, formatting preferences, acceptable shortcuts, definitions of “done.”
At the same time, it has to be usable by an agent, which means the front matter (the name and description an agent scans first) needs to be precise enough to trigger at the right moments and skip the wrong ones. The body needs enough examples to be useful without so many that it becomes a maze.
Writing for both audiences simultaneously is a skill in itself, and it’s the piece most people skip. They either write something so terse an agent can barely act on it, or so exhaustive a human would need an hour to review it and an agent burns unnecessary attention parsing it.
Should you fork existing skills instead of writing from scratch?
Often, yes. Reusable skills from trusted sources are genuinely valuable. Matt Pocock’s publicly shared skills, including one nicknamed “Grill Me” that interrogates a plan until it’s actually thought through, are a good example of a skill that’s compact (a handful of body sentences), easy to read, easy to understand the job of, and easy to try in minutes.
But most of the time you won’t find something that fits your exact workflow untouched. A commonly cited pattern: a smaller share of skills you use will come straight from a trusted source unmodified, while the majority will need adaptation, either forked from someone else’s version or built from scratch around your own judgment.
Forking is legitimate and expected. One documented example: a creator took Matt Pocock’s “Grill Me” skill and modified it so the resulting output was persistent and inspectable after a single round of questioning, rather than requiring repeated interrogation each time. The core loop stayed, but the goal shifted to fit a different downstream need. That’s the normal lifecycle of a skill: not a fixed artifact, but something that gets rebuilt as your requirements change.
What does a good skill-writing process actually look like?
Start by being honest about why you want a skill at all. If the answer is “it looked cool in a demo,” that’s a weak reason. The stronger approach is to identify a specific, repeated task where you keep giving your AI the same implicit instructions over and over, and turn that repeated judgment into a written recipe.
A practical method for surfacing that judgment: talk it out. Voice input, whether through a live voice feature in a chat app or a separate dictation tool, tends to produce more complete, natural descriptions of what you actually want than typing does. People often articulate goals more freely out loud, including quirks and preferences that are hard to write down cold (a specific formatting habit, a tone preference, a structure that only makes sense once you’ve explained the reasoning behind it).
From there, the job is translation: taking that unstructured rant and converting it into a skill file with a tight, accurate description (the part the agent scans first), a body with enough examples to be clear but not so many it becomes bloated, and a structure a human can open and audit line by line.
If you already maintain a stack of skills, dig back into it periodically. Check which ones actually get triggered, which ones you can’t fully explain anymore, and which ones were installed once out of curiosity and never verified. Treat it as ongoing maintenance, not a one-time collection.
Frequently Asked Questions
Built like a system. Not vibe-coded.
Remy manages the project — every layer architected, not stitched together at the last second.
What’s the difference between a skill and a regular prompt?
A prompt is instructions you type fresh each time. A skill is saved, reusable, and loaded conditionally: the agent only pulls in the full instructions when a task matches the skill’s description, rather than carrying that context in every conversation.
Is it safe to download skills from GitHub?
Only from sources you trust. A skill is a set of instructions your AI will follow, potentially including business logic or shortcuts you didn’t review. Unverified skills can behave unpredictably or contain instructions you wouldn’t have approved.
Why does a skill’s description matter so much?
The agent scans the name and description before deciding whether to load the full skill. A vague description means the agent never calls it. A too-broad one means it fires in unrelated tasks and consumes context window space unnecessarily.
How long should a skill’s main file be?
Long enough to be clear, short enough to be scanned quickly. Skills with a handful of clear body sentences and a couple of solid examples tend to work better than files that try to cover every edge case, since bloated files force the agent to spend effort navigating the manual instead of doing the task.
Should I modify skills I download, or use them as-is?
Expect to modify most of them. A small portion of skills from a highly trusted source might work unchanged, but most tasks are specific enough to your workflow that forking or rewriting is normal, not a failure.
