Synthesis onboarding
Skill synthesisengineering/synthesis-skills/skills/synthesis-onboarding
One-command installer and doctor for the synthesis ecosystem: installs the synthesis-skills plugin into Claude Code and/or Codex, scaffolds ai-knowledge-<workspace> repos, and layers organization knowledge bases and shared skills from a declarative org manifest. Idempotent, upgrade-aware, fail-closed. Use when asked to: onboard, install synthesis, set up the ecosystem, set up a knowledge base, new machine setup, install the knowledge base for me, onboarding installer, org onboarding, verify my install.From its SKILL.md
npx -y skills add synthesisengineering/synthesis-skills --skill synthesis-onboardingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 23 stars23 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as CC0-1.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
9.4 KB, as published. Nobody here has run it
Synthesis Onboarding
Everything a new person needs to go from a bare machine to a working synthesis setup — close to one command plus an auth step. Built for two audiences at once: engineers who want a scriptable, verifiable installer, and non-engineering colleagues who should never see a complicated question.
Three ideas carry the whole design:
- One engine, org manifests. The engine is generic. An organization
ships configuration — a
.agents/onboarding.yamlin its knowledge-base repo — never installer code. Any org gets a colleague installer by writing one YAML file and a three-line wrapper script. - Convergence, not scripts. Every run states desired state and moves the machine toward it. Re-running is always safe: it updates, repairs half-finished installs, and reports instead of clobbering anything a person edited.
- Fail closed and loud. Stale caches, unknown manifest keys, and unverifiable state stop with plain-language instructions. A check that cannot run never looks like a check that passed.
The two front doors
Terminal (works with nothing pre-installed except macOS):
curl -fsSL https://raw.githubusercontent.com/synthesisengineering/synthesis-skills/main/onboard.sh | sh
Agent (when Claude Code or Codex already has this plugin): ask the assistant to "set up the synthesis ecosystem" — it runs the same engine:
python3 <this-skill>/scripts/onboard.py install
Organization members use their org's wrapper instead (one command from the
org's knowledge-base repo), which calls the same engine with the org's
manifest. See references/org-manifest.md.
Commands
onboard.py install [--manifest PATH] [--dry-run] [--json]
[--clients claude,codex] [--no-plugin-cli]
[--with-personal-workspace NAME]
onboard.py update # explicit native-plugin refresh + install convergence
onboard.py doctor [--manifest PATH] [--json]
onboard.py init-workspace --workspace NAME [--remote URL]
onboard.py uninstall [--dry-run]
Exit codes (guard contract): 0 fully converged / healthy; 1 errors or a
step that needs the user (auth, git identity) — re-run after acting; 2 the
engine could not establish ground truth (no git, invalid manifest).
What install does, in order
| Phase | Behavior |
|---|---|
| preflight | Verify git (guides through xcode-select --install if missing); detect clients via SYNTHESIS_CLAUDE_BIN/SYNTHESIS_CODEX_BIN → PATH → well-known locations (incl. the ChatGPT app's bundled codex). Absent clients are skipped, not fatal. |
| ecosystem | install adds a missing native plugin and checks an existing one without replacing its live cache. update explicitly refreshes existing native plugins, verifies the resulting version when running from a source checkout, and states the client-restart and receipt-verification boundary. A first installation may use the repo's direct-copy fallback when a client lacks the plugin CLI; an installed native plugin is never replaced by duplicate copies. |
| org-skills | For each manifest skills_repos entry: SSH-first clone/refresh into the engine cache, then delegate to that repo's own installer with its source pinned to the fresh cache. A cache that cannot refresh stops the step (SYNTHESIS_ONBOARD_ALLOW_STALE=1 overrides, loudly). |
| knowledge-bases | Clone to ~/workspaces/<org-workspace>/<name>, or adopt an existing clone found by matching remotes (never moved). Superseded remotes are repointed to the manifest primary (git remote set-url). Fast-forward pull when clean. When the repo ships .githooks and no global hooks engine is active, wire repo-local core.hooksPath so protective hooks run on fresh clones. Auth failures print the manifest's auth_help and mark the step "needs you" — the run continues and the re-run completes it. |
| workspace | Generate ~/workspaces/<org-workspace>/AGENTS.md (+ CLAUDE.md = @AGENTS.md): the welcome, what-you-can-ask list, KB contract pointers. |
| migrations | Apply the manifest's skill tombstones (remove / rename / superseded-by-public) to user-level skill copies — archive first, always. |
| doctor + welcome | Verify everything, then greet: what to try asking, where the guides are, and that re-running is always safe. |
Receipts and the no-clobber rule
State lives at ~/.synthesis/onboarding/receipts.json: every generated
file's checksum, adopted repo locations, run history. A generated file whose
current content matches its receipt is engine-owned and may be updated
(previous copy archived under ~/.synthesis/onboarding/backups/). A file a
person edited is never overwritten — the engine warns and moves on.
uninstall removes only receipt-owned files (archived first) and never
touches knowledge-base clones or plugins.
Safe plugin upgrades
Run onboard.py update only after closing other Claude Code sessions and
Codex tasks that use this marketplace, and make it the invoking session's last
action before restarting the client. Resume the same root conversation only
when its exact transcript-bound SessionStart receipt and loaded skill metadata
match the installed release. Start a new conversation/task only if restart
verification fails or the client cannot rehydrate it. Native clients resolve
plugin hooks to versioned cache paths; replacing that cache can invalidate hook
commands already loaded by another live session. Ordinary install and
doctor runs never refresh an existing native plugin.
Scaffolding a personal knowledge workspace
onboard.py init-workspace --workspace alice [--remote [email protected]:alice/ai-knowledge-alice.git]
Creates ~/workspaces/<name>/ai-knowledge-<name>/ with projects/index.yaml,
lessons/, AGENTS.md + CLAUDE.md adapter, README, git init and first
commit — the synthesis-project-management container shape. Project content
stays agent-authored (that skill's "examine an example and adapt" principle);
this scaffolds the container so day one needs no hand-wiring.
Configuration
| Env var | Default | Purpose |
|---|---|---|
SYNTHESIS_ONBOARD_HOME | $HOME | Root for all install targets (tests use a sandbox home) |
SYNTHESIS_ONBOARD_STATE_DIR | ~/.synthesis/onboarding | Receipts + backups |
SYNTHESIS_WORKSPACES_ROOT | ~/workspaces | Where workspaces and KBs live |
SYNTHESIS_ONBOARD_CACHE_DIR | XDG cache | Org repo caches |
SYNTHESIS_ONBOARD_SOURCE_DIR | this repo | synthesis-skills checkout to install from |
SYNTHESIS_CLAUDE_BIN / SYNTHESIS_CODEX_BIN | auto | Client binary override; set-but-empty means "treat as absent" |
SYNTHESIS_ONBOARD_ALLOW_STALE | unset | Accept an unrefreshable cache (loud) |
SYNTHESIS_ONBOARD_NO_PLUGIN_CLI | unset | Force file-copy fallback |
Relationship to neighbors
- install.sh (repo root) — the per-skill copy fallback this engine delegates to when a client lacks native plugin support.
- onboard.sh (repo root) — the curl-able bootstrap: ensures git, clones or refreshes this repo, hands off to this engine.
- synthesis-skills-manager — the agent-run protocol for skill authors (multi-repo source management, synthesis merges). This engine is the end-user installer; it never edits sources.
- synthesis-agent-conformance — the deep parity audit for maintainers.
onboard.py doctoris the end-user health check; conformance remains the authoritative source/runtime/handoff verification. - synthesis-project-management / context-lifecycle — define the
workspace shape that
init-workspacescaffolds.
Supported client surfaces
- Claude Code, ChatGPT Codex desktop, and Codex CLI are first-class native plugin surfaces.
- Codex IDE is reported as
UNSUPPORTED: it does not load plugins, and its shared user-skill roots cannot hold a second public copy without creating duplicate definitions in desktop/CLI. - A plugin change becomes usable only after a genuine client lifecycle reload. Preserve the synthesis checkpoint, restart the client, and verify the exact current-plugin SessionStart receipt plus loaded skill metadata. A same-root conversation may continue when that proof passes; installed files alone do not prove a reload.
Safety rules
- Never delete without archiving first; never force-push anything.
- Never overwrite a file the user edited (receipts decide ownership).
- Never enumerate or clone repos the manifest does not name.
- Org manifests are validated fail-closed: unknown keys are errors.
- The engine runs on python3 stdlib alone (PyYAML optional) so a fresh Mac with Command Line Tools needs nothing else.
- v1 targets macOS; the engine avoids macOS-only code paths so Linux and Windows (WSL first) can follow without redesign.