The midcode skill

A project edited with midcode is a normal repository, so any coding agent can work in it. What an agent doesn’t know by itself is what midcode put there and what midcode needs: that midcode.css is generated, what mid:p-6 means, where your comments are kept, how a component has to be written for its variants to show on the canvas.

The midcode skill is that knowledge, packaged the way agents take it: a folder with a SKILL.md and reference files. The agent reads the skill’s one-line description at the start of every session, and opens the rest only when the task has to do with midcode.

Install it

There are two ways: from midcode, for you and every project on your Mac, or with the open installer, for a repository and everyone who works on it.

From midcode’s Agent panelNext release

In the Agent panel, the button with the graduation cap opens the skill’s panel. Its tooltip names the agent you have selected: “Teach Codex how midcode works”. An empty chat shows the same words under its suggestions while the agent doesn’t have the skill.

Click “Add to Codex” (or whichever agent it is). midcode copies the skill it carries into that agent’s own skills folder on your Mac, the folder in the last column of the table below, and the panel shows where: ~/.codex/skills/midcode. Nothing is written in your project and nothing is downloaded: it’s the skill that matches the midcode you have.

• –

  The agent reads it from its next session: start a new chat, or restart the agent.

• –

  It’s added to one agent at a time. Pick another agent in the panel to add it there too.

• –

  “Update the skill” shows when the folder holds another version, an older midcode’s or one installed from this site. It replaces the skill’s files and leaves anything else you keep in that folder.

• –

  “Remove the skill” moves the folder to the Trash.

With the installer

In your project’s folder:

npx skills add https://midcode.app

skills is the open-source installer for agent skills. It reads the skill from this site, checks it against the digest the site publishes, asks which agents to install it for, and puts it in each one’s skills folder:

With several agents, the files are kept once in .agents/skills/midcode/ and the other folders link to it. The installer also writes a skills-lock.json that records where the skill came from, which is what lets it update later.

Installed in the project, the skill is a folder you can commit: everyone who works on the repository, and every agent they use, gets it. Installed with -g, it’s there for every project on your Mac.

To skip the questions:

npx skills add https://midcode.app -g -a claude-code -y

Without the installer

The skill is one archive. Unpack it where your agent looks for skills:

mkdir -p .claude/skills/midcode
curl -fsSL https://midcode.app/.well-known/agent-skills/midcode.tar.gz | tar -xz -C .claude/skills/midcode

What’s in it

• –

  SKILL.md: the short version. How to recognise a midcode project, which files midcode owns, the rules for writing markup, styles, components and content that stay editable, and how to read what you send from the canvas (an element’s reference, your comments).

• –

  references/: every page of these docs as Markdown, one file each (editor-components.md, styling-without-tailwind.md, frameworks-nextjs.md…). SKILL.md ends with the list, so the agent opens the one page a task needs and nothing else.

What changes with it

With the skill installed, an agent working in your project:

• –

  Writes text, classes and attributes in the forms midcode can edit afterwards, and says so when it has to use one it can’t (Code that midcode can edit).

• –

  Styles with Tailwind’s classes in a Tailwind 4 project and with mid: classes everywhere else, and never edits midcode.css by hand (Without Tailwind).

• –

  Writes a component’s variants and states the way the canvas shows them: a typed variant prop, data-variant, a named group (Components).

• –

  Reads .midcode/comments.json when you ask it to go through your comments, and finds each one’s element by its file and line (Comments).

• –

  Leaves alone what’s midcode’s: the .midcode/ folder’s files, the canvas page, the generated stylesheet (What midcode adds to your project).

Keep it current

The skill is built from these docs, so it changes when they do. Added from midcode, it’s updated from the same panel: “Update the skill” shows after you update midcode. Added with the installer:

npx skills update midcode

Without a skill

Every page of the docs is one click from a chat:

• –

  Copy for AI, on top of each page, copies it as Markdown.

• –

  Add .md to a page’s address for the same text: https://midcode.app/docs/editor/components.md.

• –

  /llms.txt lists every page with one line each, and /llms-full.txt is the whole documentation in one file.