Your first skill

Welcome. This page walks you through making your first skill in Skillmaker Studio — from one npx command to a drafted, honestly-measured SKILL.md — with an agent doing the production work and you making the calls. No prior setup, no cloned repo, no configuration files. Plan for a relaxed half hour; most of it is conversation.

A quick word on what you’re making. A skill is a SKILL.md file that teaches a coding agent (Claude Code, Codex, and compatible tools) how to do something your way. Skillmaker Studio’s wager is that the file itself is the least interesting part: the research behind it, the design reasoning, the eval fixtures that probe where it might fail, and the measured evidence that it works are the durable asset. Studio keeps all of that together in a Skill Bundle — plain files in a directory you own — and SKILL.md is one of its outputs.

Before you start

Two things need to be true on your machine:

Node.js (for npx) and git. Your skills live in a git repository — Studio will set one up for you.
A coding agent, installed and signed in. Studio’s conversations run through an agent you already have: either Claude Code or Codex. Install at least one and make sure it works on its own (claude or codex runs and is authenticated) before you start — Studio drives these tools; it can’t sign in for you. If chat never answers, this is the first thing to check: see Provider auth & troubleshooting.

And two things worth knowing before you’re surprised by them:

The agent works in your real project. Its edits land as actual files in the directory you choose — nothing is sandboxed away from you. That’s the point: everything it produces is yours, on disk, diffable.
You are the gate. The pipeline moves at human speed, on your say-so. Studio will never advance a skill past a stage without you.

1. Start the Studio

From any terminal, in any directory:

npx skillmaker-studio start

This starts a small local server and opens your browser to the Studio (default: http://localhost:4323). On a first run with nothing set up yet, you’ll land on a welcome screen with one button: Create your first project. Click it.

2. Create a project

A project is just a directory on your machine where your skills will live. The dialog lets you browse to an existing directory, type a path, or create a new folder right there. Pick or create one — a fresh, empty folder is perfect for today.

Don’t worry about preparing the directory: anything that isn’t already a Skillmaker workspace gets set up automatically when you click Create project (a git-friendly scaffold: one small config file and an append-only journal — more on that at the end).

3. Describe the skill you want

You’ll land on the new-skill launcher, which asks one question: What skill would you like to create? Tell us about it.

Write real sentences, like you’d brief a colleague. Not a slug, not keywords — the more intent you give, the better the conversation starts. For example:

A skill that writes release notes from merged PRs in my team’s voice: grouped by user impact, no commit-hash soup, honest about breaking changes.

The picker at the bottom of the box lists the agents Studio found on your machine — pick which model runs this skill’s sessions. Then send.

(If Studio spotted existing SKILL.md files near your project, it offers them under Import one of these? — a way to bring an existing skill under management. For your first run, describing something new is more fun.)

4. Meet the agent

Sending drops you onto the new skill’s page, and a chat opens on the right. Your brief arrives with a context chip attached — machine-written context telling the agent where it is: inside Skillmaker Studio, working on this bundle, at this stage, with its production guidance to read before acting.

This matters more than it sounds. A bare agent told “write release notes” would just… write release notes, once, for this repo. This agent knows its job is to build the reusable skill that does it — so its first move is to orient: it reads the bundle’s actual state and asks you the one question that moves things forward. Answer it. This is the rhythm of the whole pipeline: the agent produces, you decide.

(Closing the panel or the tab loses nothing — reopening the chat resumes the same session where you left off.)

5. Research — answer the open questions

First real station. The agent researches your skill’s domain: real sources, failure cases, the boundaries of what the skill should and shouldn’t do. Its notes land in research/notes.md, which you can watch fill in on the skill page’s Research tab.

Then comes the part to actually show up for: research ends with open design questions, and the agent brings them to you one at a time — ask, wait, fold your answer back into the notes, next question — until they are all cleared or explicitly parked. These answers are where your judgment enters the skill. Take them seriously; one honest “I don’t know, park it” beats a confident guess.

6. Design — co-author design.md

With research settled, the agent proposes the skill’s design and you shape it together in conversation: what the skill is for, when an agent should reach for it, the workflow it teaches, and — most valuable — your failure hypotheses: the specific ways you suspect it could go wrong. Those hypotheses become your evals in step 8.

The result is design.md — the why behind the skill, the document most skills never have. You can read it any time in the Files panel on the right.

7. Draft — SKILL.md appears

Now the agent drafts. output/SKILL.md — the actual skill text an agent will someday run — lands in the bundle, and the skill page’s Overview tab starts showing its summary. Read it. Push back in chat on anything that doesn’t sound like you; the draft is a conversation artifact like everything else here.

8. Evals — measure it honestly

This is the station that separates a Skillmaker skill from a pasted gist. The agent turns the design’s failure hypotheses into claims (a risk map of what the skill is supposed to get right) and fixtures — small concrete test scenarios that probe them.

Head to the Eval tab:

Each claim shows its coverage — and until fixtures have been run and graded, its measurement honestly reads not yet measured. That’s a feature, not a gap: Studio never lets “a test exists” masquerade as “it passes.”
Run all fixtures executes them against your chosen agent.
When runs finish, read each response and grade it — Pass or Fail, your judgment, recorded. Grade honestly; a real Fail is worth more than a polite Pass, because it goes straight back into the conversation as the next thing to fix.

The Evals section covers this whole machinery in depth when you want it.

9. Publish

The last station: putting the skill where your agents will actually find it. Publishing is gated the way everything else here is — the skill has to pass its final human gate first (record a version and move it through the last stage; the agent will drive this in chat when you say the word — see the production state machine).

Then, on the Publish tab, the Current draft row asks the only question that matters — publish to whom? — with two buttons:

All my agents — installs to ~/.claude/skills/<your-skill>/, so every agent on your machine can use it, in any project.
This project’s agents — installs to .claude/skills/<your-skill>/ inside this project only.

One honest thing to know before you click: this writes real files into that directory, exactly like installing a skill by hand — and if a copy is already there, re-publishing overwrites it (Studio warns you when the installed copy has been hand-edited since).

Your choice is remembered. From then on the row shows a single Publish button — re-publishing an improved version is one click — and each older version in the list gets a Revert button that re-installs its snapshot to the same place. Every publish is recorded in the journal, and every installed copy carries a provenance comment naming the bundle, the exact version, the date, and its evidence state — honestly, as “N of M claims measured.” Anyone who finds that file later can trace it straight back to the research, the design reasoning, and the grades you just made.

That’s the whole point, and the whole loop: not a pasted SKILL.md of unknown pedigree, but a skill with a paper trail.

Where everything lives

You’ve now seen the whole shape of the Studio; here’s the map of it.

The tabs are the stations. Overview is the skill’s front page (the draft’s summary), Research holds the notes and decisions, Eval holds claims, fixtures, runs and grades, Publish holds versions and evidence. Each tab shows the state of one leg of the pipeline.

The Files panel is the whole bundle. The right panel’s Files tab browses every file in the bundle — research, design, draft, fixtures, runs. Nothing on the skill page is anything other than a view of these files.

Everything is files in your project. The bundle is a directory (skills/<your-skill>/) inside the project directory you picked in step 2, plus an append-only journal (.skillmaker/events.jsonl) recording every decision. Commit them and your skill’s entire history — reasoning, evidence, and all — travels with your repo. See The Skill Bundle and The journal for the anatomy.

When something doesn’t work

Chat never answers, or no agents appear in the picker — your provider isn’t installed or isn’t signed in. Fix it standalone first, then restart: Provider auth & troubleshooting.
On Windows — support is new and lightly tested; if something breaks, please open an issue with what you saw. That genuinely helps.
Anything else that stopped you or confused you — we want to hear it, at the same place. You are exactly the reader this page was written for.

Where to next

The production state machine — how a skill moves idea → researching → drafting → evaluating → published, and why every move waits for you.
Adopting an existing repo — bring the skills you already have under management.
CLI Reference — every station on this page has a terminal door.