What a team should share is capabilities and failure experience, not forcing everyone to use exactly the same entry point.
Raymond’s explanation
This is like a team sharing a cookbook. The cookbook should contain standard procedures, common failures, shared ingredient names, and tools that have been validated. But the layout of each person’s kitchen, where their fridge is, their tastes, and their personal ingredients will not be exactly the same. Forcing everyone’s entry point to become identical can make individual workflows fail.
The shared upstream is responsible for “how to do this correctly”; the personalized entry is responsible for “where to start in my environment, which personal resources to use, and how to present the result.” A single source of truth (SSOT) standardizes the boundaries of responsibility; it does not mean every person’s computer can contain only one completely identical file.
How to divide things
| Put in the shared upstream | Keep in the personalized entry |
|---|---|
| General SOPs and acceptance criteria | Personal absolute paths and folder structures |
| Reusable team scripts and examples | Local tools, hardware, accounts, and provider routing |
| Shared dictionaries, brand terminology, and format rules | Private resources, unpublished material, and methods for accessing credentials |
| Real failure cases and regression tests | Raymond’s taste, work rhythm, and delivery defaults |
| Relative paths that do not hard-code a personal environment | Local wrappers, routers, or overrides for shared capabilities |
When to use it
- The same Skill needs to work for team members, different AIs, or multiple devices.
- General rules should be upgraded together, but each execution environment has different paths, tools, and permissions.
- The team already has two or more similar workflows and is beginning to fix the same errors repeatedly.
Synchronization process
- First ask, “Does this change apply to everyone on the team?” If so, update the shared upstream first; otherwise, keep it in the personal entry.
- The shared upstream should use relative paths, environment variables, or checks before execution; do not put in keys, customer materials, or personal absolute paths.
- Diff the personal and team versions, absorb only the general improvements needed, and do not overwrite everything as a package.
- Feed general bugs and failure cases found in personal workflows back into the upstream so others do not encounter the same issue again.
Example: a team subtitle Skill
team-ai-skills is the shared upstream: it contains general SOPs for video-subtitle and yt-transcript, a shared terminology dictionary, reusable scripts, and a real failure case of “treating a raw transcript as a finished subtitle.”
Raymond’s local video-subtitle skill is a personalized entry: it retains vault paths, local tools, Raymond’s YouTube post-production rhythm, and private resource routing. It is not replaced by a symlink to the team version; instead, common improvements are manually absorbed after periodic comparison.
Counterexamples and boundaries
- Overwrite the entire personal version: copying the team version over whenever it changes erases personal paths, preferences, and stable entry points.
- Update only the personal version: a general bug remains on one computer, and other team members repeatedly hit it.
- Put a private environment in the upstream: hard-coded personal paths, tokens, or customer data make the shared version non-portable and may expose confidential information.
- A workflow used by only one person and still being tested can remain local; extract an upstream version when a second user appears or the same failure recurs.
Origin
This card comes from practical experience consolidating the team subtitle Skill on 2026-07-08–07-09: the team shared repository served as the upstream, while Raymond kept a locally optimized entry; shared terminology and failures went upstream, while personal paths and preferences stayed local. The corresponding repository decision is also recorded in REPOS.
Where it has been discussed
Implementation and standards
team-ai-skills/README.md: defines the team upstream, local version, and manual adoption method.team-ai-skills/video-subtitle/: a complete example of shared SOPs, scripts, dictionaries, and failure cases.- Raymond’s local video-subtitle skill: the personalized entry.
- REPOS: records the boundary between the shared upstream and the local version.
Related concept pages
- AI Tool Applications: system layering when multiple people and AIs share capabilities.
- Remote Work: maintaining shared understanding while preserving local autonomy across different work environments.
Related concepts
Tool Neutrality and Context Compact, Externalizing Judgment, Remote Work, Automation, AI Multimedia Production Toolchain