fix: Global skill installs work without manual folder moves

[hatayama]

Summary

• Globally installed uloop skills now land directly where AI tools can discover them.
• Older grouped skill folders are cleaned up by the default uninstall path.

User Impact

• Before this change, global installs could place skills under an extra unity-cli-loop/ folder, so tools that only scan top-level skill folders did not show the bundled uloop-* skills.
• After this change, running uloop skills install --claude --global makes the skills available without moving folders by hand.

Changes

• Make the default skill install directory flat for CLI installs.
• Keep the existing --flat flag accepted and update help text to describe the default.
• Let default uninstall remove skills from both the current flat layout and the older grouped layout.
• Add focused tests for command defaults, install directory resolution, and cleanup behavior.

Verification

• npm run test:cli -- --runTestsByPath src/__tests__/skills-command.test.ts src/__tests__/skills-manager.test.ts
• npm run lint (passes with existing security warnings)
• npm run build
• Built CLI flat-install check against a temporary Unity project
• codex-review-loop against origin/main: 0 valid findings

Closes #1103

Overview

This PR fixes global skill installation discovery by changing the default installation layout from grouped (with a unity-cli-loop/ wrapper directory) to flat. This allows Claude Code to discover globally installed uloop skills without requiring manual folder reorganization.

Problem

When users ran uloop skills install --claude --global, skills were installed under ~/.claude/skills/unity-cli-loop/uloop-*/SKILL.md. However, Claude Code expects skills to be located directly at ~/.claude/skills/<name>/SKILL.md, causing bundled uloop-* skills to not be discovered.

Solution

The fix implements flat-layout installation as the new default by:

• Introducing a DEFAULT_GROUP_MANAGED_SKILLS constant (set to false) in skills-manager.ts
• Updating function signatures to use this new default instead of the previous true default for:
  • getAllSkillStatuses()
  • installAllSkills()
  • uninstallAllSkills()
  • getInstallDir()
• Updating --flat flag descriptions in the CLI to clarify that flat layout is now the default behavior
• Modifying uninstall logic to handle both legacy grouped and new flat layouts when groupManagedSkills is disabled

Changes

Core Changes

• skills-manager.ts: Exports DEFAULT_GROUP_MANAGED_SKILLS = false and updates four function signatures to default groupManagedSkills to this new value instead of true. The uninstall strategy now branches: when grouping is enabled, it uses the single-layout path; when disabled, it removes skills from all layouts.
• skills-command.ts: Updates CLI to reference DEFAULT_GROUP_MANAGED_SKILLS instead of deriving the grouping behavior from the --flat flag. Flag descriptions updated to state "Use skills/ directly" to reflect the new default.

Test Coverage

• skills-manager.test.ts: Added test for uninstallAllSkills() verifying removal from both legacy flat and grouped layouts. Updated test for getInstallDir() to verify flat layout is used by default.
• skills-command.test.ts: New test suite verifying that skills install --claude --global invokes installAllSkills with correct target and layout arguments.
• cli-e2e.test.ts: Updated to verify flat-layout skill discovery and clarified test descriptions.

Impact

Users running uloop skills install --claude --global will now have skills installed directly under ~/.claude/skills/ and immediately discoverable by Claude Code without manual folder moves. The --flat flag remains available and accepted for explicit user control.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 125a9233-a8e6-4f5d-86b1-9eca997ac3e6

📥 Commits

Reviewing files that changed from the base of the PR and between 09d29e3 and b6210a9.

📒 Files selected for processing (5)

• Packages/src/Cli~/src/__tests__/cli-e2e.test.ts
• Packages/src/Cli~/src/__tests__/skills-command.test.ts
• Packages/src/Cli~/src/__tests__/skills-manager.test.ts
• Packages/src/Cli~/src/skills/skills-command.ts
• Packages/src/Cli~/src/skills/skills-manager.ts

---

📝 Walkthrough

Walkthrough

This PR changes the default skills installation layout from grouped (with unity-cli-loop/ wrapper directory) to flat (directly under ~/.claude/skills/), making skills discoverable by Claude Code by default. The change introduces a DEFAULT_GROUP_MANAGED_SKILLS = false constant and propagates it through all related APIs and CLI integrations.

Changes

Skills Layout Default

Layer / File(s)	Summary
Default constant and API signature updates Packages/src/Cli~/src/skills/skills-manager.ts	Exports DEFAULT_GROUP_MANAGED_SKILLS = false and updates getAllSkillStatuses, installAllSkills, uninstallAllSkills, and getInstallDir function signatures to use this constant as default instead of true.
Uninstall behavior for flat and grouped layouts Packages/src/Cli~/src/skills/skills-manager.ts	uninstallAllSkills now branches: when groupManagedSkills is enabled it uses single-layout uninstall; when disabled (default), it removes skills from both legacy flat and grouped layouts to handle migration cases.
CLI command integration and help text Packages/src/Cli~/src/skills/skills-command.ts	Imports and uses DEFAULT_GROUP_MANAGED_SKILLS in list, install, and uninstall command handlers. Updates --flat option descriptions to clarify default behavior and adjusts help text guidance for target selection.
Unit tests for skills-manager flat layout behavior Packages/src/Cli~/src/__tests__/skills-manager.test.ts	Adds test verifying flat layout is the default install directory, updates getInstallDir call signature, and adds test confirming uninstallAllSkills with defaults removes skills from both legacy and grouped layouts.
CLI command test suite for skills install Packages/src/Cli~/src/__tests__/skills-command.test.ts	New Jest test suite that mocks skills-manager and verifies skills install --claude --global invokes installAllSkills with correct target and groupManagedSkills boolean arguments.
End-to-end installation tests Packages/src/Cli~/src/__tests__/cli-e2e.test.ts	Updates test comments clarifying that default installs should be discoverable by Claude Code, adjusts expected skill path to uloop-compile/SKILL.md, and updates test description to reference the --flat flag explicitly.

Sequence Diagram

sequenceDiagram
  participant User as CLI User
  participant ListCmd as skills list
  participant InstallCmd as skills install
  participant UninstallCmd as skills uninstall
  participant SkillsMgr as skills-manager
  User->>ListCmd: --claude flag
  ListCmd->>SkillsMgr: listSkills(..., DEFAULT_GROUP_MANAGED_SKILLS=false)
  User->>InstallCmd: --claude --global flag
  InstallCmd->>SkillsMgr: installAllSkills(..., DEFAULT_GROUP_MANAGED_SKILLS=false)
  User->>UninstallCmd: --claude flag
  UninstallCmd->>SkillsMgr: uninstallAllSkills(..., DEFAULT_GROUP_MANAGED_SKILLS=false)
  SkillsMgr->>SkillsMgr: Uses flat layout when groupManagedSkills=false

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• hatayama/unity-cli-loop#951: Both PRs modify the CLI skills layout behavior around the same groupManagedSkills/--flat wiring in skills-command.ts and the related defaults/path logic in skills-manager.ts, so the changes are directly code-level related.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main fix: global skill installs now work without requiring manual folder moves, which directly addresses the core problem in the PR.
Linked Issues check	✅ Passed	The PR fully implements the solution for #1103: it makes flat layout the default for skill installs, ensures skills are discoverable by Claude Code without manual moves, and updates uninstall cleanup for both layouts.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the global skill discovery issue: default layout changes, test coverage updates, and command documentation reflect only the intended flat-layout-by-default solution.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/hatayama/fix-global-skill-discovery

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 5 files