Skip to main content

​
Silvia AI Skills — Keeping UI Knowledge in Sync

Silvia (the AI agent users talk to) does not learn about the app from this codebase. Her knowledge of the UI lives in a separate repo:
https://github.com/CFO-Silvia/skills
Two skills in that repo mirror the UI in this repo:

​
Why this matters — the failure mode

The navigation skill instructs Silvia to answer navigation/“how do I…” questions only from what is documented there. If a UI element isn’t in the skill, Silvia tells the user “I don’t have that information” and files a support ticket — even when the answer is one click away. Real incident (CFO-6702, skills PR #158): the chat box shows a “Profile incomplete” warning. The warning existed in this repo but not in the skill, so when a user asked Silvia to remove it, she said there was no way to resolve it and opened a support ticket. The fix was a 4-line skills update — but it shipped weeks after the UI did. The lesson: a user-visible UI change is not done until the skills repo reflects it.

​
Rule for agents implementing features

When your change touches anything user-visible, before you open the PR:
  1. Read silvia-navigation-skills/SKILL.md in the skills repo (clone or check ~/procap/skills if working locally).
  2. Ask: if a user asked Silvia about this change tomorrow, could she answer correctly from that file?
  3. If not, open a companion PR in CFO-Silvia/skills updating the skill, and link the two PRs to each other.
  4. Mention the skills PR in this repo’s PR description so reviewers can verify the pairing.

​
Changes that almost always need a skills update

  • Adding, removing, renaming, or moving a page or sidebar item
  • Changing a user flow (add asset/liability, connect/reconnect account, transactions, goals, vault, profile, onboarding, settings)
  • Adding or changing warnings, banners, empty states, or prompts the user might ask Silvia about (“how do I get rid of this?”)
  • Changing plan gating, pricing, or upgrade CTAs (Free/Pro/Max)
  • Renaming buttons, tabs, or menu items referenced in the skill
  • Adding/changing GenUI ui-* components or their schemas → silvia-ui-components-skills/SKILL.md
  • Changing dashboard widgets (add/remove/rename, customize flow)

​
Changes that don’t

API internals, refactors with no visual change, performance work, tests, infra, styling tweaks that don’t alter structure or copy.

​
Deploying the skills update

Skills are served to Silvia from S3, not from GitHub. Merging a skills PR alone does not change live behavior — the skill must be synced to the silvia-skills bucket (see the skills repo README for the aws s3 sync commands and the silvia-skills-dev bucket for testing). Flag the deploy step in the skills PR description.

​
Review safety net

.coderabbit.yaml instructs CodeRabbit to flag PRs that change user-visible UI without a mention of a skills-repo update. Treat that flag as a real checklist item, not noise — either link the companion skills PR or state why no skill update is needed.