The Mental Model — One Source, Two Runtimes
Zones: What an Update May and May Not Touch
Your Customizations Are Protected by Design
A toolkit that overwrote your project's personality on every update would be unusable. Files are classified into zones, and the updater honors them:
| Zone | Behavior on update |
|---|---|
| Template | Refreshed from the toolkit (workflows, shared skills, core helpers) |
| Project | Never overwritten (local settings, bespoke skills) |
| Mixed | Template parts refresh, your parts are merged (role files, root instructions) |
Adding to a Shared Skill Safely
Say you want a project-specific rule inside a toolkit-owned skill. Edit it in place and the next sync clobbers it. Use a marker instead:
<!-- @@project-additions -->
Everything below this line is yours and survives updates.
For a paragraph that must sit inside an existing section, use the paired fence <!-- @@project-additions:start --> and <!-- @@project-additions:end -->. Both forms are only recognized outside fenced code blocks, so documentation that merely shows the marker does not accidentally freeze its section.
Role personas, Project Context, bespoke skills, marked project additions and local settings are the things --merge keeps. If you are tempted to customize something not on that list, put it behind a project-additions marker first.
How do you add a project-specific rule to a toolkit-owned shared skill so updates do not erase it?