synthesis-skills-manager v2.9.1A

Immutable. This exact content never changes and is served at /api/v1/blob/db7c164d4627be6e.

---
name: synthesis-skills-manager
description: "Agent-native skill installer and manager for the synthesis skills ecosystem. Handles installation, drift detection, synthesis merge for conflicts, provenance tracking, and cross-repo coordination. Use when asked to: install skills, update skills, check skill drift, manage skills, skill status, skill inventory, sync skills."
license: "CC0-1.0"
depends_on: []
metadata:
  author: "Rajiv Pant"
  version: "2.9.1"
  source_repo: "github.com/synthesisengineering/synthesis-skills"
  source_type: "public"
---

# Synthesis Skills Manager

**Version 2.9.1** checks complete diagnostic record capacity before acceptance
execution. The finite record ceiling is 4,096; the 32 MiB, 10-second and
privacy limits remain enforced. Test batching and coverage are unchanged.

**Version 2.9.0** runs the complete source catalog and acceptance batches with
bounded parallelism. Release verifies authenticated hosted results for the exact
source tree instead of repeating the full test suite. Current publication
authority, selected-client installation and complete installed inventory remain
independently verified. Failed or unavailable candidate evidence blocks shipping.

**Version 2.8.11** runs acquisition entry, repair, regression and optional
service-doctor controls in both the hosted and gated release catalogs.

**Version 2.8.10** retains canonical private fixture custody for every release
check, including nested checks, with bounded output and exact command receipts.
Production path protections and the full required test catalog remain enforced.

**Version 2.8.9** refuses ambiguous Muse installation inventories and unsupported
plugin command grammar before staging. Native hook support remains separately
verified; complete inventory controls run in local and hosted release checks.
**Version 2.8.7** runs complete autopilot coverage in bounded disjoint groups,
binds checked source identity and isolates required-check environments and caches.

**Version 2.8.6** runs model-catalog provenance and role validation in every
release transaction, matching the declared local and hosted CI groups.

**Version 2.8.5** preserves each pinned marketplace-created native generation
before the next command. A closed cache-parent inventory refuses unknown entries
and changed historical material before another destructive action. Post-command
historical repair retains changed materialized bytes in a verified external
bundle before replacement; ordinary runtime bytecode follows the existing
integrity policy. Interrupted native commands remain failures even after
successful recovery.

**Version 2.8.4** verifies mandatory initial restoration before starting the
existing bounded quiet-window observation. Retained native Git checkouts are
copied with complete bytes, types and modes into a durable store outside the
client-owned cache before refresh can replace that cache. Cataloged intent and
verified seals distinguish interrupted preservation from missing committed
recovery. Unknown transition roots and damaged recovery refuse refresh. These
bundles have a separate retention disposition; they are not silently deleted or
folded into the public historical archive.

**Version 2.8.3** verifies the native current Codex version against its
published source inventory while preserving the client-owned checkout and its
metadata. Historical roots retain exact recovery integrity. Verified historical
Git-backed displacements remain available with an explicit recovery disposition;
unsafe source, Git and path boundaries fail before replacement.

**Version 2.8.2** binds installed lifecycle reconciliation to the exact verified
release and existing desired state. Muse refresh first verifies the installed CLI exposes explicit plugin commands and a readable installation inventory. A top-level help fallback, missing plugin grammar, or unreadable inventory refuses before staging. Inventory absence requires one complete bounded JSON document with unique keys and plugin identities; unknown rows and missing or ambiguous installed sources refuse before staging. Version readback uses the same inventory owner; staged manifests do not prove native hook support. Muse refresh admits only owned bundle roots,
verifies staged content before replacement and retains displaced bytes for
recovery. A missing source with a retained interrupted transition remains blocked
until its recovery is resolved; an arbitrary recorded path is never erased.

**Version 2.7.0** (2026-09-04) deduplicates historical payloads in a SQLite
content-addressed archive. Immutable per-version manifests preserve paths,
types, modes and metadata; restoration creates independent files. SHA-256
validation covers every payload and manifest, beyond database structure checks.
The complete database, including page overhead, stays within the unchanged
512 MiB budget. A verified candidate replaces the store atomically; legacy
trees move before deletion only after their complete recovery is verified.
Interrupted retirement resumes against the committed version manifest. The
archive-aware standalone guardian and supervisor are verified before migration
or native refresh. Source integrity includes permissions, not just bytes.

**Version 2.6.3** (2026-09-03) makes synchronous historical-cache verification
wait up to 120 seconds for the shared transition lock. This covers a complete
budgeted historical-root restore and serializes an
onboarding completion check behind an ordinary background guardian pass instead
of reporting a false release collision. Watch and `--once` work remain
nonblocking; persistent publisher contention still fails closed after the
bounded wait.

**Version 2.6.2** (2026-09-03) makes the publisher and the durable guardian
consume one canonical integrity policy. The release snapshot and quiet-window
verifier now tolerate the same narrowly bounded runtime bytecode as the
guardian, so an older task can keep invoking its hook throughout a refresh
without invalidating its preserved root. That boundary includes CPython's
numeric-suffixed atomic-write files. A differing historical root is replaced
as one directory instead of copying through untrusted entries, so a nested
symlink or hard link cannot redirect repair writes outside the cache. All other
source and filesystem-type checks remain fail-closed.

**Version 2.6.1** (2026-09-03) bounds runtime-bytecode exclusions to real
Python cache directories; unknown files, links and source changes still fail.
Shipped Python hooks use `-B` to avoid creating bytecode there.

**Version 2.6.0** (2026-09-02) includes immutable public CLI activation in the
gated publication and dual-client verification transaction. The launcher binds
the verified version tag, commit, Git tree and content digest.

**Version 2.5.1** (2026-09-02) prioritizes the newest historical Codex roots
during recovery, so the version most likely to be pinned by a just-updated task
returns first instead of last. The onboarding update engine now consumes the
durable guardian synchronously before reporting a successful Codex refresh and
verifies the invoking task's exact hook tree. The budgeted, tag-backed archive,
single-writer transition lock, supervisor, refusal of unsafe or differing
content, and client-owned newest-version boundary remain unchanged.

**Version 2.5.0** established the durable background guardian and kept recovery
digests scoped to tracked release content rather than client-owned metadata.
The whole-system onboarding suite and its scaffold/component catalog audit
remain required release checks.

Manage synthesis skills across a three-repo architecture. Skills are executable
methodology. Public skills are also packaged as a native plugin for clients that
support plugins; private and shared skills remain native user/project skills.

## Architecture

Three skill repositories, each with a different access level:

| Repo | Type | Access | Purpose |
|------|------|--------|---------|
| `synthesis-skills` | public | Open source | General-purpose methodology skills |
| Personal skills repo | personal | Owner only | Owner-specific skills |
| Team shared skills repo | shared | Team members | Cross-project team skills |

**Deployment targets:**

1. Public `synthesis-skills` plugin — install through both the Claude and Codex
   marketplaces.
2. `~/.claude/skills/` — private personal skills for Claude Code.
3. `~/.agents/skills/` — private personal skills for Codex and the Agent Skills
   convention.
4. `~/.cursor/skills/` — direct deployment for Cursor when present.
5. `/path/to/project/.claude/skills/` — Claude project skills when a shared
   repository intentionally uses project scope.
6. `/path/to/project/.agents/skills/` — portable project skills, including
   Codex discovery.

`~/.codex/skills/` is not a source-managed deployment target. Codex may own
system skills there; copying synthesis skills into both `.codex` and `.agents`
creates duplicate discovery.

## Provenance Tracking

Every installed skill has a `.source.json` file (gitignored in source repos):

```json
{
  "source_repo": "github.com/synthesisengineering/synthesis-skills",
  "source_type": "public",
  "source_path": "skills/synthesis-thinking-framework/SKILL.md",
  "source_commit": "abc123...",
  "installed_at": "2026-03-23T14:30:00Z",
  "installed_by": "synthesis-skills-manager"
}
```

## Commands

When the user asks you to manage skills, execute the appropriate command:

### `install [repo] [skill-name]`

Install a skill from a source repo to the target location.

1. Read the skill's SKILL.md from the source repo
2. Check if a skill with the same name already exists at the target
3. If it exists, compare whole-directory checksums.
4. If different, preserve a backup and resolve drift in the source repository.
   Never merge only into the installed copy.
5. Copy the source skill directory to the target.
6. Write `.source.json` with current commit hash and timestamp.
7. Check dependencies across all active source/plugin/user-skill roots.
8. Report result.

### `update [repo]`

Update all skills from a source repo.

1. For each skill in the source repo, run the install flow
2. Report: updated, skipped (unchanged), merged (drift resolved)

### `status`

Show the state of all installed skills.

1. Inspect the enabled `synthesis-skills` plugin in Claude and Codex.
2. Scan private/shared target directories for skill directories.
3. Group copied skills by `source_repo` from `.source.json`.
4. For each copied skill:
   - Read `.source.json` for provenance
   - Compare installed SKILL.md checksum against source (if source repo is available locally)
   - Report: OK, DRIFT (local changes), MISSING (in source but not installed), ORPHAN (installed but not in any known source)
5. Detect duplicate public skills across plugin and user-skill roots.
6. Check all dependencies across the combined inventory.
7. Validate access hierarchy.

### `drift [skill-name]`

Show what changed between installed and source versions.

1. Read both SKILL.md files
2. Show a diff summary (sections added, removed, modified)
3. Recommend: reinstall source, port the installed improvement into source, or
   perform a source-side synthesis merge.

### `merge [skill-name]`

Perform synthesis merge when drift is detected.

This is the key differentiator from package managers. Skills are methodology — when the installed copy and source both have legitimate changes, the right answer is synthesis merge, not "pick a version."

**Merge protocol:**

1. Read the source version (from repo)
2. Read the installed version (from target)
3. Read `.source.json` to find the common ancestor commit
4. Identify what changed in each:
   - Source changes: new sections, updated instructions, bug fixes
   - Local changes: customizations, environment-specific tweaks, improvements
5. Synthesize:
   - Keep all source structural changes (new sections, reordered steps)
   - Keep all local customizations that don't conflict with source intent
   - For true conflicts (both changed the same instruction differently), present both versions and ask the user
6. Write the merged result to the source repository.
7. Commit and push every configured source remote.
8. Reinstall or update the plugin/user-skill deployment.
9. Verify the installed result against source.

**What makes this different from git merge:** Git merges text. This merges methodology. An AI agent understands that moving a step from section 3 to section 2 is not a conflict with adding a new substep to section 3 — even though a text-based merge would flag it.

## Dependency Access Hierarchy

Strict rules — enforced on every install and status check:

| Skill Type | Can Depend On |
|------------|---------------|
| public | public only |
| private | public + private |
| shared | public + shared |

**No cross-collection private dependencies.** If a private skill needs functionality from a shared skill (or vice versa), the dependency must be promoted to public first.

### Checking Dependencies

Read `depends_on` from SKILL.md frontmatter:

```yaml
depends_on: ["synthesis-thinking-framework", "synthesis-content-quality"]
```

For each dependency:
1. Check the combined enabled-plugin and user/project-skill inventory.
2. Read `.source.json` for copied skills or plugin source metadata for public
   plugin skills.
3. Validate against the hierarchy table
4. Report warnings (missing) or violations (hierarchy breach)

## Configuration Separation

Skills with user-specific values have a `## Configuration` section with a table:

```markdown
## Configuration

| Setting | Value | Description |
|---------|-------|-------------|
| `daily_plans_path` | `daily-plans/` | Relative to the personal ai-knowledge repo; daily plans live at top-level after phase 2 |
```

When installing a skill that has a Configuration section:
1. Note the configuration table to the user
2. If the user has previously configured values for this skill (in a prior installation), preserve them
3. Never overwrite Configuration values during update — merge them

## Workflow Examples

### First-time setup

```
User: "Install all my synthesis skills"

1. Add the public repository as a marketplace in Claude and Codex.
2. Install and enable the `synthesis-skills` plugin in all three clients.
3. Install personal skills to `~/.claude/skills/` and `~/.agents/skills/`.
4. Install shared project skills to `.claude/skills/` and `.agents/skills/`.
5. Write `.source.json` for every copied private/shared skill.
6. Run `synthesis-agent-conformance` to check duplicates and dependencies.
7. Report the source version and enabled runtime versions.
```

### Drift detected during update

```
User: "Update my skills"

1. Pull latest from each repo
2. For synthesis-daily-rituals: installed checksum ≠ source checksum
3. Read both versions
4. Installed has: added clickable link instruction (local improvement)
5. Source has: no changes since last install
6. Port the improvement into source, commit, push, and reinstall.
7. Report the source commit and zero-drift verification.
```

### Both sides changed

```
User: "Update my skills"

1. Pull latest from each repo
2. For synthesis-article-writing: installed checksum ≠ source checksum
3. Source has: new Phase 3 critical review section
4. Installed has: custom anonymization examples added
5. Decision: synthesis merge needed
6. Merge: keep new Phase 3 from source + keep custom examples from local
7. Report: "synthesis-article-writing: merged (source added Phase 3, kept local customizations)"
```

## Error Handling

- **Source repo not available locally:** Report which repo is missing, suggest cloning it
- **Circular dependencies:** Detect and report (should never happen with the hierarchy)
- **Corrupted .source.json:** Reinstall from verified source; do not infer
  provenance from the installed copy.
- **Skill with no frontmatter:** Warn — skill doesn't follow the standard. Install anyway but flag for review.

## Implementation Notes

This skill is designed to be executed by an AI agent. The agent reads files,
compares methodology, and resolves conflicts in source. Deterministic installers
and conformance scripts own copying, manifests, checksums, and health checks.

The `install.sh` scripts in each repo serve as bootstrap/fallback installers for environments without an AI agent. They handle the mechanical parts (copy, provenance, checksums) but cannot do synthesis merge — they overwrite on conflict. Drift detection covers the whole skill directory (scripts, references, data tables — not just SKILL.md); every drifted copy is saved to `${XDG_CACHE_HOME:-~/.cache}/<repo-name>-backups/<UTC-run-stamp>/<target>/<skill>/` before overwrite, and the end-of-run warning names each drifted skill and the backup path. Backups are pruned to the 10 most recent runs.

Before verification, follow [verification custody](../synthesis-implementation-integrity/references/verification-custody.md): use an isolated copy by default; shared-checkout checks must restore only their own authenticated changes, preserving concurrent edits and unresolved evidence.

## Gated cross-client release

Before invoking `release.py`, read and follow the complete
[gated release protocol and required checks](references/release-protocol.md).
It owns preflight, source and behavioral acceptance, publication, selected-client
installation, cache recovery, lifecycle reconciliation and independent readback.
The linked protocol is mandatory; a reported client version alone is insufficient.
Its bounded check groups must cover the complete test inventory without stale
bytecode or inherited test selection. Hold the release train through delivery.

The release publishes the accepted immutable commit atomically to `refs/heads/main`,
`refs/heads/stable`, and `refs/tags/vX.Y.Z`. Before refreshing Codex, it snapshots
every real versioned cache root retained by a client. The guardian protects
every archived version except the newest client-owned version, preserving
client-owned metadata. Synchronous recovery waits for a verified transition; the
watcher and explicit one-shot mode stay nonblocking. See the linked protocol for
source binding, archive limits, cleanup, installation and readback requirements.

## The stable path — never pin a version

Instruction files and long-lived sessions that pin a versioned cache path
(`…/synthesis-skills/4.59.0/…`) go stale on the next release — on 2026-09-01
a session on a months-old engine read the shared coordination board as
corrupt, and a workspace's own day-start commands pinned a release twenty
versions behind. The gated release therefore maintains a synthesis-owned,
version-independent path:

```
~/.synthesis/plugins/synthesis-skills/current  ->  <the verified install root>
```

It lives outside the client-owned caches (which the clients replace on their
own schedule), is repointed atomically by `release.py` only after the selected
clients verified the version, and is refused when the target root is not a
verified install (`install.stable-path`). Reference it from instruction
files and scripts instead of a version; `--install-only` repoints it on a
new machine. `SYNTHESIS_STABLE_PLUGIN_ROOT` overrides the parent for tests.

Two kinds of caller, two paths. Hooks and guards that must run even when no
plugin is installed, or while an install is mid-transition, resolve their
engine from a source checkout (a resolver that does so belongs with the
hook, not in an instruction file). Everything an agent is *instructed* to
run — day-start commands, board verbs, gates — pins the stable path: the
installed pointer is the verified release, while a source checkout may be
mid-transaction on a feature branch. `conformance.py parity` checks the
pointer daily (`parity.stable-path`): missing, dangling, or behind the
installed version all fail, so a stale pin is caught before a command runs
from it.

## The release train — one publisher at a time

On 2026-09-01, two agent sessions releasing this repository in parallel
overtook each other five times — each merge to `main` turned the other's open
PR CONFLICTING with checks never run — and once both authored the same
version number. Coordination-board messages failed as a serializer because
an autonomous session mid-transaction does not re-read the board between
authoring a version and merging.

Serialization is now mechanical. The train is a **virtual coordination-board
resource**, `release-train:synthesis-skills`, claimed like any source area:

```bash
python3 <synthesis-project-management-root>/scripts/coordination.py claim \
  ... --area release-train:synthesis-skills --area <your real areas>
```

The board's existing claim-overlap refusal is the mutual exclusion (two
holders cannot coexist; the lease serializes it across machines), and
`release.py`'s preflight enforces possession: on any machine that has a
coordination board, every mode except `--install-only` refuses unless the
running process's session — from `SYNTHESIS_COORDINATION_SESSION` or an
owned active-project pointer — holds the train. Machines without a board
(outside contributors) pass with a notice; adoption travels with the board.

Protocol: claim the train **before authoring the version bump**, hold it
through merge and `release.py`, and release or narrow the claim immediately
after the gated release completes. A crashed holder blocks the train by
design; the user — never another agent on its own initiative — frees it via
the stale-claim review (`coordination.py stale`).

## Source Update Protocol (NON-NEGOTIABLE)

When updating any skill — whether one file or several — follow this exact sequence. Do not deviate. **Manual file copies to install targets are NOT installation.** They create drift between what is committed, what is pushed, and what is locally active. The protocol below exists because that drift has happened before and must not happen again.

### The sequence

1. **Edit the skill in its source repo.** Public skill paths are
   `<source-repo>/skills/<skill-name>/SKILL.md`; private/shared repositories use
   their declared source layout. Never edit plugin caches or installed copies
   under `~/.claude/skills/`, `~/.agents/skills/`, or client caches.

2. **Verify the source repo state.** `git status` to confirm only the intended files changed. `git diff` to review the actual content of every change.

3. **Commit with a generic message** per public-repo commit hygiene. "Update skills" or similar. No skill names, no version arc, no rationale that exposes the work that motivated the edit.

4. **Identify all configured push remotes.** `git remote -v`. The skills repos may have multiple push remotes; the source-of-truth state is "the union of all configured push remotes is up to date."

5. **Push to EVERY configured push remote**, not just `origin`. Loop over the remote names from step 4. Single-remote repos still use this step — it just iterates once.

6. **Refresh deployments using the source’s canonical path.** For public
   skills, update/reinstall the `synthesis-skills` plugin in Claude and Codex.
   For private/shared skills, run the repository installer, which deploys to
   `~/.claude/skills/` and `~/.agents/skills/` (plus declared project/Cursor
   targets), writes provenance, and reports whole-directory drift.

7. **Verify zero drift.** After `install.sh` completes, `diff -q` each installed copy against the source. They must be byte-identical:
   ```bash
   for target in ~/.claude/skills ~/.agents/skills ~/.cursor/skills; do
     for skill in <changed-skill-names>; do
       diff -q "<source-repo>/$skill/SKILL.md" "$target/$skill/SKILL.md"
     done
   done
   ```
   Any output from `diff -q` is a failure. Investigate and re-run `install.sh update`.

### What you must NOT do

- **DO NOT** manually `cp` SKILL.md files from the source repo to install targets. The install targets are managed by `install.sh`, which writes `.source.json` provenance and runs drift detection. Manual `cp` skips both and produces files that look installed but are not canonically so.
- **DO NOT** edit plugin caches or installed copies under
  `~/.claude/skills/`, `~/.agents/skills/`, or client caches directly.
- **DO NOT** skip the push step before reinstalling. `install.sh` pulls from the configured remote; if you have not pushed, the install will refresh from a stale remote state and silently revert your local edits.
- **DO NOT** skip the verify step. "I ran install.sh" is not the same as "the install matches the source." The drift check (`diff -q`) is the proof.
- **DO NOT** ask for permission to push as if push were optional. Push is part of the install workflow, not a separate decision. If you have permission to update a skill, you have permission to push the source repo. Pausing between commit and push is the failure pattern that produced the 2026-04-29 incident — it leaves three different states of the truth (working tree, remote, installs) and the agent in the middle.

### Why these rules are non-negotiable

The 2026-04-29 incident: an agent edited four skill files in source, manually copied them to install targets to "install" them, then waited at the wrong gate before pushing. The result was three different states of the truth — source repo working tree (had the changes), GitHub (did not have the changes), install targets (had locally-copied files that drifted from what `install.sh update` would have produced). When `install.sh update` was finally run, it detected and overwrote the manually-copied drift. That detection-and-overwrite happened to be safe in that case, but it was luck, not design — the manual copies could just as easily have included an in-flight edit that the agent had not yet propagated to the source.

The protocol above eliminates the asymmetry. Source is the only edit point. Push happens before install. Install runs the canonical script. The verify step proves the canonical state. There is no place for three-states-of-truth to sit.