Add --global flag for system-wide skill installation

[julioyg]

Summary

Some skills are useful across all projects and shouldn't need a per-project Lucafile to install. This PR adds a --global flag to install, uninstall, and installed so users can manage skills at the system level.

New commands

# Install all skills from your global Lucafile
luca install --global

# Install a specific skill globally
luca install org/repo --skill my-skill --global

# Use a custom global Lucafile
luca install --global --spec ~/my-global-skills.yaml

# Uninstall a globally-installed skill
luca uninstall my-skill --global

# List globally-installed skills
luca installed --skills --global

Path conventions

Resource	Path
Global Lucafile	~/.config/luca/Lucafile (XDG-style)
Global skill cache	~/.luca/skills/ (consistent with existing ~/.luca/tools/)
Global agent dirs	Per agent — e.g. ~/.claude/skills/, ~/.config/opencode/skills/

Behaviour notes

• Re-running luca install --global fetches the latest version of all skills — no separate update command needed
• Project-local skills take precedence over global skills when agent tools resolve paths
• repos: aliases in the global Lucafile work — the same spec parser is used
• --global is skills-only; tools already install globally to ~/.luca/tools/
• --global --only-tools is rejected with a clear validation error
• .gitignore management and post-checkout hook installation are skipped in global mode (no project repo involved)

[albertodebortoli]

I have no problem with this but it is necessary for these changes?

[julioyg]

you're right

[albertodebortoli]

👀

[julioyg]

changed

[albertodebortoli]

Unclear why this changed since nothing else changed in the file.

[julioyg]

think it changed because of the update on package.swift file, (both reverted)

[albertodebortoli]

From Claude Code:

---
Code Review Summary

Scope: branch feature/global-skill-installation vs main (2 commits)
Files Changed: 23
Lines Added/Removed: +451 / -47
Verdict: Needs fixes (3 issues before merging, 1 optional)

---
Positive Notes

- The uninstall ordering fix (b9f47a9) is correct and well-commented — symlinks are now cleaned up before the cache folder is deleted, resolving the
dangling-symlink bug.
- resolvedGlobalSkillsPath handles ~/…, bare ~, and absolute paths cleanly.
- .gitignore and git-hook logic is correctly skipped for the global path.
- InstalledSkillsLister, SkillSymLinker, and SkillUninstaller all have solid unit tests for the new global paths.
- Protocol additions (globalSkillsCacheFolder, homeDirectoryForCurrentUser) are minimal and targeted.

---
Issue Rating Table

┌─────┬─────────────────────────────────────────────────────────────┬─────────┬────────┬──────────────┬───────────┬─────────┬─────────────────────┐
│  #  │                           Finding                           │ Urgency │ Risk:  │ Risk: No Fix │    ROI    │ Blast   │     Fix Effort      │
│     │                                                             │         │  Fix   │              │           │ Radius  │                     │
├─────┼─────────────────────────────────────────────────────────────┼─────────┼────────┼──────────────┼───────────┼─────────┼─────────────────────┤
│     │ Installer.swift:244,261,263,287 — Four user-facing messages │         │        │ 🟡 High      │ 🟠        │ ⚪ 1    │                     │
│ 1   │  say "for the current project" even when isGlobal: true     │ 🟡 High │ ⚪ Low │ (confusing   │ Excellent │ file    │ Trivial             │
│     │                                                             │         │        │ UX)          │           │         │                     │
├─────┼─────────────────────────────────────────────────────────────┼─────────┼────────┼──────────────┼───────────┼─────────┼─────────────────────┤
│     │ InstallCommand.swift:98 — Help text reads "Install skills   │         │        │              │ 🟠        │ ⚪ 1    │                     │
│ 2   │ globally to ~/.config/luca/Lucafile" — that's the source    │ 🟡 High │ ⚪ Low │ 🟢 Medium    │ Excellent │ file    │ Trivial             │
│     │ spec file, not a destination                                │         │        │              │           │         │                     │
├─────┼─────────────────────────────────────────────────────────────┼─────────┼────────┼──────────────┼───────────┼─────────┼─────────────────────┤
│     │ InstallCommandTests.swift — Entire file is stub TODOs;      │ 🟢      │        │              │           │ ⚪ 1    │ Trivial (delete     │
│ 3   │ ships with zero active tests                                │ Medium  │ ⚪ Low │ 🟢 Medium    │ 🟢 Good   │ file    │ file or move TODO   │
│     │                                                             │         │        │              │           │         │ to PR description)  │
├─────┼─────────────────────────────────────────────────────────────┼─────────┼────────┼──────────────┼───────────┼─────────┼─────────────────────┤
│     │ Installer.swift — No tests for the isGlobal: true install   │ 🟢      │ 🟢     │              │           │ ⚪ 1    │                     │
│ 4   │ path (SkillSet routing, cache folder selection). Individual │ Medium  │ Medium │ 🟢 Medium    │ 🟢 Good   │ file    │ Medium              │
│     │  components are tested, but the orchestration layer is not. │         │        │              │           │         │                     │
└─────┴─────────────────────────────────────────────────────────────┴─────────┴────────┴──────────────┴───────────┴─────────┴─────────────────────┘

---
Detail on Each Issue

Issue #1 — Wrong success messages when global (Installer.swift)

Four strings need an isGlobal branch:

// line 244
"\(.info("🧠 Installing skills for the current project."))"
// → when isGlobal: "🧠 Installing skills globally."

// line 261
"\(.success("🚀 Skills have been installed for the current project."))"
// → when isGlobal: "🚀 Skills have been installed globally."

// line 263
"\(.muted("🫥 No skills have been installed for the current project."))"
// → when isGlobal: "🫥 No skills found to install globally."

// line 287 (in install(_:agents:useNpx:isGlobal:resolvedAgents:))
"\(.primary("🙌 Skills from \(skillSet.repository) installed for the current project."))"
// → when isGlobal: "globally." instead of "for the current project."

Issue #2 — Misleading --global help text (InstallCommand.swift:98–107)

Current: "Install skills globally to ~/.config/luca/Lucafile and ~/.luca/skills/."

~/.config/luca/Lucafile is read as the source spec, not written to. Suggested:

"Install skills globally. Uses ~/.config/luca/Lucafile as the spec (unless --spec is provided) and caches skills in ~/.luca/skills/."

Issue #3 — Empty test file

Tests/Core/InstallCommandTests.swift has no @Test functions — only TODO comment blocks. The architectural constraint is real and well-explained, but a
file with only comments adds noise and zero coverage. The TODO context is better placed in the PR description. Recommend deleting the file unless you
want to leave it as a future reminder.

Issue #4 — Missing Installer global path tests

InstallerTests.swift has no test asserting that when isGlobal: true the skill folder is globalSkillsCacheFolder rather than skillsCacheFolder, or that
setSymLink is called with isGlobal: true. The SkillSymLinkerMock already records isGlobal implicitly (via the protocol signature), so a test could
assert skillSymLinkerMock.lastIsGlobal == true. Worth adding before merging.

---
Verdict: Address issues #1 and #2 before merging (wrong messages and misleading help text). Issue #3 is a clean-up call (recommend deleting the stub
file). Issue #4 is a coverage gap worth closing but not blocking.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!