Agent skills

The wizard's last act is to hand the project to a coding agent, so the app has to arrive with notes and not only with code. Everything on this page follows from that: the agent that continues the work needs what we know about the API's edges, and it needs it in the place its own CLI looks.

One skill per module

Each module carries a skill/ directory in this repository, and the wizard copies it into your project as chatfuel-<id> — chatfuel-deals, chatfuel-livechat, one per module you picked. Each one holds that module's structure, its GraphQL operations and the traps in the API behind it.

One skill hangs off no module: chatfuel-update, which is about the app's relationship to the wizard rather than about anything the app does. A module's skill installs only if you picked that module, and every app needs the update story, so it lives beside the module trees instead of inside one — which is also what lets an update update it.

Two layouts, because neither CLI reads the other's

Neither reads the other's directory, so this is a choice the wizard has to make rather than hedge. Copying both layouts would leave two trees to drift apart instead of one to maintain — so the skills are written once, and moved if the agent you settle on at the handoff is not the one they were laid out for.

The difference goes one level deeper than the paths. Claude Code loads its skills directory by itself, so naming the skills is enough. Codex's discovery depends on its version and the user's config, so its instructions file spells out the full path to each SKILL.md.

Skills can also go to your home directory instead of the project, in the same layout — useful when you will scaffold more than one app and want one copy of the notes.

The handoff note, and the checklist it lands in

Two files come out of the run, and they do different jobs.

CLAUDE.md or AGENTS.md is the standing brief: the routes this app has, the skills to read before touching the API, which environment variables are secrets that must never be printed, and how to resume the guided setup later. It is short on purpose — it is read on every session start.

The setup checklist is the one-time script for the first session: how to greet you, a tour of the modules that were installed, the deep links to what was seeded, and the instruction to start the dev server rather than ask you to. Each module's handoff.md is inlined into it verbatim, under a "Module guides" heading, which is where the module-specific first tasks and gotchas live.

Claude Code reads that checklist as a slash command; Codex reads it as a skill, with the frontmatter that makes the same text valid in both places. When the wizard launches the agent for you, all it types is the instruction to run it.

In --embed mode the instructions file belongs to a project that already existed, so the wizard writes a marked section into it and rewrites that section on later runs instead of overwriting the file.

What a skill is actually for

The concrete case: module code is plain React and a typed GraphQL client, and the operations each module uses live in its skill's examples, validated against the bundled schema — the same SDL the app carries at src/vendor/schema/, written from one source so the two cannot drift. So "add a column to the deals table" is a sentence rather than a file hunt: the agent already has the operation, the schema and the note about what that field does when it is null.

It also has the part that is easy to get wrong. Editing an operation is a cycle, not an edit — the document in src/vendor/api/operations/, then npm run codegen, then both committed — and the proxy refuses a document that no namespace in src/operationDocs.ts exports. An agent working from the skill knows that; an agent working from the code alone finds out on the first request.

That is also why the skills are per module rather than one big document. You installed four modules, so your agent reads four sets of notes and not fourteen.

This site does the same thing for the same reason. It serves itself as a skill at /SKILL.md, and every documentation page as Markdown — /docs/concepts/state.md is this section's neighbour in plain text — with the whole list at /docs/llms.txt.

What it costs

A skill is a copy, like everything else the wizard writes. It reflects what we knew on the day you ran it and it does not refresh itself. What carries it forward is the app's lock: a skill installed into the project is recorded there with every file it holds, so npx @chatfuel/wizard update moves it the way it moves the rest of the vendored source — and a file you edited comes back as a conflict rather than being overwritten.

Two cases sit outside that. A skill sent to your home directory is outside the app, so the lock records that it exists and nothing more; keeping it current means re-running the wizard, which asks before it replaces one. And a chatfuel-* directory the lock does not claim is treated as yours: the wizard asks the blunter question before touching it, and under --yes it leaves it alone entirely.

Your first change ends with the version of this you can try in one line.