mosaicstack/stack
6
0
Fork 1
Code Issues 298 Pull Requests 18 Actions Packages Projects Releases 15 Wiki Activity

skills: single install path — canonical skills ship with the framework

Browse Source 
Phase D2 of plan 2026-08-19: single package, single install, single command.

The framework installer already treats skills/** as a shipped, manifest-owned
framework subtree, so the folded skills now install into
$MOSAIC_HOME/skills with the rest of the framework — no second repository,
no separate sync step:

- mosaic-sync-skills (bash + powershell): the fetch machinery is gone (clone,
  pull, dirty-state migration, rsync from sources/agent-skills). The script
  now only links installed skills into runtime homes. --link-only is a compat
  no-op; --no-link exits having nothing to do.
- catalog.ts: the sources/agent-skills fallback is dead and removed.
- install.sh, launch.ts, defaults/README.md, README.md, skills/README.md:
  references to the second repo rewritten to describe the shipped path.

Verified: clean install into a fresh MOSAIC_HOME produces 102 skills with no
sources/ directory; the linker then links the selected skills into the four
runtime homes with no git involvement.
This commit is contained in:
fargo
2026-08-19 14:39:28 -05:00
parent 1a822493ba
commit 1556982dbc
9 changed files with 55 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/mosaic/framework/defaults/README.md
+4 -4
View File
@@ -126,7 +126,7 @@ You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtim
│ ├── opencode/ ← AGENTS.md, RUNTIME.md
│ ├── pi/ ← RUNTIME.md, mosaic-extension.ts
│ └── mcp/ ← MCP server configs
├── skills/ ← Universal skills (synced from mosaic/agent-skills)
├── skills/ ← Universal skills (shipped with the framework package)
├── skills-local/ ← Local cross-runtime skills
├── memory/ ← Persistent agent memory (preserved across upgrades)
└── templates/ ← SOUL.md template, project templates
@@ -193,11 +193,11 @@ The installer rejects unrecognized flags or positional arguments before making c
## Universal Skills
The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`. Install, wizard finalization, and `mosaic update` automatically reconcile every canonical skill into Claude Code's `~/.claude/skills/` directory.
Canonical skills ship inside the framework package itself; the installer installs them into `~/.config/mosaic/skills/` together with the rest of the framework (there is no separate skills repository). Install, wizard finalization, and `mosaic update` automatically link every canonical skill into Claude Code's `~/.claude/skills/` directory.
```bash
mosaic sync # Full canonical catalog sync
~/.config/mosaic/tools/_scripts/mosaic-sync-skills --link-only # Re-link only
mosaic sync # Relink the full canonical catalog
~/.config/mosaic/tools/_scripts/mosaic-sync-skills --link-only # Re-link only (same as default)
mosaic skill list # Show registered, missing, dangling, and foreign entries
mosaic skill register <name> # Register or repair one canonical Claude link
mosaic skill unregister <name> # Remove one Mosaic-owned Claude link
packages/mosaic/framework/install.sh
+2 -2
View File
@@ -17,7 +17,7 @@ set -Eeuo pipefail
# MOSAIC_HOME — target directory (default: ~/.config/mosaic)
# MOSAIC_INSTALL_MODE — prompt|keep|overwrite (default: prompt)
# MOSAIC_ALLOW_MISSING_SEQUENTIAL_THINKING — 1 to bypass MCP check
# MOSAIC_SKIP_SKILLS_SYNC — 1 to skip skill sync
# MOSAIC_SKIP_SKILLS_SYNC — 1 to skip linking skills into runtime homes
#
# Flags (CLI args, NOT environment variables — see #869 Point-1 C2):
# --allow-inactive-enforcement Explicit, per-invocation opt-out that lets the
@@ -828,7 +828,7 @@ if [[ -x "$SCRIPTS/mosaic-ensure-excalidraw" ]]; then
fi
if [[ "${MOSAIC_SKIP_SKILLS_SYNC:-0}" != "1" ]] && [[ -x "$SCRIPTS/mosaic-sync-skills" ]]; then
"$SCRIPTS/mosaic-sync-skills" >/dev/null 2>&1 && ok "Skills synced" || warn "Skills sync failed (non-fatal)"
"$SCRIPTS/mosaic-sync-skills" >/dev/null 2>&1 && ok "Skills linked into runtime homes" || warn "Skills linking failed (non-fatal)"
fi
if [[ -x "$SCRIPTS/mosaic-migrate-local-skills" ]]; then
packages/mosaic/framework/skills/README.md
+13 -19
View File
@@ -1,6 +1,8 @@
# Agent Skills
Complete agent skill fleet for Mosaic Stack. 95 skills across 12 domains — coding, business development, design, marketing, writing, orchestration, document generation, Vue/Vite ecosystem, and more. Platform-aware — works with both GitHub (`gh`) and Gitea (`tea`) via our abstraction scripts.
Complete agent skill fleet for Mosaic Stack. 101 skills across 12 domains — coding, business development, design, marketing, writing, orchestration, document generation, Vue/Vite ecosystem, and more. Platform-aware — works with both GitHub (`gh`) and Gitea (`tea`) via our abstraction scripts.
This tree lives in the monorepo (`packages/mosaic/framework/skills/`) and ships inside the framework package; it is no longer a separate repository.
## Security Audit
@@ -196,29 +198,21 @@ All skills were reviewed on 2026-02-16. Findings:
## Installation
### Via npx (recommended)
The skills ship with the framework package. The framework installer installs them
into `~/.config/mosaic/skills/`, and the post-install step links them into each
runtime's skill directory:
```bash
# Install a single skill
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --skill nestjs-best-practices --agent claude-code
# Install or upgrade the framework (skills arrive with it — no second repo)
./packages/mosaic/framework/install.sh
# Install all skills
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --agent claude-code
# Non-interactive (CI/scripting)
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --yes --agent claude-code
# Re-link installed skills into runtime homes (claude, codex, opencode, pi)
mosaic sync
```
**Note:** The `.git` suffix on the URL is required for Gitea-hosted repos.
### Manual (symlink from local clone)
```bash
git clone https://git.mosaicstack.dev/mosaic/agent-skills.git ~/src/agent-skills
for skill in ~/src/agent-skills/skills/*/; do
ln -sf "$skill" ~/.config/mosaic/skills/$(basename "$skill")
done
```
Operators can override any canonical skill by copying it to
`~/.config/mosaic/skills-local/<name>/` — local skills take precedence during
linking.
## Adapting Skills
packages/mosaic/framework/tools/_scripts/mosaic-sync-skills
+18 -105
View File
@@ -1,9 +1,14 @@
#!/usr/bin/env bash
set -euo pipefail
# Link the INSTALLED canonical skills into runtime skill directories.
#
# The canonical skills ship inside the framework package itself
# (packages/mosaic/framework/skills in the monorepo) and are installed into
# $MOSAIC_HOME/skills by the framework installer — there is no second
# repository to clone. This script only maintains the runtime symlinks.
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
SKILLS_REPO_URL="${MOSAIC_SKILLS_REPO_URL:-https://git.mosaicstack.dev/mosaic/agent-skills.git}"
SKILLS_REPO_DIR="${MOSAIC_SKILLS_REPO_DIR:-$MOSAIC_HOME/sources/agent-skills}"
MOSAIC_SKILLS_DIR="$MOSAIC_HOME/skills"
MOSAIC_LOCAL_SKILLS_DIR="$MOSAIC_HOME/skills-local"
@@ -12,37 +17,34 @@ MOSAIC_LOCAL_SKILLS_DIR="$MOSAIC_HOME/skills-local"
# (the legacy "mosaic sync" full-catalog behavior).
MOSAIC_INSTALL_SKILLS="${MOSAIC_INSTALL_SKILLS:-}"
fetch=1
link_only=0
usage() {
cat <<USAGE
Usage: $(basename "$0") [options]
Sync canonical skills into ~/.config/mosaic/skills and link all Mosaic skills into runtime skill directories.
Link installed skills from ~/.config/mosaic/{skills,skills-local} into runtime
skill directories. Canonical skills arrive with the framework installer; this
script never clones or pulls a second repository.
Options:
--link-only Skip git clone/pull and only relink from ~/.config/mosaic/{skills,skills-local}
--no-link Sync canonical skills but do not update runtime links
--link-only Accepted for compatibility; linking is now the whole job
--no-link Do nothing (kept for compatibility)
-h, --help Show help
Env:
MOSAIC_HOME Default: ~/.config/mosaic
MOSAIC_SKILLS_REPO_URL Default: https://git.mosaicstack.dev/mosaic/agent-skills.git
MOSAIC_SKILLS_REPO_DIR Default: ~/.config/mosaic/sources/agent-skills
MOSAIC_INSTALL_SKILLS Colon-separated list of skills to link (default: all)
MOSAIC_HOME Default: ~/.config/mosaic
MOSAIC_INSTALL_SKILLS Colon-separated list of skills to link (default: all)
USAGE
}
while [[ $# -gt 0 ]]; do
case "$1" in
--link-only)
fetch=0
# Compat no-op: fetching a skills repo no longer exists.
shift
;;
--no-link)
link_only=1
shift
echo "[mosaic-skills] Nothing to do (--no-link; canonical skills ship with the installer)"
exit 0
;;
-h|--help)
usage
@@ -58,101 +60,12 @@ done
mkdir -p "$MOSAIC_HOME" "$MOSAIC_SKILLS_DIR" "$MOSAIC_LOCAL_SKILLS_DIR"
if [[ $fetch -eq 1 ]]; then
if [[ -d "$SKILLS_REPO_DIR/.git" ]]; then
echo "[mosaic-skills] Updating skills source: $SKILLS_REPO_DIR"
# ── Detect dirty state ──────────────────────────────────────────────
dirty=""
dirty="$(git -C "$SKILLS_REPO_DIR" status --porcelain 2>/dev/null || true)"
if [[ -n "$dirty" ]]; then
# ── Auto-migrate customized skills to skills-local/ ─────────────
# Instead of stash/pop (fragile, merge conflicts), we:
# 1. Identify which skill dirs contain user edits
# 2. Copy those full skill dirs into skills-local/ (preserving edits)
# 3. Reset the repo clean so pull always succeeds
# 4. skills-local/ takes precedence during linking, so edits win
SOURCE_SKILLS_SUBDIR="$SKILLS_REPO_DIR/skills"
migrated=()
while IFS= read -r line; do
# porcelain format: XY <path> — extract the file path
file="${line:3}"
# Only migrate files under skills/ subdir in the repo
if [[ "$file" == skills/* ]]; then
# Extract the skill directory name (first path component after skills/)
skill_name="${file#skills/}"
skill_name="${skill_name%%/*}"
# Skip if already migrated this skill in this run
local_skill_dir="$MOSAIC_LOCAL_SKILLS_DIR/$skill_name"
if [[ -d "$local_skill_dir" ]]; then
continue
fi
# Skip if skill_name is empty or hidden
if [[ -z "$skill_name" || "$skill_name" == .* ]]; then
continue
fi
# Copy the skill (with user's edits) from repo working tree to skills-local/
if [[ -d "$SOURCE_SKILLS_SUBDIR/$skill_name" ]]; then
cp -R "$SOURCE_SKILLS_SUBDIR/$skill_name" "$local_skill_dir"
migrated+=("$skill_name")
fi
fi
done <<< "$dirty"
if [[ ${#migrated[@]} -gt 0 ]]; then
echo "[mosaic-skills] Migrated ${#migrated[@]} customized skill(s) to skills-local/:"
for s in "${migrated[@]}"; do
echo " → $MOSAIC_LOCAL_SKILLS_DIR/$s"
done
echo "[mosaic-skills] Your edits are preserved there and take precedence over canonical."
fi
# Reset repo to clean state so pull always works
echo "[mosaic-skills] Resetting source repo to clean state..."
git -C "$SKILLS_REPO_DIR" checkout . 2>/dev/null || true
git -C "$SKILLS_REPO_DIR" clean -fd 2>/dev/null || true
fi
if ! git -C "$SKILLS_REPO_DIR" pull --rebase 2>/dev/null; then
echo "[mosaic-skills] WARN: pull failed — continuing with existing checkout" >&2
git -C "$SKILLS_REPO_DIR" rebase --abort 2>/dev/null || true
fi
else
echo "[mosaic-skills] Cloning skills source to: $SKILLS_REPO_DIR"
mkdir -p "$(dirname "$SKILLS_REPO_DIR")"
git clone "$SKILLS_REPO_URL" "$SKILLS_REPO_DIR"
fi
SOURCE_SKILLS_DIR="$SKILLS_REPO_DIR/skills"
if [[ ! -d "$SOURCE_SKILLS_DIR" ]]; then
echo "[mosaic-skills] Missing source skills dir: $SOURCE_SKILLS_DIR" >&2
exit 1
fi
if command -v rsync >/dev/null 2>&1; then
rsync -a --delete "$SOURCE_SKILLS_DIR/" "$MOSAIC_SKILLS_DIR/"
else
rm -rf "$MOSAIC_SKILLS_DIR"/*
cp -R "$SOURCE_SKILLS_DIR"/* "$MOSAIC_SKILLS_DIR"/
fi
fi
if [[ ! -d "$MOSAIC_SKILLS_DIR" ]]; then
echo "[mosaic-skills] Canonical skills dir missing: $MOSAIC_SKILLS_DIR" >&2
echo "[mosaic-skills] Canonical skills ship with the framework — reinstall or update the framework package" >&2
exit 1
fi
if [[ $link_only -eq 1 ]]; then
echo "[mosaic-skills] Canonical sync completed (link update skipped)"
exit 0
fi
# Skills are linked into the MOSAIC-OWNED harness homes, never a base install.
# Paths mirror the config-dir env vars the launcher injects (HARNESS_HOME_ENV in
# commands/launch.js):
packages/mosaic/framework/tools/_scripts/mosaic-sync-skills.ps1
+14 -33
View File
@@ -1,5 +1,8 @@
# mosaic-sync-skills.ps1
# Syncs canonical skills and links them into agent runtime skill directories.
# Links the INSTALLED canonical skills into agent runtime skill directories.
# Canonical skills ship inside the framework package and are installed into
# ~/.config/mosaic/skills by the framework installer — there is no second
# repository to clone. This script only maintains the runtime links.
# Uses directory junctions (no elevation required) with fallback to copies.
# PowerShell equivalent of mosaic-sync-skills (bash).
$ErrorActionPreference = "Stop"
@@ -11,8 +14,6 @@ param(
)
$MosaicHome = if ($env:MOSAIC_HOME) { $env:MOSAIC_HOME } else { Join-Path $env:USERPROFILE ".config\mosaic" }
$SkillsRepoUrl = if ($env:MOSAIC_SKILLS_REPO_URL) { $env:MOSAIC_SKILLS_REPO_URL } else { "https://git.mosaicstack.dev/mosaic/agent-skills.git" }
$SkillsRepoDir = if ($env:MOSAIC_SKILLS_REPO_DIR) { $env:MOSAIC_SKILLS_REPO_DIR } else { Join-Path $MosaicHome "sources\agent-skills" }
$MosaicSkillsDir = Join-Path $MosaicHome "skills"
$MosaicLocalSkillsDir = Join-Path $MosaicHome "skills-local"
@@ -20,45 +21,25 @@ if ($Help) {
Write-Host @"
Usage: mosaic-sync-skills.ps1 [-LinkOnly] [-NoLink] [-Help]
Sync canonical skills into ~/.config/mosaic/skills and link all Mosaic skills
into runtime skill directories using directory junctions.
Link installed skills from ~/.config/mosaic/{skills,skills-local} into runtime
skill directories using directory junctions. Canonical skills arrive with the
framework installer; this script never clones or pulls a second repository.
Options:
-LinkOnly Skip git clone/pull and only relink
-NoLink Sync canonical skills but do not update runtime links
-LinkOnly Accepted for compatibility; linking is now the whole job
-NoLink Do nothing (kept for compatibility)
-Help Show help
"@
exit 0
}
foreach ($d in @($MosaicHome, $MosaicSkillsDir, $MosaicLocalSkillsDir)) {
if (-not (Test-Path $d)) { New-Item -ItemType Directory -Path $d -Force | Out-Null }
if ($NoLink) {
Write-Host "[mosaic-skills] Nothing to do (-NoLink; canonical skills ship with the installer)"
exit 0
}
# Fetch skills from git
if (-not $LinkOnly) {
if (Test-Path (Join-Path $SkillsRepoDir ".git")) {
Write-Host "[mosaic-skills] Updating skills source: $SkillsRepoDir"
git -C $SkillsRepoDir pull --rebase
}
else {
Write-Host "[mosaic-skills] Cloning skills source to: $SkillsRepoDir"
$parentDir = Split-Path $SkillsRepoDir -Parent
if (-not (Test-Path $parentDir)) { New-Item -ItemType Directory -Path $parentDir -Force | Out-Null }
git clone $SkillsRepoUrl $SkillsRepoDir
}
$sourceSkillsDir = Join-Path $SkillsRepoDir "skills"
if (-not (Test-Path $sourceSkillsDir)) {
Write-Host "[mosaic-skills] Missing source skills dir: $sourceSkillsDir" -ForegroundColor Red
exit 1
}
# Sync: remove old, copy new
if (Test-Path $MosaicSkillsDir) {
Get-ChildItem $MosaicSkillsDir | Remove-Item -Recurse -Force
}
Copy-Item "$sourceSkillsDir\*" $MosaicSkillsDir -Recurse -Force
foreach ($d in @($MosaicHome, $MosaicSkillsDir, $MosaicLocalSkillsDir)) {
if (-not (Test-Path $d)) { New-Item -ItemType Directory -Path $d -Force | Out-Null }
}
if (-not (Test-Path $MosaicSkillsDir)) {
packages/mosaic/src/commands/launch.ts
+1 -1
View File
@@ -1450,7 +1450,7 @@ export function registerLaunchCommands(program: Command): void {
// Direct framework script delegates
const directCommands: Record<string, { desc: string; script: string }> = {
init: { desc: 'Generate SOUL.md (agent identity contract)', script: 'mosaic-init' },
sync: { desc: 'Sync skills from canonical source', script: 'mosaic-sync-skills' },
sync: { desc: 'Link installed skills into runtime homes', script: 'mosaic-sync-skills' },
bootstrap: {
desc: 'Bootstrap a repo with Mosaic standards',
script: 'mosaic-bootstrap-repo',
packages/mosaic/src/platform/file-ops.ts
+2 -1
View File
@@ -94,7 +94,8 @@ export function syncDirectory(
const relPath = relative(relBase, src);
const dirName = relPath.split('/').pop() ?? '';
// Skip any .git directory (top-level or nested, e.g. sources/agent-skills/.git)
// Skip any .git directory (top-level or nested; defensive — the
// framework tree itself is not a git checkout at install time)
if (options.excludeGit && (dirName === '.git' || relPath.includes('/.git'))) return;
// Skip preserved paths at top level
packages/mosaic/src/skills/catalog.ts
-6
View File
@@ -20,12 +20,6 @@ export function loadSkillsCatalog(mosaicHome: string): SkillEntry[] {
skills.push(...loadSkillsFromDir(canonicalDir, 'canonical'));
}
// Fallback to source repo
const sourceDir = join(mosaicHome, 'sources', 'agent-skills', 'skills');
if (skills.length === 0 && existsSync(sourceDir)) {
skills.push(...loadSkillsFromDir(sourceDir, 'canonical'));
}
// Load local skills
const localDir = join(mosaicHome, 'skills-local');
if (existsSync(localDir)) {