What task actually needs a SKILL.md?

Three questions to help you avoid skill creep

Image generated by gamma.ai

---

I deleted most of the automations in my knowledge base this week, unable to tell which skill had run or whether two had stepped on each other. What survived passed one test: a clear goal, tight parameters, and a job I actually hate doing by hand. That’s what became the three-skill pipeline I now run to finish every Substack draft.

---

I deleted three skills this week.

Honestly, I kept tripping over them. One might contradict another, or one might work against what I’m doing manually.

For skills to really be useful, you have to be able to track your them, understand how they work together, and verify they are working as intended.

Sometimes a trigger might fire when I don’t want it to, or I forget to pull the trigger myself.

Each individual skill looks good on its own, but the more skills you have, the more work that is ... even if you have an agent keeping an eye on things.

I’d been building toward more automation for months in my local markdown knowledge base, on the assumption that more coverage meant a better system.

But as things grow, the system becomes less trustworthy, especially as solo “manager.”

I’d started double-checking outputs I used to take for granted, because I could no longer be sure which skill had actually run, or whether two of them had stepped on each other without my noticing.

So this week I went the other direction. I opened the folder and started asking, one skill at a time, whether I’d actually miss it. The answer was no for many.

What’s left is smaller and works better.

What actually needs governing

Skills don’t fail the way scripts do. A script breaks and you get an error log. A skill misfires without any error, or doesn’t fire at all, and you don’t find out until later (if you find out at all.)

This is really what the Hugging Face incident was about, but at scale. The developers lost control of the agents, because they weren’t or couldn’t watch them.

I have a pipeline of skills that keep my knowledge base and Blue, the project tracker I schedule this newsletter through, in sync. In practice, I kept forgetting to trigger them, so the two drifted.

Then when I finally ran the sync, it had a backlog to work through and the output got confusing — too much happening in one pass.

Cards also kept showing up in Blue with “LinkedIn” tacked onto the title, no matter how many times I edited the skill that was supposed to control titling.

At first that made sense — an old version of the skill was still in play, taking precedence over what I’d just rewritten. So I cleaned that up. It kept happening anyway.

That’s when I realized the actual problem wasn’t a bug in one skill. It was that too many things had a say in the same decision — a skill, a folder-level AGENT doc, and whatever the AI was inferring from the existing structure of the workspace itself.

(An AGENT doc is usually a file named AGENTS.md or similar — standing context an AI agent reads automatically whenever it works in a given folder or project, separate from any skill you invoke by name.)

Three sources of truth, occasionally agreeing, occasionally not, and no way to tell from the outside which one had won on a given run.

The fix wasn’t a better skill. It was moving the title preference out of a skill entirely and into the AGENT doc that already loads whenever the AI works in that folder — because the AI could already deduce most of how to use Blue just from the structure I’d built into it.

A skill should be for a job that needs real instructions. A stable preference like a title format doesn’t need a skill watching over it forever; it needs to live where the AI already looks, once.

This requires being judicious about what becomes a skill, what becomes an AGENT doc, and what the structure of the workspace can already carry on its own without either one.

Judging a skill by what it does, not how much it covers

Once I’d cleared out the folder, the skills left standing were the ones doing a job with a clear goal, rigid parameters, and something I actually hated doing by hand.

That third piece is the one that’s probably my most valuable. Adding a skill for something I don’t mind doing creates more opportunity for drift, whereas a skill that automates something I never do, because it’s tedious or I keep forgetting it, is definitely worth the maintenance cost.

Clear goals and rigid parameters do the rest of the work.

A skill with an unclear goal starts making judgment calls nobody asked it to make — the same failure mode as the AGENT doc problem, just inside a single file instead of across three of them.

A skill with loose parameters runs when you didn’t want it to, on inputs you didn’t intend.

So I started asking three key questions:

• Do I know exactly what this is supposed to produce?

• Are the conditions for running it specific enough that it won’t fire on the wrong job?

• And is this a task I’d pay real friction to avoid doing myself?

If the answer to any of those is no, the skill isn’t ready — or shouldn’t exist at all.

The case study I actually built

There are a lot of things one does when you finish a draft for publication, even for more informal spaces like Substack. It’s also probably a collection of my least favorite tasks.

So these skills I’m keeping ... and I intentionally keep them as separate skills, not just one big one.

finalize-substack-draft runs a link pass.

It searches my own back-catalog for essays and LinkedIn posts worth backlinking, checks a running reference file for affiliate and referral links that fit, and flags named tools, books, and sources worth linking to.

substack-summary-seo does the opposite kind of job. It writes directly into the file: a visible summary at the top, in italics between horizontal rules, and an SEO description into the frontmatter.

And finally, gamma-featured-image-prompt writes one paste-ready prompt for the post’s feed image, tied to the actual title or hook, in the newsletter’s flat-line brand style, legible at thumbnail size. It doesn’t generate the image. I still run the prompt in Gamma myself and pick the result (affiliate link, appreciate it if you use it).

It might seem counter-intuitive. I just created or kept three skills instead of one. But if a skill has clear parameters, it does not add to the bloat.

This still relies on me to trigger these. Since the tasks are clear, it’s not as hard to remember, but I also created an orchestrator skill to manage clusters of specific skills like this.

For example, my revise skill runs three skills in order. Before it does anything, it analyzes for specific rhetorical patterns that I like to revise and only triggers the revision skill if that analysis passes a certain threshold.

So I decided to also create an orchestrator for the “finishing” tasks, in the same information-typed format I use for everything in the public Structured Skills Library:

---
name: finishing-skill
---

<!-- CONCEPT -->

## Concept

The finishing pass on a Substack draft isn't one job, it's three: find link opportunities, write the summary and SEO metadata, and generate a featured-image prompt. Each produces a different kind of output — a report to decide on, a finished artifact written straight to the file, and a prompt to run in a different tool entirely — so they stay three skills instead of one. This skill is the thin connector that runs them in order and hands back one combined set of results. It holds no linking logic, no SEO-writing rules, and no image-prompt conventions of its own — each of those lives in its own skill, loaded only when that step actually runs.

<!-- REFERENCE -->

## Reference

The three stages, in order:

| Order | Skill | Input | Output |
|---|---|---|---|
| 1 | finalize-substack-draft | the draft | a report of link candidates — backlinks, affiliate links, named sources |
| 2 | substack-summary-seo | the draft | writes a visible summary and frontmatter SEO description directly into the file |
| 3 | gamma-featured-image-prompt | the post's title/hook | one paste-ready Gamma prompt for the feed image |

<!-- PRINCIPLE -->

## Principle

- Run in this order and no other. Link candidates and the SEO summary both benefit from a draft that's otherwise settled; the image prompt only needs the title or hook, so it can run last without waiting on anything upstream.
- Never auto-apply a link candidate. Stage 1 produces a list; a person decides what actually gets added. Only stage 2 is allowed to write into the draft directly, because it isn't making an editorial judgment call — it's generating metadata from what's already there.
- Don't merge these into one instruction set. Each stage has its own reference file (a link taxonomy, an SEO style guide, a brand palette) that only needs to load when that stage runs. Combining them means every run pays the context cost of all three.
- This skill doesn't judge whether the draft is ready to publish. That call stays outside it, same as the rest of the pipeline.

<!-- PROCESS -->

## Process

This produces a bundle of pass-along outputs, not a single artifact — a link report, a modified file, and a prompt to paste elsewhere. Nothing here decides publish-readiness or applies edits beyond what stage 2 already does on its own.

<!-- TASK -->

## Task

1. Run finalize-substack-draft on the draft. Keep the report of link candidates — do not add any of them yet.
2. Run substack-summary-seo on the same draft. It writes the visible summary and SEO description directly into the file.
3. Run gamma-featured-image-prompt using the post's title or hook. Keep the returned prompt as-is; do not run it against an image generator.
4. Hand back all three outputs together: the link candidates (for a human decision), confirmation that the summary/SEO was written, and the image prompt (for the writer to run in Gamma).

The skills this one calls live in the public library too, for paid subscribers who want to see how they’re actually written.

Building a system that lasts

This is why I don’t automate many things, and when I do, the workflow is clear and detailed with a clear goal and tight parameters ... and it has to be something truly valuable (and honestly, worth the risk).

I don’t want to scale simply by adding more. I want to scale by being willing to take things away, and by being honest about which piece of a system actually needs a skill watching over it and which piece just needs a place to live.

That’s what it means to be intentional about AI ... and it takes a lot of work. More work than many would like to admit, I think.