Synthesis Skills is one plugin for Claude Code, Codex and Muse. It carries 69 skills
for software engineering, writing, project management, correspondence and daily
operations, plus a small runtime: a synthesis command and four lifecycle hooks. The
skills follow the Agent Skills standard. The runtime keeps
project state in git, keeps parallel sessions from overwriting each other, holds sends
and deploys until a person approves them, and refuses destructive commands.
Version 5 rebuilt the runtime from its requirements and rewrote every skill into one format. CHANGELOG.md has the full history; this page describes what is here now.
- People who work with coding agents for weeks at a time, on software, writing, research or operations, and need a project to survive compaction, a restart, a switch between harnesses, or a move to another Mac.
- People who run several agent sessions at once and need them to see each other's work and stay out of each other's files.
- Anyone who wants outgoing messages and production deploys to wait for their approval, enforced by a hook rather than by the agent's memory.
- Teams and organizations that want the same methods and rules in every member's agents, from a shared configuration repository.
The methodology skills (writing, review, planning, reasoning) are plain instructions and work in any client that reads Agent Skills. The skills that coordinate sessions or guard actions need the runtime, which installs in Claude Code, Codex and Muse.
Every skill states its purpose in one paragraph, then its binding rules, then a contents
list that says what each linked file holds and when to read it, then its procedure. Each
SKILL.md stays under 8,000 bytes so that every harness reads all of it; longer
material lives in reference files. The skill list is below.
All four run ~/.synthesis/v5/bin/synthesis-hook <event>. That path and its text never
change between releases, so a harness's approval of the hook survives upgrades.
| Event | What it does |
|---|---|
| SessionStart | States the local time; injects the active project's PRIME-DIRECTIVE.md and the current-state block of its CONTEXT.md, this session's autopilot run if it has one, one line of ritual state, and a count of unread board messages. Claude Code and Codex run it again after compacting the conversation, so the brief comes back on its own. It also brings the installed runtime up to the plugin version the harness loaded. |
| UserPromptSubmit | Reads your prompt for approve <code> and grants that pending request. Delivers up to five unread board messages. |
| PreToolUse | Checks shell commands and message, calendar, mail and sharing tool calls before they run (see below). If its config can't be read or a guard fails, the call is blocked, never waved through. |
| Stop | Sends the agent's final reply back once if it uses deferring language, quotes someone with words that appear nowhere in the session, or (when reply_file_links is set) names a file without a clickable absolute-path link. For an autopilot run, it asks the session to continue to the plan's next open item. It fails open, since a turn-end check that fails closed would loop forever. |
What PreToolUse holds:
- Sends and drafts (Slack, Gmail, Mail and similar tools, plus any you add with
send_tools). The text must first pass yourforbidden_phrasesand the format rules, such as HTML email with whole paragraphs, and call anyone yourpreferred_nameslists by the name they go by when the call identifies them. Then the agent shows you the exact text and recipient, and you typeapprove <code>in your own message. The approval covers that exact call once and expires after 15 minutes. Only the UserPromptSubmit hook can grant it, because it reads the prompt you typed, which the agent cannot write. - Deploys (
wrangler deploy,vercel --prod,netlify deploy --prod,firebase deploy,npm publish,twine upload,gh release create, a push to a repository listed inpush_deploys, and your owndeploy_patterns) need approval of the exact command. A deploy that would put a page live before its stated date, or change the date of a published page, is refused even with approval. A second deploy of the same site within 45 minutes needs its own approval. - Destructive commands. A recursive
rmof/, your home folder,~/workspaces, any folder directly inside it, a root you list inprotected_roots, or any git repository is refused, and so is a force push tomainormaster. - Account routing. Calendar, mail and sharing calls are checked against the account
you configure for the workspace a session runs in, since an invitation sent from the
wrong account cannot be unsent. Nothing is routed until you set
account_routing.
The configuration lives in ~/.synthesis/v5/config.json. A missing file means the
defaults above. The keys are documented in the
guardrails configuration and
the message guard configuration.
An optional global git hook adds a commit check in every repository. It blocks
credentials, private keys and credential files everywhere; unapproved disclosures in
repositories outsiders read, under a commit policy you configure; and commits that touch
another live session's claim. A legitimate line that a disclosure pattern flags passes
once you approve that exact line with the code the check prints; agents never reword it
to get past the check. It then runs the repository's own hooks. Setup asks before turning it on
(--git-hooks); see synthesis-git-hooks.
| Command | What it does |
|---|---|
synthesis use <project> |
Set this session's active project. |
synthesis brief [project] |
Print the project's directive and current state, and any problems with its records. |
synthesis resume <project> |
Pick up a project: directive, state, next actions, plan and warnings (a newer copy elsewhere, upstream changes, other sessions working there). If the project differs from the session's own, it asks first; --switch switches after you agree. |
synthesis who |
List live sessions and their claims (--all includes stale ones). |
synthesis claim <paths> |
Claim absolute paths before writing; a trailing /** claims a subtree. A refused claim names the holder. --take takes over a claim that has been quiet for 8 hours and tells its holder. |
synthesis release [paths] |
Release some or all of this session's claims. |
synthesis msg <address> "<text>" |
Message a session by id, short name or project:<id>. An ambiguous address is refused, never guessed. --durable reaches every session that works on the project. |
synthesis inbox |
Show and mark unread messages. |
synthesis worktree create|retire|land |
Create a worktree under a claim, remove a merged clean one, or fast-forward the main checkout to the remote's default branch. |
synthesis handoff -m "<message>" |
Commit and push only the changes inside this session's claims, running every hook. Ends READY, or NOT READY with what blocks it. |
synthesis approvals |
List sends and deploys waiting for your approval. |
synthesis doctor |
Check the runtime, each harness's installed plugin, hook wiring and trust, and Codex's settings. --latest also asks whether a newer release exists. |
synthesis install, synthesis uninstall |
Install the runtime from a plugin folder, or remove what install wrote while keeping config and the board. |
synthesis version |
Print the runtime version. |
The installer targets macOS. It needs git, python3 (the /usr/bin/python3 that
ships with macOS is enough) and at least one of the harnesses.
curl -fsSL https://raw.githubusercontent.com/synthesisengineering/synthesis-skills/stable/onboard.sh | shonboard.sh keeps a source checkout at ~/.synthesis/v5/source on the stable branch
and runs the onboarding skill's
setup.py. Setup installs the plugin in
every harness it finds, using each harness's own commands; sets the Codex settings it
needs; installs the runtime and links ~/.local/bin/synthesis if that name is free;
asks whether to turn on the commit check; and on a fresh install asks two questions for
a first config. Every step is safe to rerun.
Variants:
# Bring an existing workspace's repositories onto a new Mac
curl -fsSL https://raw.githubusercontent.com/synthesisengineering/synthesis-skills/stable/onboard.sh | sh -s -- workspace
# Join an organization that publishes a synthesis configuration repository
curl -fsSL https://raw.githubusercontent.com/synthesisengineering/synthesis-skills/stable/onboard.sh | sh -s -- --org-repo URLTo follow the development branch or pin a release, set SYNTHESIS_REF for sh, as in
curl -fsSL .../onboard.sh | SYNTHESIS_REF=v5.0.0 sh. The
onboarding skill and its
harness reference cover
every option, including --dry-run, --no-input and the day-end launcher.
Setup's plugin step installs into only the harnesses you name, with no questions and
no workspace step:
git clone --branch stable https://github.com/synthesisengineering/synthesis-skills.git ~/.synthesis/v5/source
python3 ~/.synthesis/v5/source/skills/synthesis-onboarding/scripts/setup.py plugin --clients codex--clients takes claude, codex, muse or a comma-separated list. The step installs
the plugin with that harness's own commands, installs the runtime, links the synthesis
command, and for Codex sets [features] hooks = true and raises
project_doc_max_bytes to at least 98,304 in ~/.codex/config.toml, after a backup.
These are the native commands it runs, if you would rather type them yourself:
# Claude Code
claude plugin marketplace add synthesisengineering/synthesis-skills@stable
claude plugin install synthesis-skills@synthesis-engineering
# Codex
codex plugin marketplace add synthesisengineering/synthesis-skills --ref stable
codex plugin add synthesis-skills@synthesis-engineeringMuse installs from a local bundle that setup builds, so it has no standalone command.
The native commands give you the skills and the hooks, but not the Codex settings or the
~/.local/bin/synthesis link. In Claude Code the SessionStart hook installs the runtime
from the plugin folder the first time it runs; the command is then at
~/.synthesis/v5/bin/synthesis.
- Restart each harness. A restart reloads hooks and skills; you can resume the conversation you were in.
- Approve the hooks where the harness asks: in Codex open
/hooksand trust the synthesis hooks; in Muse runmuse plugins approve synthesis-skills. Setup never approves them for you. - Run
synthesis doctor. It prints one line per check and names any hook still waiting for approval.
Without any config, sends, drafts and deploys wait for your approval, the deploy date rules and destructive-command rules apply, and account routing is off.
To update, run the installer again with the plugin step:
curl -fsSL https://raw.githubusercontent.com/synthesisengineering/synthesis-skills/stable/onboard.sh | sh -s -- pluginAn install that follows main or a pinned release keeps it. Sessions already open pick up an upgrade on their own: the hooks run
the new release at once, and at its next prompt each session gets one note naming the release it
moved to and what changed, with the step to refresh any skill text it loaded earlier. To uninstall, run
python3 ~/.synthesis/v5/source/skills/synthesis-onboarding/scripts/setup.py uninstall --dry-run
to see what would go, then again without --dry-run. It removes the plugin from each
harness, restores your previous core.hooksPath, removes the unedited files the install
wrote, and keeps your config and the board.
install.sh remains only so older links keep working; it runs onboard.sh.
Each line comes from the skill's own description. Every skill name starts with
synthesis- to avoid collisions with other plugins.
In Claude Code a skill loads when a request matches its description. In Codex, the
eleven foundational skills (agent-conformance, anti-shortcuts, autopilot, checkpoint,
code-planning, context-lifecycle, grounding-discipline, implementation-integrity,
project-management, skill-router and thinking-framework) load the same way; the rest
are reached through synthesis-skill-router or by name as $synthesis-<name>, which
keeps Codex's skill catalog within its budget.
| Skill | What it does |
|---|---|
| synthesis-project-management | Run projects as markdown records in git and keep parallel sessions from colliding: setup, index, lessons, claims, one context owner, messages, worktrees, handoff. |
| synthesis-project-resume | Start or resume a project in any harness on any Mac with verified context, respecting live claims and surfacing other Macs' changes. |
| synthesis-context-lifecycle | Keep a project's working memory small, current and durable: CONTEXT, REFERENCE and session logs, archiving, deletion units and the records doctor. |
| synthesis-checkpoint | Re-sync a session with ground truth: verified clock, project records, git, dated session entries and board claims. |
| synthesis-autopilot | Run an explicitly delegated whole task to the end from a plan file in the project, unattended when needed. |
| Skill | What it does |
|---|---|
| synthesis-code-planning | Plan and implement code: apply constraints, compare the viable approaches that remain, resolve delegated technical choices, implement with evidence. |
| synthesis-preplan | Lock the architecture decisions for a ticket and hand a reviewable decision set to planning. |
| synthesis-implementation-integrity | Verify an implementation is complete before calling it done: data chains, placeholders, test honesty, environment parity. |
| synthesis-preflight | Pre-merge gate that grades branch, clean tree, tests and types, code audit, temporary workarounds and commit history into a go/no-go verdict. |
| synthesis-code-audit | Score a code diff on ten dimensions with PASS, WARNING, FAIL or UNKNOWN and an overall verdict. |
| synthesis-pr-review | Delta review of a pull request: regression risk, root cause, scope, and handoff to integration. |
| synthesis-review-triage | Prioritize a PR review queue by review gap, CI, age, size and labels, and gate re-reviews. |
| synthesis-codebase-review | Codebase audit methodology with tiers from Essential to Mission-Critical. |
| synthesis-code-integration | The adopt-and-adapt pattern for integrating contributions: lead synthesist, quality gates, cherry-pick safety. |
| synthesis-adversarial-review | Bounded adversarial review by differently shaped agents, with a findings table and sufficiency rulings. |
| synthesis-bitbucket | Work with Bitbucket Cloud through the open-source bkt CLI, with explicit repository binding and write-safety rules. |
| Skill | What it does |
|---|---|
| synthesis-reader-briefing | Brief the reader before drafting a public article from internal material; catches insider context collapse. |
| synthesis-article-writing | Write and review articles: research, drafting, critical review, and review of the title, description and slug as a package. |
| synthesis-article-refresh | Refresh an older published article while keeping the author's voice and its temporal integrity. |
| synthesis-content-framing | Frame synthesis engineering and synthesis coding articles: topic, sophistication, engagement and confidentiality gates. |
| synthesis-content-quality | Detect AI slop and empty substance in prose: model-family fingerprints, substance and depth tests, calibration, ESL safe-harbor. |
| synthesis-writing-pitfalls | Catch human-source bad-writing patterns: humble-bragging, throat-clearing, caveat overload, cliché, register mismatch. |
| synthesis-writing-craft | Positive principles from the writing-craft tradition for agents drafting or editing on a writer's behalf. |
| synthesis-fact-checking | Fact-check claims, quotes, studies, URLs and laundered citations before publication. |
| synthesis-link-research | Find authoritative links for people and organizations, and recover dead URLs in archives. |
| synthesis-content-distribution | Share content on social platforms: a brief, posts per platform, social-register checks, follow-up. |
| synthesis-voice-profiler | Build a voice profile from writing samples, as a section for CLAUDE.md or AGENTS.md. |
| synthesis-clean-text | Enforce clean-text and no-hidden-marker requirements and state what can and cannot be verified about statistical text marks. |
| synthesis-text-provenance | Plan, record and audit text provenance for hosted and open-weight models; not for defeating provider marks or evading detectors. |
| Skill | What it does |
|---|---|
| synthesis-agent-correspondence | Compose and send honest agent correspondence: whose words and whose hands, personas, disclosure signatures, send gates. |
| synthesis-concise-messaging | Condense a message to five sentences or fewer. |
| synthesis-executive-communication | Translate technical work for non-technical executives and boards. |
| synthesis-slack-sync | Sync Slack channels, DMs and threads to local transcripts and update the daily plan. |
| synthesis-inbox-cleanup | Manifest-driven cleanup for iCloud and IMAP, Microsoft 365 and outlook.com, and Gmail, with prompt-injection defenses. |
| synthesis-local-messaging | Read an authorized window of local iMessage or WhatsApp data into pointer-only notes, and send one approved iMessage. |
| Skill | What it does |
|---|---|
| synthesis-daily-rituals | Day-start, day-end, mid-day sync and the weekly review across every declared channel, mailbox and repository. |
| synthesis-catchup-ledger | Reconcile missed and pending commitments after a break into a dated catch-up ledger. |
| synthesis-chief-of-staff | Chief of staff and executive assistant duties: meeting triage, scheduling, look-ahead reviews, holds, travel, follow-ups. |
| synthesis-meeting-prep | Prepare for a meeting with a scannable pack and a capture half, then debrief the transcript. |
| synthesis-meeting-transcripts | Fetch meeting notes and full transcripts into markdown, and verify a record is primary before it supports attribution. |
| synthesis-absence-coordination | Coordinate an absence: notification order, coverage, out-of-office, return sweep. |
| synthesis-decision-packet | Collect five or more parallel decisions in one sitting through a self-contained HTML packet. |
| synthesis-quick-answers | A read-mostly companion session for quick lookups, each answer naming its source and confidence tier. |
| Skill | What it does |
|---|---|
| synthesis-thinking-framework | Five-mode thinking (first principles, systems, complexity, analogical, design) with a pre-response protocol. |
| synthesis-anti-shortcuts | Catch language that hides deferral, dismissal or false consultation; sub-agent dispatch and acceptance hygiene. |
| synthesis-grounding-discipline | Keep output tied to evidence: record only what a source surfaced, prove absence, validate paths before writes or deletes. |
| synthesis-tree-of-thought | Multi-expert collaborative reasoning. |
| Skill | What it does |
|---|---|
| synthesis-agent-guardrails | Configure the guards beyond sends: account routing, deploys and their date rules, destructive commands, the reply check, the provenance scan. |
| synthesis-message-guard | The send guard: no send or draft goes out until you approve that exact call and its text passes the scan and format rules. |
| synthesis-git-hooks | The commit check: credentials everywhere, unapproved disclosures where outsiders read. |
| synthesis-disclosure-policy | Decide whether a real organization or person may be named outward-facing, with a precedent ledger and five tests. |
| synthesis-promotion-gate | Scan a built site for configured internal markers before an approved deploy, and refuse on any hit. |
| synthesis-repo-guard | Find work stranded on this Mac (uncommitted, unpushed, unpulled, detached) in a read-only scan. |
| Skill | What it does |
|---|---|
| synthesis-knowledge-capture | Capture durable session facts in an OKF knowledge base with deduplication, confidentiality routing and provenance. |
| synthesis-kb-edit | Edit, validate and ship knowledge-base changes through the repository's .agents/knowledge-base.yaml workflow. |
| synthesis-okf | Validate, convert and author content for Google's Open Knowledge Format (OKF v0.1). |
| Skill | What it does |
|---|---|
| synthesis-onboarding | Install synthesis on a Mac, bring a workspace onto a new Mac, enroll in an organization, update or uninstall. |
| synthesis-agent-conformance | Audit that synthesis behaves the same in Claude Code, Codex and Muse: installed parity, hooks, instruction adapters, handoff. |
| synthesis-skills-manager | Release this plugin and keep installs true to source. |
| synthesis-skill-router | Route a request to the right synthesis skill while keeping specialist metadata out of Codex's prompt. |
| synthesis-machine-sync | Move work between Macs, and set up or retire a Mac. |
| synthesis-mac-sync | Keep several Macs in step: config through iCloud, repositories through git. |
| synthesis-fleet-secrets | Provision machine secrets from a vault onto a Mac by hand, with nothing in git. |
| Skill | What it does |
|---|---|
| synthesis-model-tiers | Three role labels (judgment, routine, bulk) resolved to current model IDs per provider, so nothing hardcodes a model name. |
| synthesis-local-model-runtime | Profile a computer, recommend open-weight models that fit it, install them and verify inference. |
| synthesis-llm-setup | Set up Claude Projects, ChatGPT GPTs and Gemini Gems with custom instructions and knowledge. |
| synthesis-technical-advisor | Configure an LLM as a senior technical advisor. |
| synthesis-creative-writer | Configure an LLM as a creative writing coach and editor. |
| synthesis-response-merger | Combine several LLM responses into one document. |
skills/<name>/
├── SKILL.md # frontmatter, purpose, binding rules, contents, procedure
├── agents/openai.yaml # Codex display text and implicit-invocation policy
├── references/ # material needed for one step or one situation
│ ├── coverage-map.md # where every rule of the previous version lives now
│ └── preserved.md # retired text, verbatim, with the reason, when any was retired
├── scripts/ # executable parts, when the skill has any
└── tests/ # tests for those scripts
- Binding rules come first: numbered, one or two lines each, with the reason. They are the rules that must hold every time, and they sit where a harness that truncates or re-attaches a skill after compaction still delivers them.
- Contents lists every section and every linked file with a line saying when to read it. No reference file is linked from nowhere.
- References each fit in one read (at most 1,500 lines), and a long one opens with its own contents list.
- Coverage maps record, rule by rule, where the previous version's text went. Nothing
was dropped silently when the skills were rewritten: whatever was not kept is in a
preservedfile with the reason.
The rules and the reasons for them are in docs/skill-format.md;
tests/test_skill_format.py enforces the checkable parts.
Projects live as plain markdown in a git repository, so any session in any harness, on this Mac or another, continues from files rather than from a chat transcript:
ai-knowledge-<workspace>/
├── projects/
│ ├── index.yaml # every project and its status
│ └── <project-id>/
│ ├── PRIME-DIRECTIVE.md # optional; injected at session start and after compaction
│ ├── CONTEXT.md # working state, with a current-state block
│ ├── REFERENCE.md # stable facts
│ ├── sessions/YYYY-MM.md # session history
│ └── resources/artifacts/
└── lessons/
synthesis finds these repositories through knowledge_roots in the config, or else
every ~/workspaces/*/ai-knowledge-*. One session owns a project's CONTEXT.md at a
time; other sessions working on the same project write contribution files for the owner
to reconcile. Switching harnesses on the same Mac needs no commit. Moving to another Mac
is synthesis handoff here, then synthesis resume <project> there. When several agents
contribute, the session log records one attribution line per agent, because different
tools often commit under the same human identity.
The conventions are in synthesis-project-management and synthesis-context-lifecycle. docs/spec/versioning.md states what readers of these records can rely on across versions.
CI runs one command, and you can run the same one locally:
python3 -m pytest -q tests/ skills/It covers the core, every skill's tests, the skill format, budgets and hook latency, and
a source lint (manifests agree, licenses present, no personal paths). Code must run on
Python 3.9. On a machine with the plugin installed, synthesis doctor checks the
installed side. AGENTS.md describes both, and the release process.
Each skill declares its license as an SPDX identifier in the license field of its
SKILL.md, and that identifier selects the terms that apply to the skill's folder:
- CC0 1.0 (public domain dedication, no attribution required): 45 skills, mostly methodology and writing.
- Apache 2.0: 24 skills, mostly those built around executable code.
The core outside skills/ (the synthesis/ runtime, hooks/, install.sh, onboard.sh
and the tests) is Apache 2.0. The plugin manifests declare the package as Apache-2.0 AND CC0-1.0.
- Many of these skills are practical artifacts of synthesis engineering, including synthesis coding, synthesis writing and synthesis project management.
- The article that introduced these skills (March 2026; its install steps predate version 5).
- Slopcheck: the content-quality and fact-checking methods as a web page. tools/slop-detection/manifest.md lets a chatbot load the same methods from URLs without installing anything.
- Why synthesis engineering exists and the runtime contract for adding another harness.
See CONTRIBUTING.md, GOVERNANCE.md and SUPPORT.md.
Created and maintained by Rajiv Pant.