Stop Writing Prompts. Start Writing Skills.

A few months ago an image generation step in my blog pipeline failed with SSL: CERTIFICATE_VERIFY_FAILED. Homebrew Python on macOS refuses to trust the certificate chain for fal.run, the API I use to render hero images. I debugged it, found that curl works fine because it uses the system trust store and moved on. Here is the interesting part: I have never hit that error again, and I never will, because the fix is written into a skill file with the date I verified it, right next to the working payload shape and the retry rule.

If I were still running that workflow from a pasted prompt, I would have re-hit that wall on a fresh chat, re-debugged it or watched the model flail at it, and lost the fix again when the session ended. That is the difference this post is about. Most developers I talk to still manage AI work as a folder of prompts, or worse, a chat history they scroll back through. Every run starts from zero. Every lesson learned evaporates at the end of the session.

In the past year this stopped being a personal workflow preference and became an industry standard with a file format, a published spec and more than thirty tools that read it. If you are still re-pasting prompts, you are hand-rolling something the ecosystem has already turned into infrastructure. Here is the argument for making the switch, and the concrete steps to do it this week.

---

The moment a prompt stopped being enough

The fal.ai story is worth spelling out because it shows the exact failure mode. The task was simple: POST a JSON payload to an image endpoint, download the result. My first implementation used Python's urllib, which died on the SSL handshake. The fix, switching to curl, took twenty minutes of debugging to find.

A prompt has nowhere to put that twenty minutes. You cannot append a debugging outcome to a sentence you paste into a chat box. So the knowledge lives in your head until it fades, or in a notes file nobody reads, and six weeks later you or your agent burns the same twenty minutes again.

A skill file has exactly the right place for it. Mine now contains the line "use curl, not Python urllib, verified 2026-05-12" plus the working request shape, the timeout, the retry rule and the instruction to stop and report on any other failure. Every fact I learn while running the workflow gets written back into the workflow. The file is where lessons stop evaporating.

A prompt is a snippet. A skill is a function.

Strip away the AI framing and this is a software engineering question we settled decades ago.

A pasted prompt is a copied code snippet. It has no version, no interface and no single source of truth. Each paste drifts a little: you tweak a word, forget a constraint, reorder an instruction. Ten pastes later you have ten divergent copies of your process and no idea which one produced the good output.

A skill is a function. It has a name. It has a contract: a description that tells the agent what the skill does and when to call it. The body encodes the steps. Files it references are its imports. You call it, you do not retype it.

The practical consequence is that consistency stops depending on your discipline on a given afternoon and becomes a property of the system. My blog posts, LinkedIn posts and outreach emails read like one person wrote them because they run through skills that share the same hard rules. I wrote about the full setup in How I Automated My Content and Outreach Pipeline with Custom Claude Code Skills; this post is about why that shape of working beats prompts in general, not just for content.

The industry agreed and gave it a file format

For a while "write your workflows down for the agent" was folk practice. Then it got a spec.

Anthropic shipped Agent Skills in Claude Code in October 2025 and published the format as an open standard at agentskills.io in December 2025. Microsoft added support to VS Code and OpenAI added it to Codex within days. By spring 2026, tools from Google, JetBrains, AWS and Block were reading the same files, and the showcase at agentskills.io lists dozens of compatible products. The New Stack called it Anthropic's next bid to define AI standards, and the comparison is apt: this is the MCP playbook repeated, a vendor format turned neutral standard.

The spec itself is small enough to learn over coffee:

• A skill is a directory with a required SKILL.md file.
• SKILL.md starts with YAML frontmatter: a required name (lowercase, hyphens, must match the directory) and a required description of up to 1024 characters.
• The description is the routing contract. It should say what the skill does and when to use it, because that is what the agent reads when deciding whether to load it.
• The Markdown body holds the instructions. Optional scripts/, references/ and assets/ directories hold executable code, documentation and templates.

That is the whole format. The barrier to entry is a text file, which is exactly why adoption moved so fast.

Progressive disclosure is just lazy loading

The design idea underneath the spec will feel familiar to any frontend developer: it is lazy loading for context.

Skills load in three layers. The metadata, roughly a hundred tokens of name and description, is always resident, like a route table. The full SKILL.md body loads only when the agent decides the skill applies. Referenced files load only when a specific step needs them. Anthropic's engineering write-up frames this as the reason a skill's total size is effectively unbounded: the agent reads what the task requires and nothing more. The spec's practical guidance follows from it: keep SKILL.md under 500 lines and push detail into reference files.

This layering is also what makes real code reuse possible. Six of my content skills enforce the same list of banned words, and none of them contain the list. They all reference one file. When I add a word to the blocklist, every channel inherits the change immediately. That is a shared module, and it only works because skills can reference files instead of inlining everything the way a prompt must.

One skills directory, three agents

Here is the part that changed how I think about the investment. A sync script on my machine symlinks one skills directory into three different runtimes: Claude Code, GitHub Copilot CLI and opencode. Same SKILL.md files, three agents, zero duplication.

Nobody knows which coding agent wins the next two years. Prompts typed into one tool's chat box are stranded there, unversioned and unexportable. Skills are the layer above that bet. The workflow knowledge lives in plain files I control, in git if I want, and whichever agent I point at them can execute them. I made a smaller version of this argument when I moved my agent configuration to a portable format in Why I Switched from CLAUDE.md to AGENTS.md; skills complete the thought. Configuration told the agent who I am. Skills tell it how I work.

What 490,000 marketplace skills won't do for you

The standard's success produced a predictable side effect: marketplaces. By March 2026 the big registries reportedly listed close to half a million skills between them, per the Agentman ecosystem report.

Most of them are worth nothing to you. A generic "handle PDFs" skill downloaded from a registry gives you the same output it gives everyone else, which is another flavor of the commodity problem. The skills that earn their place encode workflows you have personally verified: your API sequences, your voice rules, your gotchas with dates on them. "Use curl, urllib fails on macOS, verified 2026-05-12" is an asset. Nobody can download that line, because it is the residue of work only I did.

Two honest caveats belong here. First, a skill is instructions plus, optionally, executable code that you hand to an agent with real permissions on your machine. Read third-party skills before installing them, the same way you would read a shell script from a stranger. Second, my own count is modest: sixteen skills installed, ten of which I wrote myself, and those ten do all the heavy lifting. Quality of encoding beats quantity of downloads.

How to migrate this week

The migration is smaller than it sounds. You do not need a framework, an account or a build step.

1. Audit your chat history. Find the prompts you have pasted more than twice. Those are your candidates, and most people have about five.
2. Pick one and write the smallest possible SKILL.md. A name, a description that says when to use it and the steps written the way you would explain them to a new hire. Done is better than elegant.
3. Write rules as constraints, not suggestions. "Never publish without confirmation" holds up. "Try to check with me" does not.
4. Add a "verified on" line every time you debug something. This is the habit that compounds. Each fix you write back into the file is a fix you never make again.
5. Keep SKILL.md under 500 lines and split anything bigger into referenced files. Then validate with the spec's skills-ref validate tool and point your other agents at the same directory.

Your first skill will be mediocre, like the first draft of any function. The difference from a prompt is that it persists, so every improvement sticks.

Conclusion: one of these compounds

Prompt engineering optimized the sentence. Skill writing versions the workflow. A better-phrased prompt gives you a better Tuesday; a skill file that accumulates your debugging history, your hard rules and your verified API recipes gets more valuable every week you use it. One of these compounds and the other one evaporates, and the whole industry, from the spec authors to the thirty-plus tools reading the format, has already picked a side.

I build and iterate on skills like these in the open inside my Skool community, The Agentic Architect AI Lab, alongside other developers wiring agents into real production work. If you want to see actual skill files, trade approaches and get feedback on your first migration, join us there.

Sources

• Agent Skills specification
• Equipping agents for the real world with Agent Skills, Anthropic Engineering
• Effective context engineering for AI agents, Anthropic Engineering
• Agent Skills: Anthropic's Next Bid to Define AI Standards, The New Stack
• Anthropic Opens Agent Skills Standard, Unite.AI
• The Agent Skills Ecosystem in 2026, Agentman
• Agent Skills: From Claude to Open Standard, Laurent Kempé