My Claude Skills Workflow

At some point I had typed the same thing into the same session for what felt like the hundredth time: No, no emojis in the logs. Yes, clippy has to be clean. No, please no println!. And Claude nodded politely every single time — and started from zero again in the next session.

That's the point where you either develop patience or build a tool. I built a tool. Eight, actually.

First things first: what is a skill?

A skill isn't anything magical — it's a text file with instructions and a label on the front saying what it's for. Claude reads the label, and only pulls the file if the task actually matches.

Think of a binder on a shelf: the binder labelled "coding conventions" stays put while I'm talking about my book project. The moment I start programming, it gets pulled out. That's the whole trick — I don't have to paste my rules into every conversation, they're just within reach.

How this started

At work we were already using skills and harnesses, so this wasn't new territory. Privately I had something else going on: my own coding conventions, which I've been carrying around for years and explaining by hand over and over.

At some point it was obvious to put the two together. The first skill was coding — my conventions, written down properly once, applied to every piece of code work from then on. Everything else grew out of that.

And that's still how skills come about today: not at a drawing board, but because I notice in real sessions that I'm explaining the same thing for the third time. The third time is the trigger.

One skill became a plugin

By now there are eight skills, bundled into a plugin called orbitstack. Everything lives in one repo — here's an excerpt:

claude-skills/
├── README.md
├── justfile
├── scripts/
│   ├── build.sh
│   └── validate.sh
└── skills/
    ├── blog-writing/SKILL.md
    ├── calendar/SKILL.md
    ├── coding/SKILL.md + ref/   (11 reference files)
    ├── tracky/SKILL.md + ref/SYNTAX.md
    └── ...

The justfile — itself something new that came out of this rebuild — packs the skills into a .plugin file. I upload that to Claude Desktop or Claude Code, restart once, done. build.sh and validate.sh are the build and check chain behind it.

The imbalance is hard to miss: coding is by far the biggest chunk, with its own files for stack, style, git, deploy, testing, ports and so on. Others like calendar or blog-writing get by with a single file. That's not an accident — it's the result of my biggest lesson learned.

The map and the fine print

The mistake early on: I maintained the same convention in several places. And anything maintained in two places drifts apart — that's not a forecast, that's a law of nature.

The fix is a division of labour. The SKILL.md is the terse map: every hard rule stated flush in the prose, with a pointer to the file holding the detail.

- **Frontends → Svelte (SvelteKit / Vite). Backends, CLIs, MCP servers &
  libraries → Rust** — ...
- **`cargo fmt` and `cargo clippy --all-targets -- -D warnings` must both
  be clean** ... (see `ref/STACK.md`)

And right at the end, a pure table of contents pointing at the ref/ files:

## References
- Stack, tooling, linting/formatting, crate defaults per language → ref/STACK.md
- Code style (KISS, YAGNI, Rule of Three, comments) → ref/CODE_STYLE.md
- Git, Forgejo/`fj`, commit/push permission, semantic versioning → ref/GIT.md
- ... (11 ref files in total)

The detail only gets loaded when it's needed. One convention, one place.

The second half of the same lesson was about wording. Too vague, and the rule gets politely ignored. Too strict, and it gets applied where it has no business being. I had to sharpen both, more than once.

Skills are allowed to contradict each other

I found this unexpectedly liberating: two skills may carry opposing rules, as long as it's clear where each one applies.

In the khan-buch skill — my fantasy book project — I explicitly do not want a recommendation. I want options with pros and cons, and I decide. When coding I want the exact opposite: a clear call, with reasoning.

The same split applies to how the work is done. The book project spells out the shotgun approach:

First, lots of NPCs, places, concepts, systems and events as generic stubs with at most one hook. Fleshing out and merging comes later. Leaving a TBD is deliberate, not an omission — don't fill it in unasked.

A TBD in worldbuilding is a placeholder for later. A TBD in code is a bug. Both are written down that way in the skills, and both are right.

How certain is the answer?

My favourite detail sits in the repo-sanity skill, which checks a repo against my conventions. Every item on the checklist is marked with how certain the answer is:

- **[m]** mechanical — a file, a grep or a git command decides.
  Report as fact.
- **[g]** a grep finds candidates, you judge each one. Report as an
  assessment, with the candidate lines.
- **[j]** judgment — read the code. Take a sample, and say what you read.

Translated:

• [m] is a yes/no question a simple command answers unambiguously — "does the file SPEC.md exist?". No room for interpretation.
• [g] gives you a shortlist that still has to be checked by hand.
• [j] can't be shortcut — the code actually has to be read and judged, like copy-editing.

In short: from "the computer knows for sure" through "the computer suggests, someone decides" to "only looking closely helps". A check then looks like this:

- [g] No secret or live runtime config is tracked. Look at tracked `*.toml`
  beyond the tool files, `.env`, anything with `*secret*` or `*token*`;
  a runtime config needs its `.example` instead.

The difference day to day is big. For every finding I know immediately whether to believe it or go look.

Two pitfalls

First: Claude Code in the terminal can have project-local skills on top of the plugin ones, and those two can collide. I would have liked to know that beforehand. Instead I spent two hours puzzling over why Claude stubbornly ran version 0.12 of the coding skill while the plugin had been on 0.16 for ages.

Second: if you work with a skill for years, then finally nail the conventions down, rewrite them cleanly — and afterwards build a repo-sanity skill that checks every repo against exactly those conventions …

… then please don't expect your own code to still be "fine" afterwards. cough he said, after a number of stack migrations cough.

Me, after the repo-sanity check was introduced

Could of course also just be my own stubborn brain shouting: "Everything must match the convention, nyeh nyeh NYEH!"

What came out of it along the way

Two tools fell out of this rebuild, both for the same reason: an existing workflow was too manual for my taste.

bumper took over versioning. Bumps according to SemVer — major, minor, patch — and not just for skill revisions, but for Rust crates and npm packages too. One tool for all three worlds.

tracky replaced Notion: tasks, link list, game wishlist. At its core is an inline syntax where everything lives in the text itself — tags, priority, due date, references:

#einkauf                 tag / tasklist / group
!1                       priority, 1 highest … 5 lowest
~20260915T2000           due — a moment
@rezepte/lasagne         → pad with that slug
°42                      → task 42

The guiding line: The text is the source. Everything else is a cache on top of it. There's a post of its own coming for that.

And this post here?

It runs on a skill too. blog-writing knows exactly one pipeline:

status: Idea → Collecting → Writing → Published   (or: Discarded)

Collecting happens in tracky — a task, a scratchpad, loose notes. Writing and publishing happen in satz. Deliberately two tools instead of one that tries to do everything. This very paragraph sat in the pad as a bullet point two days ago.

So what now?

Better than before, definitely. One point of friction remains: every now and then Claude complains about its own guardrails despite explicit clearance in the skill — git push, merges, sometimes a deploy to prod. Explicitly marked as safe by the skill, and still: a question first.

I'll break him of that habit yet. 😛