A collection of random, unconnected things.

Appearance

Your AI Doesn't Know How You Work. Teach It. ​

Part 1 of 2: The problem, the fix, and the six workflow files I built

The Problem ​

I've been building PiPiece — a Raspberry Pi HQ Camera controller with a Vue.js touchscreen UI — as a side project. I started leaning on AI coding tools to speed things up. It worked, mostly.

But I kept hitting the same wall. At one point I had two buttons that weren't aligned. I asked the AI to fix it. It came back: "Done — the buttons are now perfectly aligned." They weren't. One still had extra padding. I asked again. Same thing. Confident, wrong, and I was doing this loop for longer than I want to admit.

That wasn't an AI problem. It was a me problem. I was giving it no context about how I actually work.

It didn't know I wanted small, focused Vue components. It didn't know I write tests first. When GitHub Copilot switched me to a different model mid-project, I'd get a completely different personality with no memory of any of it.

The Fix ​

The answer showed up in my YouTube suggestions while I was going down an AI rabbit hole: a video by Matt Pocock, "5 Claude Code skills I use every single day".

Claude Code supports "skills" — markdown files in .claude/commands/ that work like reusable slash commands. They don't just prompt; they walk the AI through a specific workflow every time you invoke them.

Instead of hoping it behaves consistently, I defined how I want it to work. I described my process in plain English and had Claude Sonnet 4.6 turn those descriptions into skill files. Here's exactly what I asked, cleaned up for spelling:

"Help me write some Claude skills for this project. I'd like Claude to ask clarifying questions before coding. Write tests before writing code (TDD) — make sure the new test fails first, then fix the code to make it pass (red, green). Keep the documentation up to date and highlight new features. Write a good commit summary for every commit and include a social media post."

"I'd like these Claude skills to also work with GitHub Copilot and other AI engines — can you set those up too?"

"Add a skill for two things: (1) when updating an AI skill, make sure it's propagated to all other AI engine configs — GitHub Copilot can switch models and I want consistent behavior regardless of which model is active. (2) I don't like large, complex Vue views. When you see a view with a lot of inline or complex components, offer to refactor it into smaller, reusable, testable components organized into categories. Include unit tests, browser tests, Storybook stories, and matching Storybook E2E tests."

"I don't use Twitter or Mastodon — I use BlueSky and LinkedIn. Update all the skills to suggest those instead. For really large features, suggest a LinkedIn article."

"I don't use Cursor, Windsurf, or Cline — remove those configs."

"Do I actually need both .github/copilot-instructions.md and a root-level copilot-instructions.md? I store things in GitLab, not GitHub." (No — .github/copilot-instructions.md is the one Copilot actually reads. The .github/ directory is just ignored by GitLab. Dropped the duplicate.)

Six prompts. It read the project structure, understood the conventions, and produced production-ready skill files that fit right in.

The Six Skills ​

/feature asks eight clarifying questions before writing a line of code:

  • What should this do, in one sentence?
  • Which part of the system does it touch? (server / Vue UI / Python / Pi hardware / docs)
  • What are the success criteria — how will we know it's working?
  • Are there edge cases or error states to handle?
  • Should this be user-configurable, or is the behavior fixed?
  • Does it replace or extend anything that already exists?
  • Are there related features or components to stay consistent with?
  • Any performance, accessibility, or dark-mode concerns?

Only after you confirm does it proceed — strict TDD, then README update, then commit.

/tdd is a focused red-green cycle for adding tests to existing code:

  • One failing test at a time
  • Shows the failing output before writing any implementation
  • Waits for confirmation before proceeding

/commit turns a diff into a complete commit package:

  • Reviews the diff and classifies the change type (feat, fix, refactor, etc.)
  • Writes a conventional commit message with a why-focused body
  • Drafts a BlueSky post and a LinkedIn update
  • Suggests a LinkedIn article outline for bigger changes

/refactor-ui is the one I probably needed most. When a Vue view gets past about 100 lines — PreviewView and AutoView are the two that pushed me to build this — it offers to break things into focused, testable components:

  • Proposes component names and categories before touching anything
  • Writes unit tests, Storybook stories, and E2E tests first (they all fail)
  • Implements each component with the minimum needed to pass its tests
  • Replaces the original view with a thin composition layer

/docs keeps the README honest after every change:

  • Reviews recent git history to find what's new or changed
  • Updates the README with > **New:** callouts for new features
  • Flags UI changes that need screenshots
  • Updates .github/copilot-instructions.md if the architecture changed

/sync-skills is the meta-skill. When any workflow changes in one config, it audits all the others:

  • Produces a gap report showing what's missing or outdated in each config
  • Updates each file to match, preserving the native format for each engine
  • Confirms everything is consistent before proposing a commit

One More Thing: Copilot Uses One File for All Models ​

GitHub Copilot in VS Code reads .github/copilot-instructions.md and injects it into every chat session, regardless of which AI model is active. GPT-4o, Claude, o1, Gemini — they all get the same instructions. The whole setup is two directories:

.claude/commands/          <- Claude Code slash commands
  feature.md, tdd.md, commit.md, refactor-ui.md, docs.md, sync-skills.md

.github/
  copilot-instructions.md  <- GitHub Copilot (all models)

No plugins. No integrations. Just markdown.

The Bigger Takeaway ​

The most useful thing wasn't the skill files themselves. It was having to describe my workflow precisely enough to write them down. That's harder than it sounds. But once you can explain your process clearly enough that an AI follows it, you can also explain it to a new team member on day one.

The tools are capable. They just need to know what you consider done.

Part 2 covers a side effect I didn't set out to build at all.

Inspired by "5 Claude Code skills I use every single day" by Matt Pocock. PiPiece is open-source; the skill files are in the repo.

— John Webb Cole