Let me search for a few more specific details before synthesizing.Now let me check the previous conversation transcript for formatting reference.Now let me build the assessment document.Now I have everything I need. Let me synthesize all the research into a comprehensive assessment.

---

## Architecture Assessment: Three-Tier Skills Persistence

**Verdict: Architecture is sound and aligns with OpenClaw's native primitives. Two of your five assumptions have caveats that need attention. One significant community tool (`skillshare`) solves 80% of this problem out of the box and is worth evaluating before building `reinstall.sh` from scratch.**

---

### Assumption Validation

**Assumption 1: `~/.openclaw/skills/` symlinks resolve correctly at skill load time.**

**CAUTION — mostly true, with important exceptions.**

OpenClaw scans skill directories and loads skills based on their SKILL.md files with YAML frontmatter. The normal skill scanner uses standard Node.js filesystem calls that follow symlinks transparently on macOS and Linux. So for the **non-sandboxed main session** (which is your use case), symlinks from `~/.openclaw/skills/meal-tracking/ → ~/markbot-skills/meal-tracking/` will resolve fine.

However, there are two documented symlink trouble spots. First, OpenClaw hardened its bootstrap/sandbox context boundary to reject symlink and hardlink alias bootstrap seed files that resolve outside the source workspace. This applies to **bootstrap files** (AGENTS.md, SOUL.md, etc.), not to the managed skills directory — but it signals that OpenClaw is actively tightening symlink handling and a future release could extend this policy. Second, OpenClaw tightened session path validation in version 2026.2.12, and symlinked directories that worked on earlier versions started failing after the update. This was about `~/.openclaw/` itself being symlinked, not about contents within `~/.openclaw/skills/`, but it's a pattern to watch.

The `skillshare` tool actually has a fallback for exactly this: if symlinks don't work, you can switch to copy mode per target. The fact that a dedicated cross-tool sync utility ships with a copy-mode fallback tells you symlink fragility is a known issue in practice.

**Recommendation:** Symlinks will work today for your non-sandboxed setup. But build `reinstall.sh` so it can trivially switch from `ln -s` to `cp -r` (or `rsync`) if a future OpenClaw update breaks symlink resolution in the managed skills directory. A one-line flag swap is cheap insurance.

**Assumption 2: Skills in `~/.openclaw/skills/` are injected into the system prompt for all agents on the machine.**

**CONFIRMED — this is explicitly documented.**

Shared skills live in `~/.openclaw/skills` (managed/local) and are visible to all agents on the same machine. The docs are unambiguous: in multi-agent setups, each agent has its own workspace, meaning per-agent skills live in `<workspace>/skills` for that agent only, while shared skills live in `~/.openclaw/skills` and are visible to all agents on the same machine.

Skills are injected into the agent's system prompt when their tools are available. The injection uses `formatSkillsForPrompt` and produces a compact XML list. The cost is deterministic: base overhead of 195 characters when at least one skill exists, plus 97 characters per skill plus the length of the XML-escaped name, description, and location values.

One thing to monitor: if you're running multiple agents (bookkeeping, personal-projects, etc.) and each gets ALL your skills injected, that's token overhead per turn. With, say, 15 custom skills at ~150 chars each, you're looking at roughly 2,500 characters (~625 tokens) of skills XML in every system prompt. Not catastrophic, but worth being aware of for prompt cache efficiency from your previous session's analysis.

**Assumption 3: `clawhub` CLI installs into `./skills` relative to workdir by default, so it won't conflict with `~/.openclaw/skills/`.**

**CONFIRMED.**

The default workdir is the current working directory (falling back to the OpenClaw workspace), and the install directory is `./skills`. The ClawHub docs confirm this: by default, the CLI installs skills into `./skills` under your current working directory, and if an OpenClaw workspace is configured, it falls back to that workspace unless you override with `--workdir` or `CLAWHUB_WORKDIR`.

So `clawhub install` drops into `<workspace>/skills/` (Tier 3 in your model), not `~/.openclaw/skills/` (Tier 2). No conflict. The namespaces are cleanly separated.

**Assumption 4: Hot-reload via the skills watcher works from `workspace/skills/` during development.**

**CONFIRMED — with a configuration requirement.**

Skills can refresh mid-session when the skills watcher is enabled or when a new eligible remote node appears — think of this as a hot reload where the refreshed list is picked up on the next agent turn. You need to enable it in config:

```json
{ "skills": { "load": { "watch": true, "watchDebounceMs": 250 } } }
```

OpenClaw snapshots the eligible skills when a session starts and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session. So without the watcher enabled, you'd need to start a new session to pick up skill changes. With the watcher, changes are picked up on the next turn within the same session.

One known bug to watch: there's a reported issue where workspace and `extraDirs` skills aren't discovered in certain versions, with only the 50 bundled skills appearing despite custom skills being physically present. If you hit this, verify your OpenClaw version and check `openclaw skills list` output.

**Assumption 5: No native private registry option in ClawHub — public only.**

**CONFIRMED.**

ClawHub is the public skill registry for OpenClaw — a free service where all skills are public, open, and visible to everyone for sharing and reuse. There is no private tier, no access controls, no scoped visibility. The ClawHub source confirms this is by design — it's built on Convex with public browsing and vector search as core features.

Private team skills often live in a private repo, and people clone into `~/.openclaw/skills` or into a workspace skills directory — this is simple and auditable. Your private GitHub repo approach is the standard community pattern for this.

There is one alternative worth knowing about: teams can build a private registry with signature verification, where the OpenClaw config contains just the registry URL and the registry's public key, and the question of whether a skill is safe is fully delegated to the registry and its CI/CD pipeline. This is overkill for a single-person setup but exists if you ever need to share skills across a team with audit controls.

---

### Community Prior Art: `skillshare`

The most directly relevant community solution is **skillshare** by runkids. It keeps all skills in one directory and creates symlinks to each AI CLI — when you install a skill, every target gets it, and when you edit a skill in one tool, the others see it immediately.

The architecture is remarkably close to your proposal:

Your Tier 1 (`~/markbot-skills/`) maps to skillshare's source directory (`~/.config/skillshare/skills/`). Your Tier 2 symlinks into `~/.openclaw/skills/` maps to skillshare's sync targets. Your `reinstall.sh` maps to `skillshare sync`.

Key capabilities: one git push/pull syncs skills across all your machines, works with any Git host, and scans skills for prompt injection, data exfiltration, and destructive commands with critical threats blocked automatically. It also has a `--track` flag that preserves `.git` so you can update later with a pull and sync.

The copy-vs-symlink choice is per-target: you can switch to copy mode per target if symlinks don't work.

**Assessment:** skillshare solves the mechanical problem (sync, symlink, git-backed source of truth) but doesn't solve the *workflow* problem (development → promotion → cleanup lifecycle). Your three-tier model adds the development staging layer that skillshare doesn't address. The two are complementary: you could use skillshare as the sync engine while keeping your three-tier lifecycle on top.

---

### Gaps and Upgrades

**Gap 1: Sandbox mode breaks skill access via `~/.openclaw/skills/`**

If you ever enable sandbox mode for any agent (e.g., for running untrusted code from a Discord channel), agents in sandbox mode with `workspaceAccess: "rw"` have no access to skills outside their own workspace, including those in `~/.openclaw/skills/`. The workaround is to disable sandbox for agents that need managed skills, but this is worth documenting in your architecture so you don't hit it by surprise when hardening security later.

**Gap 2: No automated promotion workflow**

Your five-step dev workflow (build → move → symlink → commit → delete) is manual. Each step is a shell command, but it's easy to forget one (especially the "delete from workspace" step, which leaves a Tier 3 copy that silently overrides Tier 2 due to precedence). Consider a `promote.sh` script:

```bash
#!/bin/bash
SKILL=$1
mv workspace/skills/$SKILL ~/markbot-skills/$SKILL
ln -s ~/markbot-skills/$SKILL ~/.openclaw/skills/$SKILL
cd ~/markbot-skills && git add $SKILL && git commit -m "Promote $SKILL"
# Workspace copy is already gone (mv, not cp)
```

The `mv` instead of `cp` eliminates the precedence shadowing risk entirely.

**Gap 3: Multi-machine sync (Big Daddy + BabyMac)**

Your architecture covers one machine. With both Big Daddy and BabyMac running OpenClaw instances, you need the private repo to serve as the sync mechanism. `reinstall.sh` handles cold-start, but ongoing sync needs either: a cron `git pull` on each machine, a webhook-triggered pull, or `skillshare` with `--track` mode pointing at your private repo.

**Gap 4: Skill token cost awareness**

Each skill costs 97 characters plus name/description/location lengths in the system prompt. With your multi-agent setup from the previous architecture discussion, every channel's agent gets the full skills list. If you have 20 skills at ~200 chars each, that's ~4,000 characters (~1,000 tokens) of skills XML per turn, per agent. Not budget-breaking, but it compounds with the prompt cache invalidation concerns from the shared state analysis. Consider using `skills.entries` to selectively disable irrelevant skills per agent (e.g., the bookkeeping agent doesn't need the shopping skill).

---

### Security Context

Your private-repo-only approach is well-timed. The first comprehensive security audit of the Agent Skills ecosystem revealed that roughly 13% of scanned skills contained critical security flaws, with a non-zero chance of active credential exfiltration. The ClawHavoc campaign in January 2026 targeted OpenClaw's memory files, SOUL.md and MEMORY.md, enabling memory poisoning attacks that could permanently alter the AI's behavior.

The skill loading mechanism introduces additional risk through a three-tier precedence system where workspace skills override managed skills, which override bundled skills — an attacker who can place a malicious skill in a workspace folder can shadow legitimate functionality. Your architecture actually mitigates this: by keeping `workspace/skills/` empty except during active development, you reduce the attack surface for workspace-level shadowing.

---

### Final Assessment

The three-tier architecture is **correct and well-aligned with OpenClaw's native primitives**. It's not novel — the community has converged on essentially this pattern — but that's a feature, not a bug. It means the approach is battle-tested.

**What's best-in-class about it:** The use of `~/.openclaw/skills/` as the active layer (survives workspace wipes, visible to all agents) and a git-backed source of truth is exactly what the docs recommend and what tools like skillshare implement.

**What would make it fully best-in-class:**

1. **Automated promotion script** — eliminates the precedence-shadowing footgun where a forgotten workspace copy overrides the managed version
2. **Copy-mode fallback** — one flag in `reinstall.sh` to switch from symlinks to copies if a future OpenClaw update tightens symlink handling
3. **Per-agent skill filtering** — use `skills.entries` with `enabled: false` to keep irrelevant skills out of specific agents' system prompts, reducing token overhead
4. **Multi-machine sync mechanism** — cron-based `git pull` or skillshare's `--track` mode for Big Daddy ↔ BabyMac parity
5. **Consider `skillshare`** as the sync engine rather than hand-rolling `reinstall.sh` — it handles symlink creation, copy-mode fallback, security scanning, and git integration out of the box