Building and Debugging a Post Creator Skill

I added a skill to this repo today whose entire job is creating one file. It took three failed attempts to get it working, and the failures were more interesting than the skill.

What a skill actually is

A skill is a markdown file with frontmatter. That's it. There is no runtime, no sandbox, no execution model. The agent reads SKILL.md and follows what it says, the same way it would follow anything else you type at it.

The frontmatter description is the only part that behaves specially — it's always in the agent's context, so it functions as the trigger. The body is loaded on demand, once the description convinces the agent this is the right file to open.

Which means a skill is best understood as a lookup table entry: a condition, and a procedure to run when it matches.

The one I built

Creating a post here means putting a file at content/tsx/YYYY-MM-DD-slug.tsx. The date has to be today. The slug has to be derived from the title consistently. Get either wrong and the content sync produces a duplicate or a broken URL.

This is exactly the kind of thing an LLM does almost right — a slug that hyphenates slightly differently, a date pulled from the wrong place. So the skill delegates: a Node script owns the naming logic, and the skill's main instruction is to shut up and call it.

- **Always call the script. Never hand-write the post file yourself**,
  even though you technically could. The whole point of this skill is that
  the filename/date/path logic lives in one place and never drifts.

The skill is documentation. The script is the implementation. The skill exists to make sure the script gets used.

Then it failed three times

First real invocation, the agent ran this and got an immediate Cannot find module:

node scripts/new-post.js "Building a Post-Creator Skill"

Because the script isn't at scripts/new-post.js. It's at .github/skills/post-creator/scripts/new-post.js, sitting next to the SKILL.md that describes it. The skill had written the short path, the agent copied it verbatim, and Node went looking in a directory that doesn't exist.

Nothing was wrong with the reasoning. The instructions were wrong, and they were followed exactly.

The part that makes this a real trap

Skill paths resolve from the workspace root, not from the skill's own directory. So a skill has to refer to its own neighbouring files using their full path from the repo root. Relative paths read naturally and are silently wrong.

Worse, the wrong path is the intuitive one. A file called new-post.js lives in scripts/ in roughly every repo ever written. So the failure mode isn't just “path is wrong” — it's “path is wrong in the direction everyone guesses.”

The fix

Three changes, only one of which is the obvious one.

1. Correct the path, and explicitly name the wrong one: “Do not shorten it to scripts/new-post.js.” Naming the plausible mistake beats stating the correct answer alone, because the mistake is what the reader is already reaching for.
2. Separate the two paths that were being conflated. The script lives nested; the working directory must still be the repo root, since the script resolves content/tsx/ from process.cwd(). Two different path rules in one command, and the skill originally explained neither.
3. Add a recovery rule. If the command fails with Cannot find module, re-run with the full path — don't go hunting for the file, and don't fall back to writing the post by hand.

The third one is the one I'd have skipped. A skill that only describes its happy path leaves the agent to improvise when things break, and improvisation is precisely what the skill was written to prevent. The failure branch deserves as much specification as the success branch.

What I took from it

• Skills fail like documentation, not like code. No stack trace points at the sentence that was wrong. The agent does what it was told, and the error surfaces somewhere downstream.
• Every path in a skill is load-bearing. Prose can be approximate. Paths cannot.
• Say what to do when it breaks. Otherwise the fallback is whatever the agent invents, which is the thing you were trying to eliminate.
• Test by using it, not by reading it. The skill looked completely fine. It broke on first contact.

This post was created by the skill, on the fourth try, after the skill was fixed. Which is the only endorsement it needs.