- New: registry_source_dir_migration_runbook.md (6 steps, all pass) - New: init_skip_skill_prompt_runbook.md (4 steps, all pass) - Updated: registry paths in existing runbooks to use skills/ dir
13 KiB
CLI E2E Runbook: Symlinked Source/Target Directories
Validates that all commands (sync, status, diff, list, collect, update, uninstall, reconcile) work correctly when source and/or target directories are symlinks — the "dotfiles manager" scenario.
Scope
- Source directory is a symlink (dotfiles manager pointing
~/.config/skillshare/skills/elsewhere) - Target directory is a symlink (dotfiles manager pointing
~/.claude/skills/elsewhere) - Both source and target are symlinks simultaneously
- Chained symlinks (link → link → real dir)
- Merge mode sync through symlinks
- Copy mode sync through symlinks
ss status,ss diff,ss listthrough symlinksss collect(pull local skills) through symlinked targetss update --alldiscovers skills through symlinked sourcess uninstallresolves skills through symlinked sourcess uninstall --groupwalks group dirs through symlinked source- Reconcile (global) detects installed skills through symlinked source
- Idempotency: re-sync doesn't break existing symlinks
Environment
Run inside devcontainer with ssenv isolation.
Step 0: Setup — Create symlinked source directory
# Create the REAL skills directory in a "dotfiles" location
REAL_SOURCE="$HOME/dotfiles/skillshare-skills"
mkdir -p "$REAL_SOURCE"
# Create test skills in the REAL location
mkdir -p "$REAL_SOURCE/alpha"
cat > "$REAL_SOURCE/alpha/SKILL.md" << 'SKILLEOF'
---
name: alpha
description: Test skill alpha
---
# Alpha Skill
SKILLEOF
mkdir -p "$REAL_SOURCE/beta"
cat > "$REAL_SOURCE/beta/SKILL.md" << 'SKILLEOF'
---
name: beta
description: Test skill beta
---
# Beta Skill
SKILLEOF
mkdir -p "$REAL_SOURCE/group/nested"
cat > "$REAL_SOURCE/group/nested/SKILL.md" << 'SKILLEOF'
---
name: nested
description: Nested skill for flat-name test
---
# Nested Skill
SKILLEOF
# Symlink the config source dir to the real location
SYMLINK_SOURCE="$HOME/.config/skillshare/skills"
rm -rf "$SYMLINK_SOURCE"
ln -s "$REAL_SOURCE" "$SYMLINK_SOURCE"
# Verify symlink
ls -la "$SYMLINK_SOURCE"
readlink "$SYMLINK_SOURCE"
Expected:
- exit_code: 0
- dotfiles/skillshare-skills
Step 1: Merge mode sync with symlinked source
ss sync --dry-run
Expected:
- exit_code: 0
- regex: 3 skills
- Not failed to walk source directory
ss sync
Expected:
- exit_code: 0
- merged
Step 2: Verify symlinks resolve correctly through symlinked source
# Check that skill symlinks in the target resolve to real files
TARGET_DIR="$HOME/.claude/skills"
# The symlink inside target should resolve to a real directory
ls -la "$TARGET_DIR/alpha" 2>/dev/null || echo "alpha not found in $TARGET_DIR"
stat "$TARGET_DIR/alpha/SKILL.md" 2>/dev/null && echo "RESOLVES OK" || echo "BROKEN SYMLINK"
Expected:
- exit_code: 0
- RESOLVES OK
Step 3: Status reports correctly with symlinked source
ss status
Expected:
- exit_code: 0
- skills
- Not unresolvable
Step 4: Diff detects no changes after sync
ss diff --no-tui
Expected:
- exit_code: 0
Step 5: List shows skills through symlinked source
ss list --no-tui
Expected:
- exit_code: 0
- alpha
- beta
- Not failed to walk
Step 6: Symlinked target directory — merge mode
# Create a REAL target directory and symlink it
REAL_TARGET="$HOME/dotfiles/claude-skills"
mkdir -p "$REAL_TARGET"
# Remove existing claude target and replace with symlink
CLAUDE_TARGET="$HOME/.claude/skills"
rm -rf "$CLAUDE_TARGET"
ln -s "$REAL_TARGET" "$CLAUDE_TARGET"
# Verify
ls -la "$CLAUDE_TARGET"
# Re-sync — should create skill symlinks INSIDE the symlinked target
ss sync
Expected:
- exit_code: 0
- merged
REAL_TARGET="$HOME/dotfiles/claude-skills"
CLAUDE_TARGET="$HOME/.claude/skills"
# Verify symlinks were created inside the symlinked target
ls -la "$CLAUDE_TARGET/"
ls -la "$REAL_TARGET/"
Expected:
- exit_code: 0
- alpha
- beta
- group__nested
Step 7: Symlinks resolve from both paths
REAL_TARGET="$HOME/dotfiles/claude-skills"
CLAUDE_TARGET="$HOME/.claude/skills"
# Access through symlink path
stat "$CLAUDE_TARGET/alpha/SKILL.md" && echo "VIA SYMLINK: OK" || echo "VIA SYMLINK: BROKEN"
# Access through real path
stat "$REAL_TARGET/alpha/SKILL.md" && echo "VIA REAL: OK" || echo "VIA REAL: BROKEN"
Expected:
- exit_code: 0
- VIA SYMLINK: OK
- VIA REAL: OK
Step 8: Copy mode with symlinked target
# Set up a copy-mode target
COPY_TARGET="$HOME/dotfiles/agents-skills"
COPY_SYMLINK="$HOME/.agents/skills"
mkdir -p "$COPY_TARGET"
mkdir -p "$(dirname "$COPY_SYMLINK")"
rm -rf "$COPY_SYMLINK"
ln -s "$COPY_TARGET" "$COPY_SYMLINK"
# Add to config as copy mode
ss target add agents-copy "$COPY_SYMLINK" --mode copy
# Sync
ss sync
Expected:
- exit_code: 0
- merged
COPY_TARGET="$HOME/dotfiles/agents-skills"
# Verify files exist at real location
ls "$COPY_TARGET/" | head -5
test -f "$COPY_TARGET/alpha/SKILL.md" && echo "COPY OK" || echo "COPY MISSING"
Expected:
- exit_code: 0
- COPY OK
Step 9: Both source AND target are symlinks (double symlink)
CLAUDE_TARGET="$HOME/.claude/skills"
# Both are already symlinks from previous steps
readlink "$HOME/.config/skillshare/skills"
readlink "$CLAUDE_TARGET"
# Sync should still work
ss sync --dry-run
Expected:
- exit_code: 0
- regex: \d+ skills
Step 10: Chained symlinks (link → link → real dir)
REAL_SOURCE="$HOME/dotfiles/skillshare-skills"
SYMLINK_SOURCE="$HOME/.config/skillshare/skills"
# Create a chain: link2 → link1 → real_source
CHAIN_DIR="$HOME/chain-test"
mkdir -p "$CHAIN_DIR"
ln -s "$REAL_SOURCE" "$CHAIN_DIR/link1"
ln -s "$CHAIN_DIR/link1" "$CHAIN_DIR/link2"
# Replace source with chained symlink
rm "$SYMLINK_SOURCE"
ln -s "$CHAIN_DIR/link2" "$SYMLINK_SOURCE"
# Verify chain
readlink "$SYMLINK_SOURCE"
readlink "$CHAIN_DIR/link2"
readlink "$CHAIN_DIR/link1"
# Sync should resolve the full chain
ss sync
Expected:
- exit_code: 0
- merged
- Not not a directory
- Not too many levels of symbolic links
Step 11: Collect (pull) through symlinked target
CLAUDE_TARGET="$HOME/.claude/skills"
# Create a local-only skill in the symlinked target
mkdir -p "$CLAUDE_TARGET/local-only"
cat > "$CLAUDE_TARGET/local-only/SKILL.md" << 'SKILLEOF'
---
name: local-only
description: A skill created directly in the target
---
# Local Only
SKILLEOF
# Collect should detect it (specify target name since multiple targets exist)
ss collect claude --dry-run
Expected:
- exit_code: 0
- local-only
Step 12: Update --all through symlinked source
This step validates that ss update --all can walk the symlinked source
directory to discover updatable skills. We simulate an installed skill with
metadata so update can discover it.
REAL_SOURCE="$HOME/dotfiles/skillshare-skills"
# Create a skill with install metadata (simulates remote install)
mkdir -p "$REAL_SOURCE/remote-skill"
cat > "$REAL_SOURCE/remote-skill/SKILL.md" << 'SKILLEOF'
---
name: remote-skill
description: Simulated remote skill
---
# Remote Skill
SKILLEOF
cat > "$REAL_SOURCE/remote-skill/.skillshare-meta.json" << 'METAEOF'
{
"source": "github.com/example/skills/remote-skill",
"repo_url": "https://github.com/example/skills",
"installed_at": "2025-01-01T00:00:00Z"
}
METAEOF
# Sync to pick up new skill
ss sync
# Update --all should discover remote-skill through the symlinked source
ss update --all --dry-run 2>&1
Expected:
- exit_code: 0
- remote-skill
- Not failed to walk
- Not failed to scan
Step 13: Update --group through symlinked source
REAL_SOURCE="$HOME/dotfiles/skillshare-skills"
# The "group" directory contains "nested" — update --group should find it
# Add metadata to nested skill so it's updatable
cat > "$REAL_SOURCE/group/nested/.skillshare-meta.json" << 'METAEOF'
{
"source": "github.com/example/group-skills/nested",
"repo_url": "https://github.com/example/group-skills",
"installed_at": "2025-01-01T00:00:00Z"
}
METAEOF
ss update --group group --dry-run 2>&1
Expected:
- exit_code: 0
- nested
- Not failed to walk group
Step 14: Uninstall single skill through symlinked source
# Uninstall beta skill — should resolve through symlinked source
ss uninstall beta --force --dry-run
Expected:
- exit_code: 0
- beta
# Actually uninstall
ss uninstall beta --force
Expected:
- exit_code: 0
REAL_SOURCE="$HOME/dotfiles/skillshare-skills"
# Verify beta is gone
test -d "$REAL_SOURCE/beta" && echo "STILL EXISTS" || echo "REMOVED OK"
ss list --no-tui
Expected:
- exit_code: 0
- REMOVED OK
- Not STILL EXISTS
Step 15: Uninstall --group through symlinked source
# Uninstall group — should walk the symlinked group dir
ss uninstall --group group --force --dry-run
Expected:
- exit_code: 0
- nested
- Not failed to walk group
# Actually uninstall the group
ss uninstall --group group --force
Expected:
- exit_code: 0
REAL_SOURCE="$HOME/dotfiles/skillshare-skills"
# Verify group is gone
test -d "$REAL_SOURCE/group/nested" && echo "STILL EXISTS" || echo "REMOVED OK"
Expected:
- exit_code: 0
- REMOVED OK
Step 16: Uninstall by nested name resolution through symlinked source
REAL_SOURCE="$HOME/dotfiles/skillshare-skills"
# Re-create a nested skill for this test
mkdir -p "$REAL_SOURCE/mygroup/deepskill"
cat > "$REAL_SOURCE/mygroup/deepskill/SKILL.md" << 'SKILLEOF'
---
name: deepskill
description: Deep nested skill
---
# Deep Skill
SKILLEOF
ss sync
# Uninstall by short name — resolveNestedSkillDir must walk symlinked source
ss uninstall deepskill --force
Expected:
- exit_code: 0
- deepskill
REAL_SOURCE="$HOME/dotfiles/skillshare-skills"
test -d "$REAL_SOURCE/mygroup/deepskill" && echo "STILL EXISTS" || echo "REMOVED OK"
Expected:
- exit_code: 0
- REMOVED OK
Step 17: Reconcile discovers skills through symlinked source
Reconcile is triggered by ss install. We install from a local file:// bare
repo so the install writes metadata into the symlinked source, then reconcile
walks it to populate registry.yaml.
# Set up git identity for bare-repo operations
git config --global user.email "test@test.com"
git config --global user.name "Test"
# Create a bare git repo as install source
BARE_REPO="$HOME/test-repos/recon-repo.git"
rm -rf "$HOME/test-repos"
mkdir -p "$BARE_REPO"
git init --bare "$BARE_REPO"
WORK_DIR="$HOME/test-repos/work"
git clone "$BARE_REPO" "$WORK_DIR"
mkdir -p "$WORK_DIR/reconcile-skill"
cat > "$WORK_DIR/reconcile-skill/SKILL.md" << 'SKILLEOF'
---
name: reconcile-skill
description: Test reconcile through symlink
---
# Reconcile Skill
SKILLEOF
cd "$WORK_DIR"
git add -A && git commit -m "add skill"
git push origin HEAD:master
# Install from file:// URL — installs into the symlinked source dir
cd "$HOME"
ss install "file://$BARE_REPO" --skip-audit --yes
# Check registry.yaml — reconcile should have walked the symlinked source
cat "$HOME/.config/skillshare/skills/registry.yaml"
Expected:
- exit_code: 0
- reconcile-skill
Step 18: Containment guard — group symlink outside source is rejected
If a group directory is a symlink pointing outside the source tree,
uninstall --group and update --group must refuse to operate (to prevent
accidental deletion/modification of external directories).
REAL_SOURCE="$HOME/dotfiles/skillshare-skills"
# Create a directory OUTSIDE the source tree
EXTERNAL="$HOME/external-danger"
mkdir -p "$EXTERNAL/victim-skill"
cat > "$EXTERNAL/victim-skill/SKILL.md" << 'SKILLEOF'
---
name: victim
description: Should NOT be uninstallable
---
# Victim
SKILLEOF
# Symlink a group inside source → external location
ln -s "$EXTERNAL" "$REAL_SOURCE/evil-group"
# Attempt group uninstall — should fail with containment error
ss uninstall --group evil-group --force 2>&1 || true
# Attempt group update — should also fail
ss update --group evil-group --dry-run 2>&1 || true
# Verify external directory was NOT touched
test -f "$EXTERNAL/victim-skill/SKILL.md" && echo "EXTERNAL SAFE" || echo "EXTERNAL DAMAGED"
# Cleanup
rm -f "$REAL_SOURCE/evil-group"
rm -rf "$EXTERNAL"
Expected:
- resolves outside source directory
- EXTERNAL SAFE
Step 19: Idempotency — re-sync preserves everything
# Sync twice more
ss sync
ss sync
Expected:
- exit_code: 0
- merged
REAL_TARGET="$HOME/dotfiles/claude-skills"
CLAUDE_TARGET="$HOME/.claude/skills"
# Final verification
readlink "$CLAUDE_TARGET"
ls "$REAL_TARGET/alpha/SKILL.md" && echo "STILL WORKS" || echo "BROKEN"
Expected:
- exit_code: 0
- STILL WORKS
Pass Criteria
- All 20 steps (0-19) pass
- No symlinks are incorrectly deleted during sync
- Skills discovered through symlinked source directories in all commands
update --allandupdate --groupwalk symlinked source correctlyuninstall(single, group, nested-name) resolves through symlinked source- Group operations reject symlinks pointing outside source tree (containment guard)
- Reconcile discovers installed skills through symlinked source
- Symlinks inside symlinked targets resolve from both logical and physical paths
- Chained symlinks (2+ levels) work correctly
- Copy mode preserves target symlinks (doesn't unconditionally delete)
- Collect detects local skills through symlinked target directories
- Re-sync is idempotent — doesn't break existing links