The day I stopped writing prompts and started writing commands, and then, skills

A few weeks ago, I shared how I built an operating system for a 3-person SaaS using Claude Code. Since then, I’ve already torn half of it apart and rebuilt it.

That’s not a failure. That’s the point.

In four months, my AI workflow went through three distinct paradigm shifts. Each one felt like a minor earthquake - the way I thought about the tool changed fundamentally. And each shift came from the same realization: I was still thinking too small.

Phase 1: Writing prompts (October 2025)

I started with Cursor and did what most people do - wrote prompts.

prompts/
├── raw-to-structured.md      # "Take this transcript and extract..."
├── insights-to-shaping.md    # "Given these insights, identify..."
├── shaping-to-prd.md         # "Transform this opportunity into..."
└── challenge-strategy.md     # "Challenge these assumptions..."

Each file was a set of instructions I’d paste into a conversation. My workflow looked like this:

  1. Open Cursor, load a prompt file
  2. Paste in the customer transcript
  3. Copy the output somewhere
  4. Open the next prompt, paste the previous output
  5. Repeat

I was using AI like a fancy text processor. Feed input, get output, manually chain the steps together.

The folder structure changed three times in ten days. I kept reorganizing because nothing stuck. The tool wanted me to think in terms of “give AI text, get text back.” But my actual work wasn’t about transforming text - it was about making decisions.

The real problem: every session started from zero. No memory. No context. No accumulated knowledge. I explained our product, our customers, our constraints - every single time.

Phase 2: Writing commands (January 2026)

In November, I switched to Claude Code. Then the repo went quiet for two months.

That’s not because I stopped working. It’s because I was experimenting without committing. Feeling out a completely different way of thinking.

When I came back in January, I deleted everything and started over:

.claude/
├── CLAUDE.md                   # How we work together
└── commands/
    ├── ux-research.md          # Full UX workflow in one command
    ├── new-project.md          # Create Linear projects
    ├── commit-push-pr.md       # Git automation
    └── save-discussion.md      # Document decisions

The shift wasn’t technical - it was conceptual.

Prompts describe. “Take this data and analyze it for patterns.”

Commands execute. “Load the customer research, challenge my assumptions with evidence, explore three UX approaches, map them to our design system, and generate a PRD.”

One word difference. Completely different mental model.

Here’s what a simplified command file actually looked like:

# ux-research.md

## Context
Load these files before starting:
- .context/billabex-messaging.md (product, ICP, pain points)
- .context/development-principles.md (constraints, appetite)

## Process
1. Search research/calls/ for transcripts mentioning the topic
2. Extract pain points with severity scores
3. Challenge the user's initial hypothesis with data
4. Propose three UX approaches with tradeoffs
5. Generate a PRD using the agreed approach

## Output
Structured markdown PRD with: problem statement, evidence, proposed solution, edge cases, acceptance criteria.

Three sections: what to know, what to do, what to produce. That’s the whole pattern.

With prompts, I was the orchestrator. I decided what to feed the AI, when, in what order. With commands, I described the whole workflow once - and Claude ran it. It loaded context files, queried customer data, applied design principles, and produced structured output. The 9 context files in .context/ acted as persistent memory - Claude knew our ICP, our pain points, our development principles without me re-explaining them.

Here’s what a session looked like after the switch:

Me: /ux-research - I want to design the invoice import flow.

Claude: Loading customer research from research/calls/… I found 47 mentions of “data quality” across transcripts. Pain score: 3.8/5. Before we design, what’s your hypothesis for why imports fail today?

Me: Probably bad file formats?

Claude: The data says otherwise. The recurring complaint is invoices importing with wrong amounts or missing client references - not format issues. I’d recommend we explore validation-first approaches. Here are three options…

I didn’t paste anything. I didn’t load any context manually. The command did all of that - and then pushed back on my assumption with actual customer data.

The result was immediate. January 13th became the most productive single day I’ve ever had since: I shipped four major automations (UX research, Linear integration, git workflow, Fireflies sync) in seven commits between 10 AM and 6 PM.

This felt like the final form. Commands were powerful, context was persistent, workflows were automated.

It wasn’t the final form.

Phase 3: Writing skills (February 2026)

Three weeks later, I migrated again.

.claude/
├── CLAUDE.md                        # Project conventions only
├── skills/
│   ├── ux-research/
│   │   ├── SKILL.md                 # Agent behavior + workflow
│   │   ├── prd-template.md          # Structured output template
│   │   └── shaping-template.md      # Research output format
│   ├── substack-writer/
│   │   └── SKILL.md                 # Voice profile, workflow, checklist
│   ├── linkedin-writer/
│   │   └── SKILL.md
│   ├── new-project/
│   │   └── SKILL.md
│   └── new-issue/
│       └── SKILL.md
└── context/                         # Shared memory
    ├── billabex-messaging.md
    ├── content-strategy.md
    ├── topic-bank.md
    └── development-principles.md

What changed? Three things.

Skills carry their own context. A command was a single markdown file with instructions. A skill is a directory - it can hold templates, reference files, checklists. My /ux-research skill now includes its own PRD template and shaping format, instead of inlining everything in one giant prompt.

Skills declare what they need. The YAML frontmatter tells Claude when to use the skill and how it should behave:

---
name: ux-research
description: Use when exploring a feature idea and needing to validate the problem, compare solutions, and define MVP scope before prototyping
---

A command was just text Claude had to interpret. A skill is structured metadata

  • Claude knows what it’s for before reading a single line of the instructions.

Here’s a real excerpt from the substack-writer skill - the one that drafted this post:

## Voice Profile

Tone: Technical founder sharing real work - not thought leadership.
Style: Show the work, not just the insight. Code snippets, actual
  numbers, real decisions.
Length: 800-1500 words.

## Value Test (Required)

Before presenting any draft, answer these three questions.
If the answers aren't clear and compelling, the draft isn't ready.

1. Does this post provide real value?
2. Can the reader use this in their day-to-day?
3. What will they learn?

That value test is what caught this very post before publishing - the first draft was too narrative, not actionable enough. The skill enforced quality I might have skipped.

Skills can be global or project-specific. I promoted commit-push-pr and save-discussion to ~/.claude/skills/ - now they work in every project on my machine, not just this one. Project-specific skills like ux-research stay in the project.

Here’s the before and after for the same UX research workflow:

Command version (January): 308 lines, one file. Everything crammed in - context loading instructions, research process, component mapping, PRD format, edge case requirements. Claude had to parse the whole thing every time.

Skill version (February): 103-line SKILL.md for behavior and process. Separate 141-line PRD template. A shaping template for research output. Each piece has a clear job.

Same capability. Better organized. Easier to iterate on.

Here’s how a skill session differs from a command session - same workflow, different behavior:

Me: /ux-research - I want to design the invoice import flow.

Claude: Before we explore solutions, let me check if there’s existing work on this topic… Found a shaping doc from January with three approaches. Two were rejected for complexity. Loading the surviving option as starting point.

Me: Actually, I want to start fresh.

Claude: I’d push back on that. The January research included data from 12 customer calls. Starting fresh means re-discovering what you already know. I suggest we build on the validated pain points and focus the new work on the UX layer. Here’s what I’d keep and what I’d revisit…

The command version would have followed my instruction. The skill version had enough context and structure to exercise judgment - and save me from redoing work.

What each shift actually changed

Looking back, the pattern is clear:

| Phase | I wrote... | Claude was... | Context lived in... |
|-------|-----------|---------------|---------------------|
| Prompts | Instructions to paste | A text processor | My clipboard |
| Commands | Workflows to trigger | An assistant with memory | `.context/` files |
| Skills | Agents with expertise | A team of specialists | Shared + skill-specific |

Each phase didn’t just change the file format. It changed what I expected from the tool.

With prompts, I expected answers. With commands, I expected workflows. With skills, I expect judgment.

My /ux-research skill doesn’t just follow steps - it challenges my assumptions, references customer data, and pushes back when I’m solution-first. The substack-writer skill (the one generating this post’s first draft, actually) has a voice profile, a value test, and a quality checklist. It’s not “write me a blog post” - it’s “be the kind of writer who checks whether the reader can actually use this.”

The Meta-Lesson

Here’s the thing nobody tells you about building with AI: the setup is never done.

My January system was great. I genuinely thought I’d reached the end state. Then Claude Code shipped skills as a first-class concept, and I realized my commands were just skills without structure.

The 1,072 lines I deleted in the migration weren’t wasted work. They were the foundation I needed to understand what the next version should look like. Each restructure took less time because I understood the problem better.

The repo has been restructured six times in four months. The first three (Cursor AI phase) were frustrating - searching for a shape that fit. The last three (Claude Code phase) were deliberate - evolving toward better abstractions.

If your AI setup looks exactly the same as it did two months ago, you’re probably not using it enough.

Try this now

If you’re using Claude Code (or any AI coding tool) today, here’s the smallest useful step:

  1. Create .claude/commands/your-workflow.md
  2. Write three sections:
## Context
List the files or knowledge your AI needs before starting.

## Process
Write the steps as if briefing a smart colleague.

## Output
Describe the format you want back.
  1. Run it with /your-workflow

That’s your first command. It’ll be messy. You’ll rewrite it in a week. That’s how it’s supposed to work - each version teaches you what the next one should look like.

What’s next

I went deep on the Fireflies automation - how 60+ customer call transcripts sync automatically to my repo, get formatted as markdown, and feed directly into the UX research workflow. It’s the infrastructure that makes everything else possible.

Since a few weeks, we’re also testing Granola. It’s not fully integrated within the workflow but it might be a good opportunity to talk about what I’m testing.