CommitCycle Insights

The instruction you write once instead of every session

Tue, 18 Aug 2026 00:00:00 GMT

There is a moment every few days where you type the same correction again. Use our button component. Do not add a dependency for that. The dates in this project are always ISO. You said it on Tuesday, the session ended, and the knowledge ended with it.

A skill is that instruction, written once, in a file the agent picks up on its own when it becomes relevant.

That is the whole concept, and the rest of this page is the mechanics, the judgement about what belongs in one, and the debugging — because the failure mode is not writing a bad skill, it is writing a good skill that never loads.

What a skill is on disk

A folder with a markdown file in it:

.claude/skills/
  cc-brand/
    SKILL.md
    references/
      token-reference.md
      motion-and-craft.md
      cc-tokens.css
    assets/
      AppShell.vue

SKILL.md opens with frontmatter carrying two things that matter:

---
name: cc-brand
description: Implements UI in the CC design system for Vue. Use this WHENEVER
  building, styling, theming or reviewing any Vue interface, component, page,
  dashboard or form for CommitCycle — and whenever the user mentions CC UI, the
  brand blue (#693DFF), Plus Jakarta Sans, shadcn-vue, or "make this on-brand".
---

# CC Design System Implementor

Everything the agent should know, in ordinary markdown.

Nothing else is required. No build step, no registration, no configuration file. The folder exists, so the skill exists.

Why not just put it in the prompt?

Because you have to remember, every time, and you will not. More precisely: the times you forget are not random. They are the times you were moving fast, which are the times the agent had least context, which is exactly when the convention mattered most.

Why not just put it in AGENTS.md?

This is the real question, and the answer is the design of the whole feature.

AGENTS.md (or CLAUDE.md) is always loaded. Every turn, every session, every task, whether relevant or not. That makes it perfect for facts that are always true — the stack, the commands, the folder layout, the things never to do — and it means every line you add costs context on work that has nothing to do with it. A 900-line AGENTS.md is a tax on every request.

A skill is loaded only when it matches. What is always in context is its name and description — a couple of lines. The body is read only when the agent decides the task calls for it.

This is called progressive disclosure, and it works in three levels:

Level	What loads	When
1	Name + description	Always. Costs almost nothing
2	The SKILL.md body	When the description matches the task
3	Bundled files in the folder	When the body points at them and the task needs them

Which is why a skill can be enormous — a full design system, a compliance checklist, an API’s entire surface — without slowing down a request about something else. You are carrying a library, not a note.

What belongs where

The judgement that makes all of this work:

Put it in	When	Example
The prompt	True for this one task only	“Use blue for the header on this page”
AGENTS.md	Always true, always relevant, short	“Stack is Astro + Tailwind. Never edit files in `dist/`”
A skill	True in a specific situation, too long for AGENTS.md	Your complete design system, your API conventions, your writing voice
An MCP server	The agent needs to reach something	Your database, your issue tracker, your analytics

The common mistake is putting design-system-sized content in AGENTS.md, where it is loaded on every request including the ones about a build script. The other common mistake is putting the project’s stack in a skill, where it might not load at the moment it is needed.

The description is the whole trigger

If you take one thing from this page: the description is not documentation, it is the matching rule. It is the only part of your skill the agent sees before deciding whether to read the rest.

So write it in the words a person actually types. Not:

Brand implementation guidelines and component standards.

That matches nothing. Someone asking “make this look like our app” has not used any of those words. Instead:

Use this whenever building, styling, theming or reviewing any interface, page, dashboard, form or component for [product] — and whenever the user mentions [the brand colour], [the font], [the component library], or “make this on-brand”. Reach for it even when the request is just “build a settings page” or “style this card”.

Concretely, a description that fires reliably names:

The verbs — building, styling, reviewing, migrating, drafting
The nouns — the artefacts it applies to
The literal strings — product names, hex codes, font names, library names
The informal phrasings — “make it on-brand”, “the usual way”, “like the other pages”
When to use it even though it does not look like it applies — this line does a surprising amount of work

Being over-inclusive costs a little context when it fires unnecessarily. Being under-inclusive costs you the entire skill, silently, forever. Bias towards firing.

Where skills live

Two places, and the choice matters more than it looks:

.claude/skills/ inside the project. It commits with the repository, so it is present on your other machine, in every future session, and for anyone else who clones it. Anything that describes this product belongs here.

~/.claude/skills/ in your home directory. Available in every project you touch, invisible to everybody else. This is for your own working style — how you like commits written, how you want documents structured.

The default should be the project. A skill that lives only on your laptop is one machine away from not existing, and it is the reason a project “only works properly when you run it”.

How do I know it fired?

Ask. Which skills did you use for that? is a reasonable question and gets a straight answer. What skills do you have available? lists them, which is the first check after installing one.

The stronger check is behavioural: start a fresh session, phrase a request the way a real user would — not the way the skill’s own documentation phrases it — and see whether the output follows the rules without you mentioning them. That is the only test that matters, because that is the actual condition of use.

Why is my skill not firing?

Symptom	Almost always	Fix
Never loads	Description does not contain the words being typed	Rewrite the description with real phrasings and literal names
Loads, then the output ignores it	SKILL.md is too long or the rules are buried in prose	Cut it. Lead with the rules. Move detail into `references/`
Loads on everything	Description is too broad	Add the boundary: what this is not for
Works for you, not for a colleague	It is in `~/.claude/skills/`, not the project	Move it into the repository and commit it
Contradicted by other instructions	AGENTS.md says something different	Decide which wins and say so explicitly in both

Notice that four of the five are description or placement problems. The content is rarely what is wrong.

Keeping SKILL.md short

Once loaded, the body is read in full — so length costs something, and the good structure is a short instruction file that points at detail.

SKILL.md              the rules, the decision order, what wins in a conflict
references/           the long material: token tables, API surfaces, examples
assets/               things to copy: components, stylesheets, templates
scripts/              things to run

The cc-brand skill in the example above is exactly this shape: the SKILL.md states the layer priority and the conflict rule in a few hundred words, and the token reference, the motion guidance and the ready-made shell components sit in files it points at. The agent opens the sidebar reference when it is building a sidebar and never otherwise.

Two things belong in SKILL.md rather than a reference file: the order of precedence (when two rules collide, which wins) and what not to do. Both are short and both are what the agent gets wrong when they are missing.

Skills, MCP, subagents, slash commands

Four things that get confused, on genuinely different axes:

	What it is	Who triggers it
Skill	Instructions loaded on relevance	The agent, by matching the description
MCP server	Tools that reach external systems	The agent, when it needs the tool
Subagent	A separate context window for delegated work	The agent, or you
Slash command	A saved prompt you invoke by name	You, explicitly

Skills and MCP are complements rather than alternatives. The MCP server gives the agent a connection to your database; the skill tells it your schema conventions and which tables are never written to directly. Tools without instructions is the configuration most people have, and it is why the agent can reach everything and still do the wrong thing with it.

Installing one somebody gave you

Put the folder in .claude/skills/ (project) or ~/.claude/skills/ (personal).
Start a new session — an existing one has already built its list.
Ask what skills do you have available and check yours is listed by name.
Give it a realistic request and see whether the rules apply without being mentioned.

If step 3 fails, the folder is in the wrong place or SKILL.md is misnamed. If step 4 fails, it is the description.

The one worth installing on day one is a design skill. If you have an idea but no brand and no visual opinion yet, startpow.com will let you pick what you like, export, and download the result as a skill. Drop it in, and every screen the agent builds from then on arrives in your colours, your type and your spacing without you describing them again — which is roughly the difference between a product and a demo, for about ten minutes of work.

How many skills is too many?

There is a real budget, and it is not the one people worry about. The bodies are free until they load, so a folder of forty skills does not slow anything down. What is not free is the descriptions, which are all in context, all the time.

Forty vague descriptions is worse than five sharp ones for a second reason too: the more of them overlap, the less reliably the right one wins. Two skills that both plausibly cover “styling” means a coin toss on every UI request.

The practical shape is a handful of skills with clean boundaries, each of which you could describe in one sentence without using the word “and”. When you cannot, that is two skills.

A skill is instructions you agree to run

Worth saying plainly, because skills get passed around like themes and they are not themes.

A skill is a set of instructions an agent will follow, with your permissions, in your repository. A downloaded skill can tell an agent to install a package, to send a file somewhere, to treat a rule as more important than the ones you wrote. That is the same trust decision as running a script somebody sent you, and the fact that it is markdown rather than code makes it feel smaller than it is.

So: read SKILL.md before you install it, look at whatever else is in the folder, and be more careful with skills that ship scripts than with skills that ship documentation. A design system from a tool you chose is a very different proposition from a skill pasted into a forum thread.

The same applies in reverse when you publish one — anyone installing yours is extending you that trust.

Getting them to a team

Three routes, in increasing order of ceremony:

Commit them to the repository. .claude/skills/ is in the repo, so cloning gets them. This covers most cases and needs no infrastructure at all.
Ship them in a plugin. A plugin can carry skills along with commands and MCP servers, installed by name and updated centrally. Right when several repositories need the same conventions.
Send the folder. Fine once, unmanageable by the fourth person, because there is now no answer to “which version do you have”.

The failure to avoid is the one where the skill exists only in one person’s home directory. The project then behaves differently depending on who is driving, and nobody can see why.

The fastest way to write your first skill

Do not start from a blank page. Blank pages produce generic rules, and generic rules are the ones the model already follows.

Instead: work normally, and pay attention to what you correct. The third time you say the same thing — the third time you point out the date format, or the component, or that we do not use that library here — say:

Turn what you just learned into a skill. Write the description so it fires whenever someone asks for anything in this area, including informal phrasings. Keep SKILL.md short and put the long detail in a references file.

Your corrections are already the exact content a skill needs. They are specific, they are real, and they are the ones that were actually being got wrong — which is a much better starting set than anything you would think to write in advance.

Hacks that make a real difference

Show, do not only tell. One worked example of your convention outperforms three paragraphs describing it. Models are extremely good at pattern-matching from an example and merely obedient about following a rule.
One skill per concern. A single “our standards” skill covering design, testing and deployment fires on everything and applies to nothing well. Split it.
Say what wins. Every skill that contains more than one source of guidance needs a sentence saying which one takes precedence in a conflict. Without it, the model picks, and it picks differently each time.
Write the negative rules. Do not introduce a second component library. Do not add dependencies for something the standard library does. Negative constraints are followed more reliably than positive ones and are almost always the thing you actually cared about.
Version it with the code it describes. A design skill in the repository changes in the same commit as the tokens it documents. A design skill on your laptop drifts within a fortnight and then confidently teaches the agent last month’s colours.
Test with a cold session and a lazy phrasing. “make the settings page” is how the request will really arrive. If the skill needs the well-formed version to fire, it does not work.
Let old skills die. A skill describing a convention you abandoned is worse than no skill: it is a confident, always-available instruction to do the wrong thing.

If you are not on Claude Code

Skills-as-folders are a Claude Code feature. Other agentic tools read a single always-loaded instructions file, and the near-universal convention is AGENTS.md at the root of the repository.

The content transfers directly. What does not transfer is the selective loading — everything in that file is paid for on every request — so the discipline is different: keep it to what is always true, put the long material in ordinary documentation, and point at it from the file rather than pasting it in.

Either way, the underlying move is the same one, and it is the highest-leverage habit in agentic development: the second time you explain something, write it down where the agent will find it. The rest of the setup that sits around this — the repository, the model, the host, the stack, the guardrails — is six decisions long.

GitHub for people who do not write the code

Tue, 18 Aug 2026 00:00:00 GMT

If you have never used GitHub, ignore how it is usually described. It is not a social network for programmers, you are not there to read anyone else’s code, and the green squares are not a scoreboard you have to fill.

It is a save system with a history, hosted somewhere that is not your laptop. That is the whole thing.

For a vibe coder it earns its place for one specific reason. At some point — not maybe, at some point — a session will rewrite something that already worked. It will refactor a file you liked, delete a function it decided was unused, or fix one bug by quietly introducing two. Without commits, that work is gone and your only recovery is describing it again from memory to a model that has forgotten the conversation. With commits, recovery is one sentence.

This guide is everything you need for that, and nothing you do not.

Git and GitHub are not the same thing

Worth ten seconds, because conflating them is what makes the rest confusing.

Git is a program on your computer. It records versions of a folder. It works with no internet, no account and no website, and it is what does all the actual work.

GitHub is a website that holds a copy of a Git repository, and adds the things a website can add: a page to browse it, a place for other people, automation that runs when you push.

So when your agent “commits”, that is Git, locally, instantly. When it “pushes”, that is the copy travelling to GitHub. This is why you can work on a plane and why a commit is not a backup until it has been pushed.

The alternatives — GitLab, Bitbucket, Codeberg — are the same Git underneath with a different website on top. Nothing in this guide changes if you pick one of those.

The seven words that cover almost everything

Word	What it actually is
Repository (“repo”)	Your project folder, plus every version it has ever been
Commit	A save point with a note attached
Branch	A copy of the project where you can break things safely
Push / pull	Sending your commits up to GitHub / bringing others’ down
Clone	Downloading a whole repository, history included
Pull request (“PR”)	“Here is a change, look at it before it goes in”
Merge	Folding one branch’s commits into another

Two more you will see and can mostly ignore: origin is the default nickname for “the copy on GitHub”, and main is the default name of the primary branch.

Do I need to learn Git commands?

No, and this is the part nobody tells beginners. You need three sentences to say to your agent, and it runs the commands.

Commit this with a clear message.
What has changed since the last commit?
Undo everything since the last commit.

That is the entire interface for your first month. What you do need is to understand what those three things mean, which is what the rest of this page is for — because the failure mode is not typing the wrong command, it is asking for the wrong kind of undo.

If you would rather have buttons than sentences, GitHub Desktop is free, shows changed files as a visual diff, and turns commit and push into two clicks. Many people who ship real products never use the terminal for Git at all.

Where your code lives while you are working

Git messages talk about files being “staged”, “tracked” and “untracked”, and none of it makes sense until you know there are three places a change can be:

Place	What it means	How it leaves
Working directory	You (or the agent) edited the file. Nothing is recorded	`git add`
Staging area	Marked as part of the next commit, but not saved yet	`git commit`
Committed	Recorded in history permanently	`git push` sends it to GitHub

The staging area is the part that feels pointless at first. Its purpose is choosing: twelve files changed, four of them belong to this commit, so you stage those four. As a vibe coder you will mostly commit everything at once — but you need to know staging exists, because “changes not staged for commit” is otherwise an error message about nothing.

git status is the “where am I” command, and it is the one worth being able to read yourself. It tells you which branch you are on, what is changed, what is staged, and whether you are ahead of or behind GitHub. When something is confusing, this is the first thing to look at, and it is completely safe — it changes nothing.

The first file that matters: .gitignore

Before your first push, before anything else: .gitignore is a list of files Git must never record.

At minimum it contains:

.env
.env.local
node_modules/
.DS_Store
dist/

.env is the one that matters. That is where your API keys live, and that one line is what stops them from being published the first time you push. Public repositories are scanned continuously by people looking for exactly this, and a leaked key is found in minutes, not days.

Ask for it explicitly at setup — add a .gitignore appropriate for this stack, and make sure .env is in it — and then check with your own eyes that .env is listed. This is a thirty-second check that prevents the single most common expensive beginner mistake.

Make the repository private by default. Public is a deliberate decision to publish, and it is far easier to make a private repository public later than to un-publish something — including everything in its history.

How do I read a diff without reading code?

A diff is what changed, shown line by line. Green lines with + were added, red lines with - were removed, grey lines are unchanged context. You do not need to understand the code to get real value from it:

How big is it? Twelve lines changed for a small ask is normal. Four hundred is a signal to stop and ask what else it did.
Which files? If you asked for a colour change and a file with auth or migration or schema in the name is in the list, that is the moment to ask why.
Anything deleted that you did not ask to delete? Long blocks of red are worth a question.

That is the whole skill, and it is most of what code review gives you on a solo project. Show me the diff, and explain in plain English what each file’s change does is a good habit before every commit.

What makes a commit message worth writing?

Its only job is to help future-you find a moment in time. “Update” and “fixes” fail at that; six of them in a row are indistinguishable.

Write what the state is, not what you did: login screen works, validation not done yet. Six weeks later, that message is what lets you say “go back to when login worked” and mean something precise.

Commit when something works, not at the end of the day. The end of the day is one save point for eight hours of decisions. Every working state is a place you can return to.

When do I actually need a branch?

As a solo vibe coder, less often than tutorials imply. You need one when you are about to try something you might regret — a big refactor, a risky dependency swap, an experiment you are only half sold on.

The reason is that the undo becomes free. You are on experiment, it goes badly, you switch back to main and delete the branch. Nothing to unpick, nothing to revert, no argument with the agent about what it changed.

The moment anyone else touches the repository, this stops being optional and becomes one branch per piece of work — which is where vibe coding gets genuinely harder, and a different problem from this one.

How do I undo something?

The most important section on this page. There are four kinds of undo and asking for the wrong one is how people lose work while trying to save it.

1. You have changes you have not committed, and you want them gone.

git restore .

Everything since the last commit disappears. This is the everyday one — the session went wrong, nothing was worth keeping, start again from the last good state.

2. You committed, but have not pushed, and want the commit gone.

git reset --soft HEAD~1   # undo the commit, keep the changes
git reset --hard HEAD~1   # undo the commit and the changes

--soft is for “right commit, wrong message, wrong moment”. --hard is for “that whole direction was wrong”.

3. You already pushed, and other people (or a deployment) have it.

git revert <commit>

This makes a new commit that undoes the old one. It is the safe one, because it adds to history rather than rewriting it, and nothing anyone else has ever disagrees with what you have.

4. You think you have lost something permanently.

git reflog

Git keeps a private log of every position your branch has been in for around ninety days, including commits you “deleted” and branches you removed. Almost nothing is ever actually gone. This is the one to reach for after a --hard you regret or a force-push that ate your afternoon — and it is worth knowing it exists precisely because the moment you need it is the moment you are panicking.

What is a merge conflict, and who fixes it?

Two branches changed the same lines. Git will not guess which version wins, so it marks the disputed section in the file with <<<<<<< and >>>>>>> and stops.

Nothing is broken and nothing is lost. Both versions are right there; something has to choose.

Agents are good at this, on one condition: tell them what each change was for. The decision is about intent, not syntax — this side is the new pricing logic, that side is the bug fix from yesterday, keep both behaviours gets a correct resolution. “Fix the conflict” gets a coin toss.

What happens if I commit an API key?

Rotate it. Now. Go to the service, revoke the key, issue a new one.

Deleting the file in a later commit does nothing, because the key is still sitting in the history where anyone can read it. On a public repository, assume it was scraped within minutes — this is automated at scale.

GitHub helps at two points, and both are worth turning on. Secret scanning notices known key formats in your repository and alerts you. Push protection goes further and blocks the push before the secret ever lands. Neither covers every format, so .gitignore remains the actual defence.

Cleaning the key out of history afterwards is possible and fiddly. It is also secondary: once the key is rotated, the one in the history is a dead string.

What else is GitHub, beyond storage?

Things you will meet, in one line each:

Issues — a to-do list attached to the project. Fine for solo notes, though a real board is better once work has shape.
Actions — automation that runs on push. This is how tests run and how deploys trigger. You will meet it the first time you connect a host.
Releases and tags — a name pinned to a specific commit. v1-launch is a bookmark saying this version was good, and it costs nothing.
Pages — free static hosting straight from a repository. Fine for a landing page, not for anything with a backend.
Fork — your own copy of somebody else’s repository. Relevant when you want to change someone’s open source project.
Dependabot — opens pull requests when a dependency has a security fix. Free, worth leaving on.
Codespaces — a full dev environment in the browser. Useful when you want to work from a machine that has nothing installed.

Things that will confuse you exactly once

Each of these produces a moment of genuine alarm, and each is harmless once you have seen it.

“You are in ‘detached HEAD’ state.” You looked at an old commit and are now standing on it rather than on a branch. Commits made here belong to nothing and are easy to lose. git switch main walks back. Nothing is broken.

Your repository contains another repository. An agent ran git init inside a folder that was already in a repo, usually while scaffolding something. GitHub then shows a folder you cannot open, containing nothing. The fix is deleting the inner .git folder — and the tell is a commit that adds a directory but none of the files in it.

A file is too large to push. GitHub rejects individual files over 100MB, and a video, a database dump or a node_modules that escaped .gitignore will hit it. The trap is that removing the file does not fix the push, because it is still in the history — the commit that added it has to be undone. Much easier to prevent: check .gitignore before the first push.

Your two machines disagree. You committed on the laptop, pushed, then committed on the desktop without pulling. Git will refuse the second push. git pull first, resolve anything it asks about, then push. The habit that avoids it entirely is pulling at the start of a session rather than at the end.

The agent committed as somebody else. Commits carry the name and email in your local Git config, which on a fresh machine may be blank or wrong. Worth setting once, or your history is authored by “unknown”.

Hacks that pay for themselves

Commit before every agent session, not after. The commit is not a record of what you did, it is the save point you are about to risk. Ten seconds, and it converts every disaster into git restore .
Ask for the diff before you accept. Show me what you changed and why catches the helpful extra thing you did not want, which is the most common failure that survives to production.
One branch per experiment, and delete is the undo. Cheaper than any revert.
git stash when the agent complains about a dirty tree. It pockets your uncommitted work; git stash pop gives it back. Better than committing junk to get unstuck.
--force-with-lease, never plain --force. Both rewrite what is on GitHub. The first refuses if someone else pushed in the meantime; the second overwrites them without asking.
Protect main once anything real is on it. GitHub’s branch protection can require a pull request before merging, which makes “the agent pushed straight to main at 2am” structurally impossible rather than merely discouraged.
Tag the version that worked. Before a big change, v-works costs nothing and is trivially findable, unlike a commit hash you will never recognise.
Squash when you merge. Fourteen commits of “wip”, “fix”, “actually fix” collapse into one meaningful entry, and your history stays readable by a human — and by the next agent that reads it.
Remember reflog exists before you need it. The moment you need it, you will not be in a state to discover it.

What to do on day one

Create the account. Make the first repository private.
Get .gitignore in place with .env in it, and check with your own eyes.
Ask the agent to make the first commit and push it. Look at the repository on GitHub and see your files there.
Then, every time something works: commit this with a clear message.

That is the whole practice. Everything else on this page is there for the day something goes wrong — and the reason to read it now is that the day something goes wrong is a bad day to be learning which kind of undo you need.

The rest of the setup this fits into — the model, the host, the stack, the guardrails — is six decisions long, and version control is the one that everything else assumes you already have.

Six decisions before your first prompt, and why each one is there

Tue, 18 Aug 2026 00:00:00 GMT

Nobody wants to spend an afternoon on setup. The pull is to open a chat and start describing the thing, and for a prototype that is the right instinct — the first week has its own post and most of the advice there is go faster.

This is the other post. It is for the moment you decide the thing will still exist next month, and it is six decisions. Each takes minutes. Each closes off a specific way week two goes wrong, and the reason to make them together is that all six are cheap now and expensive later.

None of them is about which model is best.

1. GitHub, which is an undo button you can talk to

If you have never used it, ignore how it is usually described. GitHub is not a social network for programmers and you are not there to read anyone’s code. It is a save system with a history, hosted somewhere that is not your laptop.

Five words cover almost everything you need:

Repository — your project folder, plus every version it has ever been.
Commit — a save point with a note attached. “Login screen works” is a commit.
Branch — a copy of the project where you can break things without breaking the original.
Push / pull — sync between the copy on your machine and the copy on GitHub.
Pull request — “here is a change, look at it before it goes in.” You will not need this alone; you will need it the day somebody else touches the project.

Here is why a vibe coder specifically cares. At some point — not maybe — a session will rewrite something that already worked. It will refactor a file you liked, or delete a function it decided was unused, or fix one bug by introducing two. Without commits, that work is gone and your only recovery is describing it again from memory. With commits, recovery is one sentence.

Which brings up the part nobody tells beginners: you do not have to learn Git. You have to learn three sentences to say to your agent.

Commit this with a clear message.
What has changed since the last commit?
Undo everything since the last commit.

That is the whole interface for the first month. The agent runs the commands.

Set it up like this and stop thinking about it: create the account, make the repository private by default, and before anything else make sure .env is in .gitignore. That single line is what stops your API keys from being published the first time you push. Keys leak from beginner repositories constantly, and they are scraped within minutes.

Then one habit, which is the highest-leverage thing in this entire post: when something works, commit it. Not at the end of the day. At the moment it works.

That is enough to start with. The rest of it — reading a diff without reading code, the four different kinds of undo and when each applies, what to do the day you commit an API key — is the full guide.

2. One model, and it matters less than you think

Claude Code, Codex, or an open-weights model you run yourself. The honest framing: this is the one decision you can reverse for free. The repository is portable, your prompts are portable, and nothing you build is locked to the tool that wrote it.

What actually separates them is not benchmark scores, it is whether the tool lives in your project:

	What it is	Where it fits
Claude Code	Agentic CLI in your terminal, reads and writes your files, runs commands	Building whole features across many files
Codex	OpenAI’s agentic equivalent, terminal and cloud	Same job, different house style
Open weights (via Ollama, LM Studio, and a client like Aider or Cline)	Models running on your machine or your own server	Privacy, cost control, no per-token bill

The recommendation: pick one paid agentic tool and stay on it for a month. Not because the others are worse, but because the skill you are building is knowing what to ask for and how to tell when the answer is wrong, and that skill transfers slowly while you are still switching tools every week.

On open source, being straight: it is real, it is cheaper, it is private, and it is the wrong first move. You will spend your first week on setup instead of on the thing you wanted to build, and long agentic tasks — many files, many steps, hold the plan the whole way — are exactly where the gap is still widest. Come back to it in month two, when you know what you are comparing.

And whichever you pick, the leverage is not in the model. It is in what the model can see about your project, which is decisions 4, 5 and 6.

3. One host, and one account if you can manage it

You will need somewhere to put it. The two obvious answers are Cloudflare and Vercel, and the deciding question is not performance.

It is how many accounts you want to hold.

Cloudflare is the all-in-one: hosting, a database (D1), file storage (R2), key-value, the domain itself, DNS, email routing — one login, one bill, one place where things are wrong when they are wrong. For someone starting out, that consolidation is worth more than any individual feature. The price is a runtime that is not quite Node, so a handful of npm packages will not run there, and you find out at deploy rather than at install.

Vercel gives you the smoothest deploy in existence if you are on Next.js. The trade is that the data pieces come from marketplace partners, so the database is somebody else’s dashboard, storage is another, and you will be reconnecting three services on a Sunday evening trying to remember which one has the failing credential.

Pick Cloudflare unless you have a specific reason to be on Next.js.

And buy the domain on day one, from the same provider. It costs about ten euros, it takes four minutes, and it changes how you treat the project. A thing with a domain is a thing that exists.

4. A stack — chosen by you, written down

The temptation is to leave this to the model. Do not, and the reason is not that its choice would be bad.

It is that the model chooses per conversation. Monday’s session picks Next.js. Wednesday’s session, with no memory of Monday, picks Vite and React Router. Friday’s adds a component library that duplicates the one you already have. Nothing errors when this happens — you just end up with a project that is three projects wearing a trenchcoat, and every future session has to guess which convention it is in.

So: React + Tailwind, and tell the model to use shadcn/ui.

Why that specific combination, when plenty of others are perfectly good:

It is the best-documented combination in any model’s training data. You are choosing the region of the map where the model is at its most accurate and least inventive, and that is worth more than any technical advantage on day one.
Tailwind keeps styling in the markup, so when you say “make this card tighter”, the agent changes one line in the file you are looking at instead of hunting a stylesheet.
shadcn components are copied into your repository, not installed as a dependency. This is the underrated part. When you ask for a change to a button, the agent edits your button. With a traditional component library, it has to fight the library’s API, and it will usually lose by wrapping it in three layers of nonsense.

One exception, and it is a common one. If what you are building is mostly content — a site, a landing page, a blog, a documentation set, with a small admin area attached — use Astro instead. It ships almost no JavaScript by default, the pages are fast without you doing anything, and it scales into a real application when you need it. This site is Astro.

Skills: how you stop repeating yourself

A skill is a folder with a SKILL.md file in it that your agent reads only when it is relevant. That last part is the whole point: it is instructions that are available without being in the way.

The anatomy is small. A file at .claude/skills/<name>/SKILL.md, starting with:

---
name: my-design-system
description: Use when building or restyling any UI in this project —
  colours, typography, spacing, component patterns.
---

Everything the agent should know, in plain markdown.

The description is the important line, because it is what the agent matches against to decide whether to load the skill at all. Vague description, skill never fires.

Two places to put them: .claude/skills/ inside your project, which means it is committed to GitHub and it is still there tomorrow and on your other machine, or ~/.claude/skills/, for things you want in every project you touch. Prefer the project one — a skill that describes this product belongs with this product.

To install one somebody gave you: drop the folder in, start a new session, and ask what skills do you have available. If it does not list, the description is the first thing to check.

That is the shape of it. Why the description is the only part that always loads, what belongs in a skill versus AGENTS.md, and the fastest way to write your first one — the full guide.

(Skills are a Claude Code feature. If you went with Codex, the equivalent lever is the AGENTS.md file described in the bonus section — same idea, less selective loading.)

The design one is worth doing on day one. If you have an idea but no brand, no colours and no visual opinion yet, go to startpow.com, pick what you like, export, and choose the skill download. Drop it in .claude/skills/. From that moment every screen the agent builds arrives in your colours, with your type and your spacing, without you describing them again — which is the difference between a product and a demo, and it costs about ten minutes.

5. Something that remembers, so tomorrow is not a rebuild

Here is the failure this decision is about, and it is worth being precise because the popular version is wrong.

The model is not malicious. It is agreeable and fast, in places where being wrong is expensive. The database does not get dropped by a rogue AI; it gets dropped because a migration was broken, dropping the table was the shortest path to a passing test, and nobody was asked. Auth does not get rewritten in an act of sabotage; it gets rewritten because a test was failing and the auth check was what was failing it.

Two layers of defence, and the first one is free:

The habits. A development database that is not the production database. Production credentials the agent never holds. A commit before you start anything. And the instruction most people never give — what it must not touch. Models are agreeable; they will happily do a helpful thing you did not want.

The tooling. This is what CommitCycle is: work starts as a task with a declared scope, the agent gets access bound to that one task and one branch and it expires on its own, the paths that would actually hurt carry an owner who has to say yes, and every task closes with a record of what was declared against what was touched.

Now the honest limit, which is also the most important sentence here: it does not remove the possibility. The final responsibility is always the person who approves what the agent asks. The agent executes; you consent. What the tooling removes is the class of accident where nobody could have said no, because nobody was asked — and that class is most of them.

If you want it: /plugin marketplace add pow-paulinho/commitcycle-plugin, then /plugin install commitcycle@commitcycle, in Claude Code, or npm i -g commitcycle for the CLI. The hosted board is invitation-only while this is small.

6. Now what? Start with the shape, not the screen

You have the six pieces. The instinct is to prompt build me the homepage, and it is the wrong first move — not because the homepage is unimportant, but because it is a consequence of decisions you have not made yet.

The first useful question is: does this need accounts? Almost everything sorts into four surfaces from there.

Surface	What it is	Do you need it?
Public front	Everything visible without logging in	Almost always
Auth	Register, log in, reset password, verify email	Only if there is a “your” anything
The product	What people see after logging in	If auth, then yes
Admin	Where you see users, payments, problems	Yes, and everyone forgets until week two

If the honest answer is “mostly public front, small admin”, build it in Astro and do not add an authentication system you will maintain for one user. If it is “mostly product”, the auth and the data model are the first thing, because everything else hangs from them.

The prompts

First, the one that writes no code. This is the highest-value prompt in the whole process and it is the one most people skip:

I want to build: [describe it in three or four sentences, including who
it is for and what they pay for, if anything].

Do not write any code yet. Interview me — ask me the questions you need
answered to plan this properly, one batch at a time.

When you have enough, give me back:
1. The screens, grouped into public / auth / product / admin
2. The data model, as a list of entities and how they relate
3. Any third-party service this needs and why
4. What you would build first, and what you would deliberately leave
   until later

You are making the model produce a question, and reviewing a question is far cheaper than reviewing three hundred lines of an answer built on an assumption you never saw.

Second, the foundation. Deploy the empty thing on day one — “getting it live” should never become its own project later:

Set up the project skeleton:
- [Astro | React + Vite], TypeScript, Tailwind, shadcn/ui
- Deploy target: Cloudflare
- A Git repository with a first commit, pushed to GitHub

Get an empty page deployed and give me the live URL before adding
any features.

Then write AGENTS.md at the root recording: the stack and the versions,
the folder layout, the naming conventions, the commands to run and
build, and anything you should never do in this project.

Do not add authentication, a database or any dependency beyond the
above yet.

Third, the surfaces that need a system behind them:

Build registration and login: sign up, log in, log out, password
reset, email verification.

Use [the auth provider you picked] rather than rolling it yourself.
Screens use our existing components — do not introduce a second
component library.

Also give me the smallest admin page that lists users, because I
need to be able to see whether this works.

Do NOT touch: payments, the marketing pages, anything under [path].
If you hit a decision I have not made — pricing, session length, what
happens to unverified accounts after a week — stop and ask instead of
choosing.

Notice the two lines that almost nobody writes: what it must not touch, and stop and ask instead of choosing. Those two lines prevent more rework than any amount of prompt-engineering finesse.

Fourth, once it works, make it yours: install the design skill and ask for one screen to be restyled with it. Check that one. Then let it run at the rest.

7. User stories, which is where this gets real

If you can narrate what a person does, you can build it. Take the user’s own sentence:

Someone sees an ad, lands on the site, creates an account, subscribes to a plan, pays by card, and their subscription unlocks.

Read it again slowly, because that one sentence is a specification. It contains:

A landing page that the ad points at, which is not the homepage
Registration, and therefore verification, and therefore email that actually arrives
Probably onboarding, because a new account with nothing in it is where people leave
A payment provider — Stripe, in practice — and a checkout
A webhook, because the payment succeeds on Stripe’s servers and your app has to find out
Entitlement: some state that says this account is now a subscriber
Feature gating driven by that state, in every place it matters
The failure path: card declined, payment succeeded but the webhook did not arrive, subscription cancelled mid-month
An admin view, so that when someone emails you saying they paid and nothing unlocked, you can look

One sentence, nine work items, and the last three are the ones that get discovered in production by a customer if nobody wrote them down.

This is also work the model does well — hand it the story and ask what it implies, and it will produce a list very like the one above. What it cannot do is remember the list next Tuesday. That is what a board is for: each item becomes a task with a scope, a task becomes a branch, and the branch closes with a record of what it actually changed.

This sounds boring. It is, a bit. And in the interest of not overselling: three prompts genuinely can give you something that runs and looks good, and the hit of watching it work is real and worth having. Go and have it.

But the thing that is still standing in month three, that you can hand to somebody else, that you can change without holding your breath — that one was built by somebody who wrote down what it was supposed to do. Consistency is unglamorous and it is the entire difference.

Bonus track

Small things, in rough order of how much regret they prevent:

AGENTS.md at the root of the repository. The single highest-return file you will write. Stack, conventions, commands, and the list of things never to do. Every agentic tool reads it. Ours keeps the zone map there and writes the active task to a gitignored CLAUDE.local.md, cleared at hand-in, but a hand-written one is already most of the value.
Two databases from the very start. Development and production, never the same credentials, and the agent only ever holds the development one. This is the specific defence against the specific disaster.
Secrets never in the repository. .env in .gitignore, real values in your host’s secret store. Rotate anything that ever got committed — deleting the file does not remove it from the history.
Preview deploys per branch. Both Cloudflare and Vercel give you a URL per branch free. Seeing the change on a real URL before it is live is worth more than any amount of local testing.
Let the agent see what it built. Screenshots, or a browser tool it can drive. An agent building UI without ever looking at it is working blind, and it shows.
Error tracking, plus exactly one analytics number you actually look at. Anything more than one and you will look at none of them.
Terms and a privacy policy before you take a card. Stripe will ask for a working site with them before it activates the account, and finding that out on launch day is a bad day.
Know your restore, not just your backup. An untested backup is a belief, not a backup.
One decisions file. Three lines per decision: what, why, what you rejected. Six weeks later it is the only thing standing between you and re-litigating everything with a model that was not there.
Expect the model to cost more than the hosting. That ratio is correct and it is not a sign you are doing it wrong.

The whole setup above is an afternoon. What it buys is that the second week is a continuation rather than an archaeology project — and if you want the habits that go on top of it, that is the first-week post.

Vibe coding, and the first week that does not end in a mess

Fri, 14 Aug 2026 00:00:00 GMT

Vibe coding is building by describing what you want and accepting what the model writes without reading all of it. The term is Andrej Karpathy’s, and the distinguishing feature is not that AI wrote the code — that is now ordinary — but that nobody reviewed it line by line.

That is a trade, not a mistake. Whether it is a good trade depends entirely on one question: how long does this code have to live?

Where does vibe coding actually work?

Prototypes you intend to delete. The cost of being wrong is that you throw it away, which you were going to do anyway.

Scripts and one-off tools. A thing that reshapes a CSV, seeds a database, scrapes a page once. If it produces the right output you are done; nobody is going to maintain it.

Learning the shape of something unfamiliar. Getting a working example of a library you have never used is faster this way than reading the docs first, and you can read the docs after with a concrete thing in front of you.

Anything where the feedback is immediate and total. If it works, it works, and you find out in ten seconds.

The common thread is that being wrong is cheap and obvious. That is the condition. Not the size of the project, not the language, not whether it is “real” — just whether a mistake shows up immediately and costs little.

When does it stop working?

The moment the code outlives the session that produced it.

This is not a moral point. It is arithmetic: you bought speed by skipping understanding, and the bill arrives when somebody has to change code that nobody understood when it was written. If nobody ever changes it, the bill never arrives and you got the speed for free. That is a real outcome and it happens a lot.

What makes it go wrong is not knowing which case you are in. Most bad experiences start as a prototype that quietly became load-bearing while nobody was deciding anything.

How do I tell which case I am in?

Three questions, and they are about the situation rather than the code:

Ask	Vibe coding is fine when	It stops being fine when
How fast do I find out I am wrong?	Seconds. You run it and see	Weeks, via a customer
What does being wrong cost?	You delete it and start again	Money, data, or somebody’s trust
Who else depends on this?	Nobody	Anyone who is not you

All three pointing the same way is the case this was made for. All three pointing the other way and you are not vibe coding, you are gambling with extra steps.

The useful part is that this is decided per piece of work, not per project. The same afternoon can hold a throwaway script you never read and a permissions change you read twice. Treating a whole repository as one setting is what produces both of the common mistakes — reading everything on a prototype, and reading nothing on the part that bites.

What should I never vibe code?

A short list, and the reason is the same for every item on it:

Authentication and permissions. Wrong here does not throw an error. It quietly lets the wrong person in, and you find out from somebody else.
Money. Prices, charges, refunds, currency. Off-by-one in a loop is a bug; off-by-one in cents is a chargeback and an email you do not want to write.
Anything that deletes. Cascading deletes especially. The test for this category is whether an undo exists.
Database migrations. They run once, against real data, and the failure is discovered after the data is already gone.
Anything handling other people’s personal data. Being wrong here has a regulator attached.

Notice what is not the criterion: difficulty. Some of these are easy code. The property they share is that being wrong does not announce itself — which is exactly the assumption vibe coding runs on.

This is not “write it yourself”. It is “read this one”. Have the model write it, then actually read what it wrote, and ask it to explain the parts you cannot follow. The reading is the whole cost, and on these five it is worth paying.

The first week

Keep sessions short, and end each one on something that works. This is the single highest-leverage habit and it is not about the AI at all. A long session accumulates decisions nobody wrote down, and when something is finally wrong there is no point to go back to. Short sessions with a working commit at the end give you somewhere to return to.

Read the expensive parts. Not all of it — that would defeat the purpose. Read anything touching money, authentication, data deletion, or code another person also works on. Skim the rest. The skill being built here is triage, and it is a real skill: knowing where being wrong is expensive is most of what senior engineers know.

Say what it must not do. Most people describe what they want and stop. The instruction that saves the most time is the one that rules things out — do not touch the auth module, do not add dependencies, do not change the database schema. Models are agreeable and will happily do a helpful thing you did not want.

Run it before you believe it. Generated code that looks right and does not run is the most common single failure, and the cheapest to catch.

Notice when the prototype stopped being a prototype. There is usually one specific moment: somebody else opens it, or it goes in front of a user, or you deploy it. That is the moment the trade changes, and the honest response is to go back and read it properly.

What a good session looks like, start to finish

Concretely, because “keep sessions short” is advice you can agree with and still not act on:

Start from a commit. Not a tidy repository — a committed one. This is the save point, and it takes ten seconds.
Say the goal and the boundary in the same message. What you want, and what is off limits. The second half is the one people skip.
Let it work without interrupting. Steering mid-flight produces a change that is half one plan and half another, which is harder to read than either.
Read the diff, not the codebase. How many files, which files, anything deleted you did not ask to delete.
Run it. Before you believe any of it.
Commit, or throw the whole session away. Both are fine outcomes. The one that is not fine is carrying a half-working state into the next session.

Roughly an hour is where this lands for most people, and the number matters less than the shape: the session is the unit you can throw away. Once a session has been going long enough that discarding it is unthinkable, you have lost the property that made the whole approach safe — and that happens gradually, which is why it is worth watching for.

The questions people actually ask

“Am I still a real developer if I do this?”

The question underneath is whether you are building a skill or avoiding one. You are building one — triage, specification, knowing where risk lives — and it is not the same skill as writing the syntax yourself. Both are real. Neither is complete on its own.

“How do I stop it inventing libraries that do not exist?”

Run the code. Hallucinated imports fail immediately, which makes this the least dangerous class of error. Worry more about the ones that run.

“It rewrote something I did not ask it to touch.”

Very common, and the ordinary fix is to say what is off limits before you start. On a repository other people work on, this stops being a nuisance and becomes the actual problem — which is its own post.

“Should I commit code I have not read?”

On something disposable, yes. On something shared, you are handing your colleagues a diff you cannot answer questions about, and that is a social problem before it is a technical one.

“Is this how professional teams work now?”

Partly, and honestly the answer is still moving. What is clearly true is that the constraint has shifted from how fast can this be written to how confidently can it be changed later, and the teams doing well are the ones treating that as the thing to design around.

Where this is going, and what we do about it

Everything above works for one person on their own machine. The interesting failures start when the repository is shared — when generated code is locally reasonable and globally wrong because the model could not see a convention that lives in somebody’s head.

That is the problem CommitCycle works on: each agent gets a grant bound to one task and one branch that expires on its own, the paths that would hurt carry an owner, and every task closes with a record of what it declared versus what it touched.

Being straight about where that is: the plugin installs the enforcement today, and the commitcycle package on npm installs the CLI — the process without the wall. The hosted board is invitation-only while this is small. And none of it is what you need in your first week of vibe coding — in your first week you need short sessions and a habit of reading the expensive parts.

The week after, when you have decided the thing is going to exist beyond Friday, the question changes from habits to setup: what to have in place before the first prompt, and why each piece is there.

What breaks when vibe coding meets a repository other people work on

Fri, 14 Aug 2026 00:00:00 GMT

Everything about vibe coding changes when the repository has other people in it. Not because the code gets worse, but because the way it fails stops being visible.

On your own machine, a mistake shows up as something not working. On a shared repository, the characteristic failure is code that works, reads reasonably, passes review, and is wrong anyway — because it broke a rule that was never written down anywhere the model could read it.

The shape of it

An agent is asked to add a field to a form. It does, competently. It also adds a database migration, because that is what adding a field usually needs.

The migration is fine. The problem is that this team applies migrations by hand, in a specific order, after a review by the person who owns the schema — a convention that exists because of an incident eighteen months ago, is known by four people, and is written down nowhere.

Nothing in that diff looks wrong. That is the failure. It is not bad code; it is code that is locally reasonable and globally wrong, and the distance between those two is exactly the distance between what is in the repository and what is in somebody’s head.

Why does review not catch it?

Review reads the diff and asks whether it is good. This class of problem is invisible to that question, because the diff is good. The defect lives in the relationship between the change and a piece of context that is not on screen.

A reviewer catches it only if they happen to hold the convention and happen to think of it while reading. That works, sometimes, when the reviewer is one of the four people. It stops working the moment volume goes up — and volume going up is the entire point of using agents.

So the usual advice, review AI-generated code more carefully, is half right and does not scale. Careful line-by-line review of everything removes the reason to generate it in the first place.

What is the failure that costs most?

Two agents, at the same time, on the same repository.

Each is correct in isolation. Each passes its own tests. One refactors a helper the other is depending on; or both touch the same config from opposite directions; or one moves a file the other is writing to. Nothing errors. Both branches are green.

The loss shows up days later as a change that was made and then was not there any more, and nobody can say when it stopped existing. It is expensive precisely because there is no moment of failure to point at — you are reconstructing a negative from git history.

This is not hypothetical and it is not rare. It is the ordinary consequence of running more than one agent on one repository, which is now a normal Tuesday.

How do I know this is already happening?

It does not arrive as an incident, which is the difficulty. It arrives as a set of small facts that each have a plausible individual explanation:

Work that was done and then was not there. Somebody remembers writing it. Git says it existed. Nobody can name the commit that removed it.
The same bug fixed twice, three weeks apart, by two people who each thought they were first.
A convention re-explained in three separate sessions, because each session started with no memory of the last one and nobody wrote it down in between.
A pull request that touches files nobody expected, where the extra files are all individually defensible.
“Who changed this?” answered by a commit message that says refactor and an author who was not reading closely.

Any one of these is an ordinary bad week. All of them together is the failure mode, and the reason it goes unnamed for so long is that there is no error to search for. You are looking for the absence of something, and absences do not page anyone.

What if the other people are my own agents?

The inversion that catches most people out: you do not need a team to have a shared-repository problem. Two terminals is enough.

A repository does not know that two sessions belong to the same human. Every property that makes this hard on a team is present when you are alone — concurrent writes to the same files, no shared memory between the sessions, conventions that exist only in your head — and one property is strictly worse. On a team, the second agent’s work is at least read by a different person. When both are yours, you approve both, quickly, in the same afternoon, and there is no second reader anywhere in the loop.

This is why “I am a solo developer, this does not apply to me” is usually wrong by the time somebody says it. The threshold is not the number of people. It is the number of things writing to the repository at once.

Do AGENTS.md and CLAUDE.md fix this?

The standard answer is a CLAUDE.md or AGENTS.md with your conventions in it. Do write one. It genuinely helps, and it is the cheapest thing on this list.

It also decays, for the same reason all documentation decays: it is a snapshot of what somebody remembered on the day they wrote it, and nothing forces it to be revisited when the thing it describes changes. Six months in, it is a mix of true, stale and aspirational, and an agent reading it cannot tell which line is which. Neither can a new hire.

A context file is necessary and it is not sufficient, and the gap between those two is where the interesting work is.

What actually helps?

Name the paths where being wrong is expensive. Not everything — most of a repository is genuinely safe to change, and treating it all as dangerous means nothing is. A short list of the paths that would hurt is worth more than an exhaustive one, because a short list gets read.

Give each one an owner. Not for bureaucracy: so that “should this change?” has somebody to ask. An unowned rule is a rule that gets routed around at the first inconvenience, by humans as much as agents.

Scope the work before it starts, not after. What should this do, what must it not do, which areas does it touch. Written before the code exists, that is a specification. Written after, it is an excuse.

Make it possible to see what a piece of work actually touched, as against what it said it would. That difference is where the surprises are, and it is a question git can answer if anybody asks it.

None of that needs a product. It needs the list to exist somewhere both the people and the agents can read.

What can I do on Monday, without buying anything?

In order, because doing the first two is most of the value:

Write down the five paths where being wrong is expensive. Five, not fifty — the point is that the list gets read. Migrations, auth, the payment code, the shared config, whatever yours are.
Put a name against each one. So “should this change?” has somewhere to go. It does not have to be a formal owner; it has to be a person.
Start every piece of work by saying what it must not touch. One line, before the code exists. This is the single highest-yield sentence in agentic development and it costs nothing.
Once a week, look at what actually changed against what you thought was being worked on. Not a review of the code — a comparison of two lists. The gap is where the surprises live, and once a week is enough to catch them while they are still cheap.

None of that is a product and none of it needs permission. If it turns out to matter for you, the next question is what enforces it when everybody is busy — which is where the rest of this gets interesting.

Where CommitCycle fits

That list is the thing we build on. Zones are the paths that would hurt, each with an owner and a risk level. A task declares what it touches before it starts, and moving a wall takes one approval with a reason. Each agent gets a grant bound to one task and one branch that expires on its own, so two sessions in their own worktrees cannot quietly authorise each other — share one directory and they still can, which is why the worktree is the instruction rather than a preference. Every task closes with a record of what it declared against what it touched.

Where it actually is, plainly: the enforcement installs today as a Claude Code plugin; the commitcycle package on npm puts cycle on your PATH and carries no hook, so it gives you the process without the wall. The hosted board is invitation-only while this is small. The zone model is agent-agnostic, but the enforcement point needs a small adapter per harness, and today only the Claude Code one has been seen to deny on a real install.

And the honest boundary worth repeating: denying a tool call in flight is not what makes this different. Several vendors ship that and Claude Code includes it for free. The part that is ours is the grant that is bound to one task, attributed to an owner, and expires on its own — and the record afterwards that says what actually happened.

If you are one person on a prototype, none of this is your problem yet, and the first-steps post is the more useful one — or the setup, if the prototype has started looking like it will survive the month.

What to move out of Obsidian, and what to leave in it

Fri, 14 Aug 2026 00:00:00 GMT

The previous post argued that an Obsidian vault cannot be your AI agents’ knowledge base: it is private to one machine, its claims carry no provenance, and nothing marks a note as expired.

That argument gets agreed with and then not acted on, because “move your knowledge” is not a task anybody can start on a Tuesday. This post is the practical half. What actually moves, what stays, and what the replacement looks like once it is running.

The line, applied per note

If being wrong about this note would mislead somebody else, it has outgrown a personal vault.

Per note, not per vault. That distinction is the whole thing, and it is why this is a smaller job than it sounds. Most vaults are mostly thinking — half-formed connections, meeting scraps, things you wrote to work out what you thought. None of that moves. What moves is the minority that other people, or an agent, would act on.

In practice that has been under a fifth of the notes for everyone I have watched do it. The rest stays exactly where it is.

What moves?

Conventions. “We do migrations in two steps.” “Handlers return the error, they do not log it.” Anything phrased as we do X is a claim about the team, and a claim about the team belongs where the team can see and correct it.

Decisions, with their reasons. Not just what was chosen, but what was rejected and why. This is the highest-value category and the one most often lost, because the reasoning lives in someone’s head and the vault records only the conclusion. An agent handed the conclusion without the reason will cheerfully undo it the first time the conclusion is inconvenient.

Anything an agent would act on. If a note would change what gets written when an agent reads it, it is operational, not personal. This is the newest category and the one vaults were never designed for.

The boundaries. “We deliberately do not do X, and here is why.” Nobody writes these down and everybody rediscovers them the expensive way.

What stays?

Everything else, and that is not a consolation prize.

Half-formed ideas. Notes that are allowed to be wrong. The connection you have not made yet. Reading notes, meeting scraps, the thing you wrote at 2am that made sense at 2am. Obsidian is better at all of it than anything you would replace it with, and it is better because it has no review, no approval and no audience — the exact properties that disqualify it for the other category.

A vault that only holds this is a vault doing its job.

What about the notes that are half thinking, half convention?

The common awkward case, and the one that stalls people, because the line looks clean until you meet an actual note that is two thousand words of working-something-out with one real decision buried at the bottom.

Split it, and it is easier than it sounds. The thinking stays in the vault. The claim moves, on its own, as one sentence. Link back if you like.

What you must not do is move the whole thing. A note that is eighty per cent exploration and twenty per cent decision, sitting in the repository, teaches an agent that your team’s conventions are tentative — and an agent that thinks a rule is tentative will negotiate with it the first time the rule is inconvenient. Leaving the whole thing in the vault has the opposite failure: the twenty per cent that other people need is invisible, indistinguishable from the musing around it.

The test for whether a note is ready: can you extract a sentence that starts “we do” or “we do not”? If not, there is nothing to move yet, and the note is still doing its job where it is.

Where should the moved notes live?

Into the repository they describe. Not a wiki, not a second tool: the repo, reviewed in the same pull request as the code they are about.

That placement is doing the work. A note in the repo gets read at the moment somebody changes the thing it describes, because it is in the diff. A note in a wiki gets read when somebody goes looking for it, which is the failure mode you are leaving.

It also means the note is reviewed like code. Somebody approves it. Somebody is accountable for it. Two engineers cannot hold two contradictory versions without one of them showing up in a diff.

What does a moved note actually look like?

Format matters less than four properties, and each one answers a way the vault version failed:

One claim per note. “We do migrations in two steps” is a note. “Notes on our backend” is a folder wearing a note’s name, and nothing in it can be confirmed, contradicted or archived independently.
It says where it came from. The decision, the incident, the pull request. A claim you cannot trace is a claim you cannot weigh, and moving an untraceable claim into the repository relocates the problem rather than fixing it.
It says what was rejected. The conclusion without the reasoning gets undone the first time the conclusion is inconvenient — usually by an agent, cheerfully, in a diff that looks like a simplification.
Present tense, and specific enough to be wrong. “Be careful with migrations” is not a note, it is a mood. Nobody can act on it and nobody can ever prove it stale.

And short. The reason wiki pages go unread is that they are two thousand words when the claim is one line, and a note nobody reads is a note that does not exist — which is the same outcome as leaving it in the vault, after more work.

What does this not fix?

Moving notes into the repo fixes discovery and review. It does not fix decay, and any post that told you otherwise would be selling you something.

A note in a repository goes stale exactly as fast as a note in a vault. What changes decay is not location, it is a trigger — something that forces knowledge to be written while the person still remembers why, and something that lets a wrong note be removed by a mechanism rather than by somebody’s memory.

Those are the two properties to look for in whatever you use, and they are the two properties CommitCycle builds on: knowledge is fed at the close of a unit of work, one line at a time, when the reason is still fresh; and archived is a real state, which is what lets the corpus shrink instead of only growing more confident.

How do I start without a migration?

Do not migrate. Migrations of knowledge fail for the same reason migrations of anything fail — the effort is up front and the payoff is diffuse.

Instead: the next time you write a note that other people would rely on, write it in the repo instead of the vault. Then the next one. The vault stops growing in the category that hurts, and the corpus that matters starts accumulating in the place where it gets reviewed. Nothing is moved and nothing is lost.

For the notes whose readers are agents rather than people, the destination has a shape: a skill is a folder in the repository that gets loaded when it becomes relevant and ignored when it does not, which is the closest thing to a vault note that an agent can actually use.

After a few weeks, whatever is still in the vault and still load-bearing is a short list, and by then you will know exactly which notes are on it.

How do I know it is working?

Four signals, roughly in the order they show up:

You stop re-explaining the same thing to each new session. This one arrives first and is the most immediately satisfying.
Somebody corrects a note during a code review. That is the placement paying off: it means the note was read at the moment the thing it describes was being changed, which is the entire reason it went in the repository.
An agent cites one back to you — proposing something and naming the note it came from, rather than proposing something plausible.
Somebody archives one. This is the real signal, and it is the one that takes longest. A corpus that has only ever grown is being accumulated, not maintained, and it will end up exactly where the vault was: more confident every month and less accurate.

The counter-signal is the mirror of that last one. If the notes in the repository are growing and nothing has ever been removed, you have rebuilt the vault with extra ceremony, and the staleness is on its way back.

Where CommitCycle actually is

Worth stating plainly, because the point of this post is a line you can apply with or without us: the enforcement installs today as a plugin, and the commitcycle package on npm installs the CLI beside it. The hosted board is invitation-only while this is small.

So take the line and use it. It costs nothing, it applies to whatever tools you have, and the argument underneath it is in the previous post if you want to check the reasoning before you trust the conclusion.

Your Obsidian vault cannot be your AI agents' knowledge base

Mon, 10 Aug 2026 00:00:00 GMT

An Obsidian vault fails as an AI agent knowledge base for three structural reasons: it is private to one machine, its claims carry no citations, and nothing tells you when a note stopped being true. Agents read whatever they are handed and have no way to tell a current note from one that expired three sprints ago — so the confident wrong answer and the correct one arrive looking identical.

This is not a criticism of Obsidian. It is very good at the job it was built for, which is one person thinking. The failure is a category error: a personal thinking tool being asked to be a shared source of truth.

Can agents read an Obsidian vault at all?

Yes, and this is worth clearing up first because it is where the conversation usually starts. A vault is a folder of plain markdown. Any agent with file access reads it without ceremony, and there are MCP servers that will wire one up for you in an afternoon.

Access was never the problem. Reading and trusting are different operations, and a vault carries no signal that separates them. A note written last week and a note that stopped being true in 2024 are the same kind of object, in the same folder, with the same authority. A human reading their own vault discounts automatically — oh, that one is old — using knowledge that is nowhere in the file. An agent has nothing to discount with.

So the easy half gets solved, the hard half is not noticed, and the setup looks like it is working right up until it confidently acts on something that expired.

The three failures, in order of how much they cost

1. It is private, so knowledge is per-person

A vault lives on a laptop. Sync it and you have a shared folder, not shared knowledge — because the vault has no notion of review. Nobody approves a note. Nobody is accountable for one. Two engineers keep two vaults, each correct about different things, and the agent gets whichever vault its operator happens to own.

The symptom is easy to recognise: the same question gets two answers depending on who asks their agent.

2. Claims carry no provenance

A note says “we do migrations in two steps.” Is that a decision someone made, an observation from one incident, or something a colleague believed in 2024? The note does not say, and after a few months nobody remembers.

For a human reader this is friction. For an agent it is fatal, because the agent cannot weigh a claim it cannot trace. It will follow a stale note with exactly the confidence it follows a correct one.

3. Nothing marks a note as expired

This is the one that quietly does the most damage. A vault has no death state. Notes accumulate, and the only mechanism for removing a wrong one is a person remembering it is wrong — which reliably fails, because the person who knows the note is stale is not the person reading it.

The result is a corpus that grows monotonically more confident and less accurate.

What does documentation for agents have to be?

Every property below exists because of a specific way vaults fail:

Property	The failure it answers
Lives in the repository	Reviewed like code, not synced like a folder
Cites a decision, task or file	A claim you cannot trace is a claim you cannot weigh
Written when work closes	Not “whenever someone remembers”, which is never
Has an archived state	A wrong note must be removable by something other than memory
Loaded by what the task declares	Fifty notes is not context, it is noise

That last row is the one most tools miss. Handing an agent an entire knowledge base is not context engineering; it is a bigger prompt. What a task needs is the subset relevant to this task, selected by something the task itself declared.

Why not just give the agent the whole vault?

The obvious move, and it fails in three specific ways:

Volume is not context. Four hundred notes in a prompt means the three relevant ones are diluted by three hundred and ninety-seven that are not. That is a bigger prompt, not better grounding, and it costs accuracy rather than buying it.

Nothing says which notes apply here. A vault’s links encode association — this reminded me of that — not applicability to the task in front of you. Those are different relations, and only one of them is useful for selection.

Contradictions have no resolution. Two notes disagree about how deploys work. Nothing in the vault records which one won, because the winner was decided in a conversation. The agent resolves it by picking whichever reads closest to the prompt, and reports the result with the same confidence either way.

The outcome is worse than a short curated file would have been: an answer that is well-phrased, apparently well-sourced, and wrong.

Does RAG over the vault fix it?

Partly, and it is worth being precise about which part, because this is the most common proposed fix.

Retrieval solves selection. That is genuine — it turns “the agent read four hundred notes” into “the agent read the four closest ones”, which is a real improvement and the annoyance people feel most.

It does not touch provenance or staleness, and on staleness it leans slightly the wrong way. Retrieval surfaces whatever is textually nearest the question, and a confidently written stale note — “we do migrations in two steps” — is frequently the nearest thing to a question about migrations. The correct note may be newer, hedged, and worded less like the question. Embeddings have no opinion about dates or truth; they rank similarity.

So RAG upgrades the problem from the agent read everything and could not tell what was current to the agent read the four most relevant things and could not tell what was current. Better, and not the fix.

What about Notion, Confluence or a wiki?

They answer one of the three failures cleanly and leave the other two roughly where they were.

Shared: yes. This is the real gain, and it is not nothing — one corpus, many readers, no more “the same question gets two answers depending on whose vault the agent read”.

Provenance: no. A wiki page rarely says which decision it came from or which incident produced it, for the same reason a vault note does not: whoever wrote it knew, so writing it down felt redundant.

Staleness: arguably worse. A vault’s bad notes are at least buried. A wiki’s are indexed, searchable and linked from four other pages, so scale makes a stale claim more discoverable rather than less, and nothing in the tool archives it. The mechanism for removing a wrong page is still a person remembering.

And one failure the wiki adds: it is not where the code changes. A note in the repository is in front of you in the diff at the moment you alter the thing it describes. A note in a wiki is read when somebody goes looking — which is the behaviour you were trying to fix.

How CommitCycle does it

CommitCycle calls these playbooks — per-topic, per-project knowledge files that live in your repository. Four properties, each answering one row above:

They cite. Every claim points at a decision, a task or a file. A lint flags a claim that carries no citation — it warns, it does not block — and when cycle seed drafts playbooks, a claim citing a file that is not in the repository is dropped, and a playbook left with nothing cited is not created at all.
They are fed at the close of work, one bullet at a time, when the person still remembers why. Not in a retro, not when someone remembers.
They are loaded by the task’s declared topics, so a task about the database does not load the frontend’s conventions.
They can be archived. archived is a real state, which is what makes the corpus able to shrink.

And an adversarial pass — cycle challenge — is built to propose the practices the repository visibly lacks, each with a named source. Like cycle seed, it needs a model configured on the board, and it has not yet run against a live one. You can refuse, and your refusal is recorded with its grounds. “We deviate from this on purpose, and here is why” is knowledge too, and it is the kind that vaults never capture because nobody writes down what they decided not to do.

The honest part

There is a real objection here and it deserves a straight answer: “if you generate a playbook from my legacy repository, won’t it just codify my mess?”

Yes. By design, description alone codifies the mess — with receipts. That is why the challenger exists: it is built to propose what the repo lacks rather than only describing what it has, and a human accepts or refuses each proposal. There is no auto-accept, and a test holds that door shut.

What this does not replace

Keep the vault. This is not a migration.

Obsidian remains better than anything here at thinking — at half-formed ideas, at connections you have not made yet, at notes that are for you and are allowed to be wrong. What moves out of it is the subset that other readers rely on being true. That subset was always the part that hurt when it went stale, and it was never the part Obsidian was designed to hold.

A useful line to draw: if being wrong about this note would mislead someone else, it does not belong in a personal vault.

Where it goes instead, for the notes an agent is meant to read, is a skill in the repository — same markdown, but versioned with the code it describes and loaded only when the task calls for it.

Where CommitCycle actually is

CommitCycle runs its own development — the board, the gate, the audit records and the playbooks described above are in use on its own repository today. The enforcement half installs as a Claude Code plugin; the commitcycle package on npm puts the cycle CLI on your PATH, without the hook. The hosted board is invitation-only while this is small. Phase 0 is measured and published with its limits.

So this post is not asking you to migrate anything today. It is making an argument you can evaluate on its merits, and if it lands, the waitlist is the honest next step. If the argument is wrong, that is worth more to us than a signup.

The rest of the product is documented in full: the AGENTS.md context block, zones, and the audit record.