| name | lovable-cloud-knowledge |
| description | Lovable's UI knowledge fields and workspace skill files — `.lovable/*.md` repo-mirror workflow, `.agents/skills/` propagation model, Project/Workspace scope split, precedence, review criteria. TRIGGER when: authoring or reviewing changes to `.lovable/*.md` or `.agents/skills/*.md`; drafting Project/Workspace Knowledge or workspace-skill changes. DO NOT TRIGGER when: not a Lovable project; editing CLAUDE.md or AGENTS.md; editing agent rules files; writing code.
|
| user-invocable | false |
Lovable Knowledge — Workflow & Review
1. Knowledge fields and Workspace Skills
| Workspace Knowledge | Project Knowledge | Workspace Skills |
|---|
| Scope | Cross-project (the Lovable workspace) | Single-project | Cross-project (the Lovable workspace) |
| Use for | Coding style, naming, libraries/frameworks, architectural patterns, testing requirements, lint rules, brand/voice, Lovable-platform behavior | What the app does, user personas, schema/tables, architecture decisions, domain terminology, project-specific constraints, design specifics, security/compliance, links to important references | Reusable procedures Lovable runs on demand |
| Precedence | — | Prioritized on conflict | — |
| Char limit | 10,000 | 10,000 | 100,000 |
| Repo path | .lovable/workspace-knowledge.md | .lovable/project-knowledge.md | .agents/skills/<name>.md |
When a rule could plausibly fit in either: ask whether it would apply to
a different project in the same Lovable workspace. If yes →
workspace. If no (it's tied to this product's domain, schema, or
constraints) → project.
Project Knowledge is prioritized over Workspace Knowledge on conflict. See REFERENCES.md for the full four-source load priority (Project Knowledge → Workspace Knowledge → AGENTS.md/CLAUDE.md → project code).
2. .lovable/ repo-mirror workflow (knowledge fields only)
This workflow applies to the knowledge fields (.lovable/project-knowledge.md
and .lovable/workspace-knowledge.md). It does not apply to workspace skill
files — see §2.5 for the skill-file propagation model.
.lovable/project-knowledge.md and .lovable/workspace-knowledge.md are
version-controlled mirrors of the corresponding Lovable UI fields.
Lovable only loads the UI fields at runtime; the repo files are not
auto-loaded — they exist for diff review and history.
Workflow for updating Lovable knowledge fields:
- Draft the change in a PR against the appropriate
.lovable/ file.
- Bump the "Last synced to Lovable UI" date in the file header in the
same PR.
- After merge, the human pastes the merged content into Lovable →
Settings → Knowledge.
Do not assume that writing to a .lovable/ knowledge file propagates to
Lovable. The UI field is the only thing Lovable reads; the repo file is the
authoring/review surface. (Skill files in .agents/skills/ work differently —
see §2.5.)
Do not skip the repo step and paste knowledge-field content directly into
the UI without a PR — that loses diff review, version history, and audit trail.
2.5. .agents/skills/ — repo-native skill files
.agents/skills/ holds the workspace skill files that Lovable auto-creates when
you define a new skill. Unlike knowledge fields, these files are not a
version-controlled mirror of a UI field — they are the source Lovable reads
directly from the repo.
Editing: editing .agents/skills/*.md via PR is permitted and encouraged.
A file being authored by Lovable (gpt-engineer-app[bot]) does not make it
read-only — it is a normal repo file on a normal review surface.
Propagation: changes reach Lovable when the PR description instructs Lovable
(in second person) to re-read the changed skill files and update its skills.
Example PR description note: "@Lovable: please re-read .agents/skills/<name>.md
and update your <name> skill to match."
No sync-date header: the "Last synced to Lovable UI" date header used in
knowledge mirror files does not apply here — there is no UI field to sync to.
Observation note: .agents/skills/ is the path Lovable uses when it
auto-creates skill files. This is observed behavior, not a documented spec in
the Lovable docs — re-verify if Lovable changes its file layout. See
REFERENCES.md for the grounding.
3. Authoring guidance
When writing content for either field:
- Perspective. Address Lovable in second person. Knowledge files
reading as internal engineering notes will confuse Lovable.
- Specificity. Lovable follows literally and may over-apply vague
guidance. "Be careful with auth" can become "add auth checks to public
endpoints." Spell out the boundary cases.
- Context budget. Both knowledge fields cap at 10,000 chars. Beyond
that, Lovable drops content. Skill bodies (
.agents/skills/*.md) have
a separate 100,000-char limit. Even before either cap, length displaces
active task instructions — apply the same length and behavior-test
discipline as Claude Code skills (see ai-instruction-and-memory-files §3).
4. Review checklist for .lovable/** and .agents/skills/** changes
When reviewing a PR that touches .lovable/*.md or .agents/skills/*.md:
- Perspective — Is the new content addressed to Lovable in second
person?
- Specificity — Could the instruction be over-applied (e.g., "be
careful with auth" applied to public endpoints)?
- Scope — Cross-project conventions →
workspace-knowledge.md;
this-app-specific → project-knowledge.md. Project knowledge wins
on conflict.
- Char budget — Is the file approaching its char limit? (Check the table above.)
- Sync status:
- Knowledge files (
.lovable/*.md): Has the "Last synced" date been bumped
in the same PR? Does the PR description note that the human must paste the
merged content into Lovable → Settings → Knowledge after merge?
- Skill files (
.agents/skills/*.md): Does the PR description include an
instruction to Lovable (second person) to re-read the changed skill files
and update its skills? (No sync-date header needed for skill files.)
For .agents/skills/*.md changes, also check:
- Skill name — Is the name 1–64 chars, lowercase letters / numbers /
hyphens only, not starting or ending with a hyphen, with no consecutive
hyphens?
