Walking Skeleton

The thinnest possible implementation that touches every layer of your architecture end-to-end — minimal and unpolished, but fully functional from user action to data store and back.

What is it?

A walking skeleton is the smallest version of your software that exercises every major architectural component. It’s not feature-rich. It’s not pretty. But it proves that all the pieces of your system can talk to each other: the user interface can send a request to the server, the server can query the database, and the response flows all the way back to the screen.

The term comes from Alistair Cockburn (2004), one of the original signatories of the Agile Manifesto. His insight: before you invest time building features, you should prove that the architecture itself works. If the frontend can’t communicate with the backend, or the backend can’t reach the database, no amount of feature work will save you.

A walking skeleton is not a prototype (which might skip layers to demonstrate an idea). It’s not a minimum viable product (which has enough features to be useful to real users). It’s the bones of the system — no flesh, no skin, but the skeleton is connected and it walks. Everything you build afterward adds muscle and detail to these proven bones.

Building the skeleton first is an act of risk reduction. You surface integration problems — the hardest problems in software — on day one, when they’re cheapest to fix.

In plain terms

A walking skeleton is like doing a dress rehearsal for a play before you’ve built the sets or finished the costumes. The actors walk through every scene on a bare stage, proving the sequence works: entrances, exits, transitions, timing. The rehearsal is rough, but it exposes every structural problem. Once you know the flow works, you can confidently invest in sets, lighting, and costumes.

At a glance

How a walking skeleton connects the layers (click to expand)
graph LR
    UI[User Interface] -->|sends request| API[API / Server]
    API -->|queries| DB[Database]
    DB -->|returns data| API
    API -->|sends response| UI
    style UI fill:#4a9ede,color:#fff
    style API fill:#4a9ede,color:#fff
    style DB fill:#4a9ede,color:#fff
Key: All three nodes are highlighted because all three must work. The skeleton is the thinnest thread connecting them: one request, one query, one response. If any arrow fails, you’ve found an architectural problem before investing in features.

How does it work?

Building a walking skeleton follows a clear pattern: identify every layer, implement the thinnest possible thread through all of them, and verify the thread works end-to-end.

1. Identify the architectural layers

Before building, list every major component your system needs. For a typical web application:

Layer	Example
User interface	A web page in a browser
Application logic	A server-side framework handling requests
Data access	An ORM or database driver
Data storage	A relational database
Infrastructure	Hosting, deployment pipeline

Think of it like...

A plumber testing a new building’s water system. Before installing fancy fixtures, they turn on the water at the main and check: Does water flow through every pipe? Does it reach every floor? Does drainage work? One faucet per floor is enough to prove the system works.

2. Build the thinnest thread

Implement one feature that touches every layer. Not the most important feature, not the most impressive one — the simplest one that exercises the full stack.

For a web application, this might be:

One database table with one record
One API endpoint that reads from that table
One page that displays the result

Example: a walking skeleton for a book catalogue (click to expand)

Database: One table books with columns id, title. One seeded row: { id: 1, title: "The Hitchhiker's Guide" }.

API: One endpoint GET /api/books/1 that returns { id: 1, title: "The Hitchhiker's Guide" }.

UI: One page at /books/1 that displays “The Hitchhiker’s Guide.”

That’s it. No search. No listing. No editing. No styling. But the browser talks to the server, the server talks to the database, and data flows back to the screen. The skeleton walks.

3. Verify end-to-end

Run the skeleton. Click the button (or load the page). Does data appear? If yes, your architecture is validated. If not, you’ve found the problem early — before you’ve built dozens of features on top of a broken foundation.

Common problems a walking skeleton reveals:

Framework configuration issues (routing, middleware)
Database connection problems
Authentication/authorisation blocking data access
Build or deployment pipeline failures
Environment variable or configuration mismatches

4. Build on the skeleton

Once the skeleton walks, every subsequent feature adds to the proven foundation. Each new feature follows the same path (UI to API to database) but adds complexity: more endpoints, more pages, more data relationships.

Phase	What you add	What you’re testing
Skeleton	One feature, full stack	”Can the layers talk to each other?”
Second feature	A similar feature	”Does the pattern repeat?”
Third feature	A different shape of feature	”Does the architecture handle variety?”
Polish	Styling, error handling, edge cases	”Is it ready for users?”

Concept to explore

See vertical-slices for how each feature after the skeleton is structured as a complete slice through all layers.