Skip to content

When to write a skill: stop explaining the same thing to your agent

· 4 min read · AI

On this page

Every time I prepared the English version of a post, I told the agent the same things: keep technical terms in English, adapt the examples to the reader, add the translation link only after publishing. Each time there was a chance I'd forget something, or explain it less clearly than the time before. The Claude Code docs recommend skills for exactly this kind of repeated work.1 So I turned the repetition into a skill, and translation stopped being a chore.

I covered what a skill is and the general rules on ViraStack Academy. This post is about the rule of thumb and the two skills I use on this blog.

Three instructions repeated for every translation, collected into a single SKILL.md file

The rule: you keep explaining the same thing

The Claude Code docs put it plainly: create a skill when you keep pasting the same instructions, checklist or multi-step procedure into chat, or when a section of CLAUDE.md has grown from a fact into a procedure.1 The difference from CLAUDE.md is that a skill's body only loads when it's used.1

In short: facts go in CLAUDE.md, procedures go in a skill. "This project uses pnpm" is a fact. "Prepare the English version of a post with these steps" is a procedure.

localize-post: localization, not translation

The first skill I built for this site, localize-post, prepares the English version of a Turkish post. It starts from the idea in my localization post (in Turkish): don't translate, adapt. The skill doesn't go sentence by sentence; it carries the idea over to an English-speaking reader. A few examples:

  • Technical terms (state, cache, hook) stay in English in both languages.
  • Place names change for the reader: Istanbul becomes Paris in English.
  • Turkey-specific examples change. My ViraStack Mask post uses a Turkish national ID (TCKN) example; since that means nothing to an English reader, the English version uses an IBAN instead.

After using the skill for a while, I noticed a new repetition: after every post I asked, "Is this good enough to be featured on the site?" Since that was a recurring question too, I added it to the skill. There was one more question I kept asking: are the sources right? That one became the second skill.

verify-sources: trust fresh eyes, not the writer

AI can hallucinate and suggest wrong sources. I saw it happen a few times, so I added a check to my posts: verify-sources.

It works in two stages. While writing, every sentence with a number, a date or an "according to X" gets a footnote right away, and no footnote is written before the source has been opened and read. When the draft is done, a clean subagent that has never seen the post checks every claim against a verbatim quote from its source.

The heart of the skill is one sentence: "The session that wrote the draft assumes its own sentences are right." That's why the check isn't done by the AI that wrote the post, but by a separate AI agent seeing it for the first time. A summary isn't enough either; the evidence is the sentence inside the source. This post's footnotes went through the same process.

When the two skills connect

Once I had verify-sources, I updated localize-post too. The Turkish post has already been verified, so the English version doesn't get a full scan, only a diff check: is each footnote tied to the same claim in both languages, and does a changed example bring a new claim?

The two skills now form one publishing flow: the Turkish post is written and verified, the English version is localized, and only the differences are checked.

A skill is never finished

Anthropic's skill authoring guide recommends assuming Claude is already very smart and only adding what it doesn't know.2 The method it suggests: do the task without a skill first, notice what you keep explaining, turn that into a skill, and refine it as you use it on real work.2

That's my method too: I improve a skill as I use it. If you're about to explain the same thing to your agent a second time, it might be time to write a skill.

You can read both skills in full in the site's GitHub repo: localize-post and verify-sources.

Sources

  1. Claude Code: Extend Claude with skills

  2. Anthropic: Skill authoring best practices