Skip to content

Retrofit an existing project for agents

`create-kywi-app agents` adds AGENTS.md, CLAUDE.md and the four skills to an existing project, skipping anything already there unless you force it.

create-kywi-app agents installs the same guidance a fresh scaffold gets — AGENTS.md, CLAUDE.md, and the four skill files — into a project that didn't start with them, or whose copies have drifted or gone missing. Run it from the project root, where kywi.config.ts lives; with no kywi.config.ts to read the command refuses outright rather than guessing. If it finds the file but can't tell which deployment mode it describes, it doesn't refuse — it assumes coupled and says so in a note under its first line of output.

It writes an honest header, not a fresh-scaffold one

Before writing anything, the command inspects the project on disk — whether it has an admin host file, a custom-module map, its own copy of the render helpers, and so on — and shapes the "Where things live" section of AGENTS.md around what it actually finds. A hand-rolled or older project gets a header describing its real layout, not a description of what a brand-new scaffold would have.

Existing files are skipped, not merged

The command always considers the same six files — AGENTS.md, CLAUDE.md, and one SKILL.md per skill — and prints a line for every one of them, whether it writes it or not. Here the project already has AGENTS.md, CLAUDE.md, and three of the four skills; only kywi-personalization was added to Kywi after this project's guidance was last refreshed, so it's the one file that gets created:

text
$ npx create-kywi-app@latest agents

Refreshing agent guidance for acme-site (coupled mode)…
  skipped (exists): AGENTS.md
  skipped (exists): CLAUDE.md
  skipped (exists): .claude/skills/kywi-content-model/SKILL.md
  skipped (exists): .claude/skills/kywi-collections/SKILL.md
  skipped (exists): .claude/skills/kywi-custom-modules/SKILL.md
  created: .claude/skills/kywi-personalization/SKILL.md

✔ 1 created, 0 updated, 5 skipped.
  Re-run with --force to overwrite the skipped file(s).

Agents will pick these up automatically; see AGENTS.md.

Run it without --force and any target file that already exists is left untouched — this is how the command adds a skill you're missing without disturbing guidance you already have. Add --force and every target file is overwritten, not diffed or merged.

A stale AGENTS.md gives no warning

Every generated AGENTS.md opens with a version comment naming the create-kywi-app release that wrote it, but nothing checks that comment against the core version the project actually runs — a project that has upgraded core several times since its guidance files were written shows no sign of it. If you're not sure your agent's briefing reflects the platform it's actually building against, re-running agents --force is the way to find out, not a stamp you can read at a glance.