# Retrofit an existing project for agents

URL: https://kywi-docs-production.up.railway.app/agent/retrofit-an-existing-project-for-agents
Type: docPage

`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](/agent/the-four-shipped-skills/) — 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:

$ 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.

## --force replaces the whole file

There is no merge step. Anything you or a teammate added to `AGENTS.md` by hand — a note about a house convention, a link to an internal doc, a correction — is gone the moment `--force` writes over it, along with everything else in the file. If you need those notes back, restore them from git history; if you want them to survive the next refresh, keep them in a section you re-add afterward rather than editing the generated prose in place.

## 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.
