Claude Code Skills in Production: What Breaks When Nobody Is Watching

A skill looks like the easiest thing in Claude Code. You make a folder, write a markdown file, and a procedure you used to paste by hand now has a name. Ten minutes of work, and it behaves perfectly the first time you try it.

Then you point a scheduled run at it and nothing happens.

I have seventeen skills on this machine. They sit behind fourteen launched products and a set of routines that run without me, and every one of the useful lessons arrived after the skill worked in a chat window and then failed somewhere I was not looking. The standard advice covers the first ten minutes very well. It stops right before the part that costs you a week.

Here is what a skill actually is, how I decide when to build one, and the four ways they break once nobody is watching.

What is a Claude Code skill?

A skill is a folder with an instruction file in it. The file has a short block of metadata at the top, usually a name and a description, and then plain markdown telling the agent how to do one job. The folder can carry scripts, reference documents, and templates alongside it.

The part that matters is how it loads. Agents read skills in stages, described plainly in the open Agent Skills standard: at startup the agent loads only the name and description of every skill, just enough to know one exists. The full body loads only when a task matches. Bundled scripts and reference files load later still, or not at all.

That three-stage loading is the entire reason skills are worth building. Instructions you keep in a project instruction file are always in context and always cost you tokens. A skill costs you roughly one line until the moment it is needed. I have a skill that produces a complete training package, repo and landing page and email sequence included. It is long. It costs me nothing on the days I am not building a training package.

When to build a skill instead of a subagent or an instruction file

Three places to put knowledge, and I got this wrong for months by defaulting to whichever one I had open.

A project instruction file holds facts. Pricing, brand rules, which branch a repo tracks, the things that are true whether or not anyone is doing a task right now. If I find myself writing numbered steps in one, that content is in the wrong place. I wrote up how I keep those files from drifting after they grew into procedures.

A skill holds a procedure. Anything with an order to it. Research the keyword, write the draft, generate the image, check the byte budget, publish, log the row. The Claude Code skills documentation makes the same call: build a skill when a section of your instruction file has become a procedure rather than a fact.

A subagent holds a context problem. Not knowledge, capacity. When a job would fill the main window with output I do not need, or when four jobs could run at once, that is a subagent, and it can be handed a skill to follow. I went through how I actually split work across agents in an earlier post.

The clean test: if the answer is a fact, write it down. If it is a recipe, make it a skill. If the problem is that one context window cannot hold the work, that is a subagent.

Why is my Claude Code skill not triggering?

Because the description is the trigger. Not the folder name, not the body, not how obviously relevant the skill is to what you just asked.

Only the name and description are loaded at startup, so that description is the entire basis on which the agent decides whether to open the file. Anthropic's own guidance for authoring skills is blunt about the direction of the error: Claude tends to undertrigger, meaning it skips skills that would have helped, and the fix is to write descriptions that are deliberately pushy about when to fire. Their skill-creator guidance recommends naming the trigger words outright rather than describing the skill's subject.

So a description that reads "generates blog hero images" gets skipped constantly. The one I actually use names the phrases a human types: hero image, featured image, social creative, ad creative, cheaper image generation. It reads like a list of search queries because that is functionally what it is.

Two limits worth knowing. The description text is truncated at 1,536 characters in the listing the agent sees, so everything decisive belongs in the first sentence. And precedence is real: a personal skill and a project skill with the same name are not merged, the personal one wins when you invoke it by name. I lost twenty minutes once to a project skill I had carefully edited and an older personal one that kept running instead.

The failure that only shows up on a schedule

This is the section I wish someone had written before I found it the hard way, because every symptom points at your skill and none of the causes are in it.

A personal skill does not exist in a cloud run. Scheduled routines and cloud sessions start as a fresh remote session. They do not read the skills folder in your home directory. If your skill lives only there, the run reports that the skill was not found, and the run itself looks fine right up until that line. The fix is to move the skill somewhere the remote session can see it, which in practice means committing it into the repository the run clones, or shipping it inside a plugin the repository declares.

A skill can be blocked from firing on a schedule by its own metadata. There is a setting that stops the model from invoking a skill on its own, meant for procedures you only ever want to trigger by hand. Since a Claude Code update earlier this year it also prevents the skill from running when a scheduled task fires with that skill as its prompt. Which is correct behaviour, and completely invisible if you set that flag months ago for a different reason.

Skills that live outside a repository are not backed up. My scheduled task files sit in a folder that no repo tracks. Version control has never seen them. I found this out during a machine reset, and the fix is unglamorous: they get copied out before anything gets reinstalled, and copied back after. If a piece of your automation is not inside a repo, it is not backed up, no matter how carefully you write it.

A skill that assumes a human is present will stall, not fail. This one is a writing problem rather than a configuration problem. Any instruction that reads "ask which repo to use" or "confirm before publishing" turns an unattended run into a run that sits there. Every skill of mine that runs unattended states its defaults instead of asking, and says what to do when a step fails: publish without the image and report it, rather than retry the image forever. A post that ships on time without a hero is a success. A run that stalls on the hero is not.

If you are building agent workflows you intend to leave running, this is the layer worth getting right, and it is most of what we work through together inside the Reinventing AI Accelerator.

One standards file, seven routines

The change that did the most for me was not writing better skills. It was writing fewer of them.

Five of my routines publish a blog post, and two more review search performance and refill the content calendar. All seven used to carry their own copy of the same rules: how to research the competition, that outbound authority links are mandatory, the image prompt constraints, what the end-of-run report has to contain. Seven copies of the same paragraph, and they drifted exactly the way you would expect. A rule got tightened in two of them. The other five kept doing it the old way for weeks.

Now those rules live in one standards skill, and all seven routines read it. Each routine keeps only what genuinely differs: its repo path, its branch, its post format, where its API key lives. The rule that makes this work is stated in the standards file itself, so there is no ambiguity when they disagree. Property-specific facts, the routine wins. Shared standards, the standards file wins.

The result is that a fix lands once. When I tightened the rule about hero image alt text being a keyword string rather than a description of the picture, I edited one file, and five blogs changed behaviour that night. I described the publishing loop those routines run separately, but the shared standard underneath it is the part that stopped the drift.

What I deliberately keep out of a skill

Keep the instruction file under about 500 lines. That number comes from Anthropic's authoring guidance and it is a real ceiling rather than a style preference. Past it, add a layer: keep the decisions in the main file and push the reference material into separate files it points at, so the agent loads them only when it needs them.

Never a secret. Not an API key, not a webhook URL, not a token. A skill file gets copied, zipped, shared, and committed. Mine resolve keys from the environment or from a local env file in a specific working directory, and they are written so the value never gets printed.

Nothing that changes weekly. Prices, dates, campaign names and current offers go in a file the skill reads, not in the skill. Anything you would have to remember to update in two places will eventually be right in one of them.

And no step that quietly caps the work. If a run only handles the first ten items, it has to say so. Silent truncation reads exactly like completeness, and you will not notice for a month.

Skills rot, and here is the loop that catches it

A skill is not finished when it works. It is finished when the next thing you learn about the job lands back in the file.

My rule is that a correction given in conversation has to be written into a file in that same session. If I tell an agent "never do that again" and only say it in chat, I will be saying it again in two weeks. That has happened to me with alt text, with renewal dates, and with source links, three separate times each, which is how the rule got made.

The practical version: when an unattended run discovers something procedural, that discovery does not belong in a note the next run will never read. It goes into the skill. My publishing routines say this explicitly, because I kept finding good observations buried in run notes while the same run repeated the same mistake a week later.

Start with the one job you keep redoing

Do not start by writing your best skill. Start with the procedure you have pasted into a chat three times this month. Write it exactly as you would explain it to someone competent who has never done it. Write the description last, and write it as the list of things a person would say when they want this to happen.

Then run it unattended once, on purpose, while you are watching. That single run tells you more than any amount of editing.

Get the working version

The session where I built a full prospecting method and packaged it as an installable Claude Code skill is available now. It covers finding a hosted platform's customers by the traces they leave in public, verifying them, and enriching them into contact routes. It produced 1,419 verified businesses with a contact route for 1,132 of them, using free tools only, and the failures are in there alongside the wins.

The full replay of that session is available instantly, along with the playbook, three working scripts, and the skill itself: watch the session on finding every business running the software you replace.

If you would rather have the whole library, the Reinventing AI Accelerator includes every past session and app, new live builds as they happen, and the apps, agents and tools that come out of them. One small ask: if you build a skill off the back of this, tell me what broke. That is the part I collect.

Frequently asked questions

Do Claude Code skills work in scheduled and cloud runs?

Yes, but not the ones in your personal skills folder. A scheduled routine starts as a fresh remote session and does not read the home directory on your machine, so a personal-only skill comes back as not found. Commit it into the repository the run clones, or ship it in a plugin the repository declares, and it loads normally.

What is the difference between a skill and a subagent?

A skill is knowledge, a subagent is capacity. A skill packages a procedure so any agent can follow it consistently. A subagent gives you a separate context window, which is what you want when the work would flood your main session or when several jobs should run at once. They compose: a subagent can be told to follow a skill.

Why does Claude ignore my skill?

Almost always the description. Only the name and description are in context at startup, so that text is the whole decision. Descriptions that describe the subject get skipped. Descriptions that name the phrases a person actually types get picked up. Put the decisive words in the first sentence, because the listing truncates at 1,536 characters.

How long should a skill file be?

Under roughly 500 lines. If it is longer, split it: decisions in the main file, reference material in separate files the main file points to. The whole benefit of the format is that heavy content stays on disk until it is needed, and a single enormous file throws that away.

Do skills work outside Claude Code?

The format is an open standard rather than a Claude Code feature, and a long list of agent tools now read it, including editors, terminal agents and cloud platforms. The core file works across them. Some fields are Claude Code extensions, so check what your target tool supports before relying on invocation control or tool permissions.