How We Automated Our Entire Dev Workflow with Claude Code Skills

Building Synoema — a compiler with 9 Rust crates, 41K lines of code, and 1,485 tests — is a solo project. One developer. No team. No sprints. No project manager. And yet the project ships features in parallel, runs multi-stage pipelines, and maintains a structured change log across dozens of simultaneous modifications.

The secret is not heroic effort. It's a system of skills — reusable workflow definitions that turn Claude Code from a chat assistant into an autonomous development partner. This article explains how the system works, what it enables, and why it matters beyond our specific project.

The Problem: AI Assistance Without Structure

The default mode of AI-assisted development is conversational. You describe what you want. The AI writes code. You review, adjust, iterate. This works for small tasks, but it breaks down at scale:

• No memory between sessions. Each conversation starts from scratch. The AI doesn't remember the design decisions you made yesterday.
• No workflow consistency. Ask the AI to "add a feature" three times, and you'll get three different approaches to planning, testing, and documenting.
• No parallelism. One conversation, one task at a time. If you have five independent changes, you wait for each to finish sequentially.
• No verification. The AI writes code and hopes it works. There's no structured check that the implementation matches the spec.

We needed something different: a system where the AI follows a consistent process, produces auditable artifacts, and can work on multiple changes simultaneously.

Skills: Workflow as Configuration

Claude Code has a built-in skills system. A skill is a markdown file (SKILL.md) in a specific directory that defines a reusable workflow. The key insight: discovery is automatic. Drop a file in the right place, and it becomes available immediately. No registration, no configuration, no build step.

.claude/skills/
  openspec-new-change/SKILL.md      → Skill("openspec-new-change")
  openspec-apply-change/SKILL.md    → Skill("openspec-apply-change")
  openspec-verify-change/SKILL.md   → Skill("openspec-verify-change")
  openspec-archive-change/SKILL.md  → Skill("openspec-archive-change")
  openspec-explore/SKILL.md         → Skill("openspec-explore")
  ... (11 skills total)

Each SKILL.md has YAML frontmatter (name, description, metadata) and a markdown body with the actual instructions. The body is not code — it's a detailed prompt that tells Claude exactly how to behave when the skill is invoked. Think of it as a runbook that the AI follows autonomously.

Commands: The User Interface Layer

Skills are the engine. Commands are the steering wheel. Claude Code maps slash commands to skills through a parallel directory structure:

.claude/commands/
  opsx/
    new.md       → /opsx:new       → invokes openspec-new-change
    ff.md        → /opsx:ff        → invokes openspec-ff-change
    apply.md     → /opsx:apply     → invokes openspec-apply-change
    verify.md    → /opsx:verify    → invokes openspec-verify-change
    archive.md   → /opsx:archive   → invokes openspec-archive-change
    go.md        → /opsx:go        → smart orchestrator
    run.md       → /opsx:run       → full autonomous pipeline
    run-par.md   → /opsx:run-par   → parallel execution
    run-seq.md   → /opsx:run-seq   → sequential execution
    run-pipeline.md → /opsx:run-pipeline → staged pipeline

The two-tier architecture separates concerns cleanly. Skills contain the complex logic ("how to verify an implementation matches its spec"). Commands contain the invocation pattern ("the user types /opsx:verify"). A single command can orchestrate multiple skills. A single skill can be invoked by multiple commands or by the AI itself.

OpenSpec: The Artifact System

Skills alone give you consistent workflows. But workflows need something to work on. That's where OpenSpec comes in — a structured artifact system that gives every change a traceable lifecycle:

openspec/changes/fix-domain-refs/
  proposal.md   — What and why (scope, motivation, constraints)
  design.md     — How (architecture, tradeoffs, decisions)
  delta-spec/   — What changes in the spec
  tasks.md      — Implementation checklist
  status.md     — Current state (auto-updated)

Each artifact serves a specific purpose. The proposal captures the "what" and "why" before any code is written. The design captures architectural decisions. The delta-spec records what changes in the formal specification. The tasks break down implementation into discrete steps. And the status file tracks progress.

The lifecycle is: create → fast-forward → apply → verify → archive. Each phase has a corresponding skill. And the entire lifecycle can run autonomously with a single command.

Automation Out of the Box

Here's where the system gets interesting. Because skills are composable and changes are structured, we can build higher-order workflows that would be impossible with conversational AI:

1. Full Autonomous Pipeline

One command to rule them all:

/opsx:run fix-domain-refs

This invokes a meta-skill that chains four skills in sequence: fast-forward (generate all artifacts), apply (implement all tasks), verify (check implementation matches spec), archive (move to completed). The AI runs autonomously, stopping only for critical decisions.

2. Parallel Execution

/opsx:run-par fix-auth add-cache update-docs

Each change launches in its own agent with an isolated git worktree. Three changes execute simultaneously, each following the full pipeline. Results merge when all agents complete. Merge conflicts are handled automatically.

3. Staged Pipelines

/opsx:run-pipeline par(fix-auth add-cache) >> refactor-api >> par(docs tests)

Three stages with barrier synchronization. Stage 1 runs two changes in parallel. Stage 2 waits for Stage 1 to complete, then runs a single change. Stage 3 runs two more in parallel. If any stage fails, the pipeline pauses and offers retry/skip/stop options.

This is the command that generated this very article. The pipeline that produced what you're reading right now was:

/opsx:run-pipeline par(fix-domain-refs dogfooding-strategy) >> skills-article

Stage 1 fixed domain references and documented our dogfooding strategy in parallel. Stage 2 (this article) ran after both completed. Three changes, two stages, one command.

4. Smart Continue

/opsx:go

No arguments needed. The system detects which change is active, what phase it's in, and resumes autonomously. If you were interrupted mid-implementation, it picks up where you left off. If verification failed, it re-runs from the verify phase.

What This Actually Looks Like in Practice

A typical day on Synoema involves 3–5 changes running through the pipeline. Some are small (fix a typo in docs). Some are large (add a new compiler phase). The system handles both with the same structure:

1. Explore (/opsx:explore) — think through the problem, investigate the codebase, draw diagrams. No code written.
2. Create (/opsx:new feature-name) — generate proposal with scope and motivation.
3. Fast-forward (/opsx:ff feature-name) — generate all artifacts (design, delta-spec, tasks) in one pass.
4. Apply (/opsx:apply feature-name) — implement each task, running tests after each one.
5. Verify (/opsx:verify feature-name) — check that implementation matches all artifacts.
6. Archive (/opsx:archive feature-name) — move to completed, update specs.

Or, for well-understood changes: /opsx:run feature-name and walk away.

The archive directory tells the story. As of today, it contains dozens of completed changes, each with full artifacts: proposal, design, delta-spec, tasks, status. Every decision is traceable. Every implementation is verified against its spec.

Why Directory-Based Discovery Matters

The most underappreciated aspect of this system is what it doesn't require: no plugin system, no package manager, no build tool, no configuration file mapping skills to commands. You create a directory, drop a markdown file in it, and the system discovers it.

This has profound implications:

• Zero friction to add a new workflow. Need a skill for "analyze Docker logs and create a fix"? Create .claude/skills/openspec-fix-from-logs/SKILL.md. Done. It's immediately available.
• Version control is the registry. Skills live in the repo, travel with the code, and are reviewed in PRs like any other change.
• Project-specific customization. Every project can have its own skills tailored to its workflow, conventions, and constraints.
• Composability. Skills can invoke other skills. Commands can chain skills. Meta-skills can orchestrate entire pipelines. The building blocks snap together because they share the same discovery mechanism.

The Bigger Picture: AI as Infrastructure

Most AI development tools treat the AI as an assistant — a smart autocomplete that you interact with conversationally. The skills system treats AI as infrastructure. The difference is fundamental:

The Synoema project is a single developer shipping a 41K-line compiler with the velocity of a small team. Not because the AI is magic, but because the workflow infrastructure — skills, commands, artifacts, pipelines — eliminates the coordination overhead that normally requires multiple humans.

Limitations and Honest Assessment

This system is not without friction:

• Context window pressure. Complex skills with long instructions consume tokens. A pipeline running multiple agents can hit context limits.
• Worktree isolation gaps. Git worktrees work well for file-level isolation but don't help with shared state (databases, running servers).
• Verification is only as good as the spec. If the proposal or design is wrong, the verification phase will dutifully confirm that the wrong thing was built correctly.
• Learning curve. The system has 11 skills and 16+ commands. Understanding when to use which takes time.

Despite these limitations, the productivity gain is real and measurable. Changes that would take an hour of back-and-forth conversation complete in minutes with a single pipeline command.

Try It Yourself

The skills system is not Synoema-specific. Any project using Claude Code can adopt this pattern:

1. Create .claude/skills/your-workflow/SKILL.md with YAML frontmatter and instructions.
2. Create .claude/commands/your-command.md for the slash command interface.
3. Commit both to your repo.

Start simple. A skill for "run tests and report results" or "create a PR with a standard template" is enough to see the value. Complexity emerges naturally as you identify repeating patterns in your workflow.

The source for all Synoema skills is in the repository at .claude/skills/. Feel free to use them as templates.