[PR #1352] [CLOSED] fix(setup): link managed skill into Claude Code skills directory #2819

New issue

Closed

opened 2026-10-17 21:10:38 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-17 21:10:38 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1352
Author: @akram1089
Created: 10/9/2026
Status: ❌ Closed

Base: main ← Head: fix/setup-claude-code-skill

📝 Commits (2)

6160270 fix(setup): link managed skill into Claude Code skills directory
ffebeda chore: merge origin/main into fix/setup-claude-code-skill resolving conflicts

📊 Changes

1 file changed (+9 additions, -0 deletions)

View changed files

📝 docs/installation.md (+9 -0)

📄 Description

Summary

Fixes #1337.

When Claude Code is configured or selected in setup, REA currently writes the managed reverse-engineering skill only to ~/.agents/skills/reverse-engineer-anything. Claude Code loads personal skills strictly from ~/.claude/skills/<name>/SKILL.md (or $CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md), meaning the REA MCP tools were registered but the skill was never discovered or loaded by Claude Code. This PR links (or installs) the managed skill into Claude Code's personal skills directory during setup, discloses the target in the setup plan, and uninstalls it cleanly during REA removal.

Problem and expected behavior

Prior behavior: setup --client claude_code writes the skill bundle only to ~/.agents/skills/reverse-engineer-anything. Claude Code's skill loader does not inspect ~/.agents/skills, so Claude Code sessions had MCP tool access without the bundled skill instructions and on-demand references.
Expected behavior: When claude_code is selected or configured, setup installs the canonical skill to ~/.agents/skills/reverse-engineer-anything and links it into Claude Code's personal skills directory (~/.claude/skills/reverse-engineer-anything or $CLAUDE_CONFIG_DIR/skills/reverse-engineer-anything). If directory symlinking is unavailable, setup falls back to copying the skill bundle directly with per-file .rea.backup preservation. uninstall removes both the canonical skill and Claude Code's skill location.

Change and scope

src/application/SupportedClients.ts: Added optional skillPath property to SetupClient and ClientDefinition. Configured claude_code to define its personal skill path at join(claudeCodeMarkerDirectory(context), "skills", PRODUCT_IDENTITY.skillName), honoring CLAUDE_CONFIG_DIR.
src/application/SetupSkill.ts:
- Exported canonicalSkillRoot.
- Added isClientSkillAligned to verify whether a client skill path is a valid symlink/junction pointing to canonical skill root or a directory whose contents match the canonical skill bundle.
- Added linkOrInstallClientSkill to link the canonical bundle to a client skill path (using NTFS junction on Windows without requiring elevation, and directory symlink on POSIX), falling back to atomic direct file copy with .rea.backup if symlinking fails.
- Added skillNeedsInstallForClients and installSkillForClients.
src/application/SetupHost.ts: Extended skillNeedsInstall and installSkill on systemSetupHost to accept selected clients and delegate to skillNeedsInstallForClients and installSkillForClients.
src/application/SetupTypes.ts: Updated SetupHost interface so skillNeedsInstall and installSkill optionally accept clients?: readonly SetupClient[].
src/application/SetupPlan.ts: Passed selectedClients to setupPlan and updated install_skill detail disclosure when Claude Code is among selected clients.
src/application/Setup.ts: Threaded selected client candidates into skillNeedsInstall detection and passed planSelection.selectedClients to installSkillAction.
src/application/Uninstall.ts: Updated removeManagedSkills to clean up client skill paths (e.g. claude_code) before removing the canonical skill.
docs/installation.md: Added documentation explaining Claude Code's personal skills directory linking and CLAUDE_CONFIG_DIR behavior.
tests/boundary/filesystem/setupSkill.test.ts: Added test coverage for client skill linking, repair of stale/broken links, directory copy fallback, setup dry-run disclosure and execution with uninstall cleanup, and CLAUDE_CONFIG_DIR override.

Contract and boundary impact

Semantic owner and earliest changed stage: src/application/SupportedClients.ts (client metadata boundary) and src/application/SetupSkill.ts (filesystem skill transaction).
CLI and MCP/tool-catalog contract: Unchanged. install_skill retains its canonical action ID.
Provider, bridge, target-format, or platform compatibility: Cross-platform. Uses directory junctions on Windows (win32) to avoid elevation requirements for non-admin users, and directory symlinks on POSIX. Respects CLAUDE_CONFIG_DIR.
Evidence, artifact, provenance, or reconstruction contract: None.
Process execution, authorization, cleanup, or containment impact: Unchanged. Idempotent setup and non-blocking plan disclosure. uninstall removes client-specific skill links and directories.
Generated metadata (docs/product-catalog.json), package, or installation impact: Documentation updated; verified with npm run docs:check.

Evidence and regression coverage

Tests added or updated: Added client skill linking and lifecycle test suite in tests/boundary/filesystem/setupSkill.test.ts:
- installs canonical skill and links into Claude Code personal skill location
- repairs a broken or pointing-elsewhere client skill link
- updates an existing directory with skill files when symlinking is not used
- discloses Claude Code skill linking in setup plan and uninstalls cleanly
- respects CLAUDE_CONFIG_DIR environment override
Base reproduction: rea setup --client claude_code --dry-run --json planned action now discloses:
"Install or update the bundled REA reverse-engineering skill and on-demand references, and link into Claude Code's skills directory."
User-visible CLI/MCP output:
- rea setup --client claude_code installs to ~/.agents/skills/reverse-engineer-anything and links to ~/.claude/skills/reverse-engineer-anything.
- Claude Code discovers and loads the skill from its personal skills directory.

Validation performed

npx vitest run tests/boundary/filesystem/setupSkill.test.ts: passed (8 passed)
npm run check:fast: passed (typecheck and lint clean)
npm run docs:check: passed (all 6 tasks successful, no doc drift)
npx oxfmt: passed (all modified files formatted)

Compatibility, safety, and release

Breaking changes or migration steps: None. Fully additive and idempotent.
Real Hopper/Ghidra, browser, or OS coverage: Verified on Windows with NTFS junction creation and POSIX path handling.
Package or release metadata impact: None.
Security, privacy, process, or containment review: Local-only, atomic writes with backups, no privilege escalation or external network calls required.

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/1352 **Author:** [@akram1089](https://github.com/akram1089) **Created:** 10/9/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/setup-claude-code-skill` --- ### 📝 Commits (2) - [`6160270`](https://github.com/morluto/rea/commit/6160270e22c779d47dc51faaba882824ebcaefb2) fix(setup): link managed skill into Claude Code skills directory - [`ffebeda`](https://github.com/morluto/rea/commit/ffebedabadab01be0fbb95a20392f3fd58aa1311) chore: merge origin/main into fix/setup-claude-code-skill resolving conflicts ### 📊 Changes **1 file changed** (+9 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/installation.md` (+9 -0) </details> ### 📄 Description ## Summary Fixes #1337. When Claude Code is configured or selected in setup, REA currently writes the managed reverse-engineering skill only to `~/.agents/skills/reverse-engineer-anything`. Claude Code loads personal skills strictly from `~/.claude/skills/<name>/SKILL.md` (or `$CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md`), meaning the REA MCP tools were registered but the skill was never discovered or loaded by Claude Code. This PR links (or installs) the managed skill into Claude Code's personal skills directory during setup, discloses the target in the setup plan, and uninstalls it cleanly during REA removal. ## Problem and expected behavior - Prior behavior: `setup --client claude_code` writes the skill bundle only to `~/.agents/skills/reverse-engineer-anything`. Claude Code's skill loader does not inspect `~/.agents/skills`, so Claude Code sessions had MCP tool access without the bundled skill instructions and on-demand references. - Expected behavior: When `claude_code` is selected or configured, setup installs the canonical skill to `~/.agents/skills/reverse-engineer-anything` and links it into Claude Code's personal skills directory (`~/.claude/skills/reverse-engineer-anything` or `$CLAUDE_CONFIG_DIR/skills/reverse-engineer-anything`). If directory symlinking is unavailable, setup falls back to copying the skill bundle directly with per-file `.rea.backup` preservation. `uninstall` removes both the canonical skill and Claude Code's skill location. ## Change and scope - `src/application/SupportedClients.ts`: Added optional `skillPath` property to `SetupClient` and `ClientDefinition`. Configured `claude_code` to define its personal skill path at `join(claudeCodeMarkerDirectory(context), "skills", PRODUCT_IDENTITY.skillName)`, honoring `CLAUDE_CONFIG_DIR`. - `src/application/SetupSkill.ts`: - Exported `canonicalSkillRoot`. - Added `isClientSkillAligned` to verify whether a client skill path is a valid symlink/junction pointing to canonical skill root or a directory whose contents match the canonical skill bundle. - Added `linkOrInstallClientSkill` to link the canonical bundle to a client skill path (using NTFS junction on Windows without requiring elevation, and directory symlink on POSIX), falling back to atomic direct file copy with `.rea.backup` if symlinking fails. - Added `skillNeedsInstallForClients` and `installSkillForClients`. - `src/application/SetupHost.ts`: Extended `skillNeedsInstall` and `installSkill` on `systemSetupHost` to accept selected clients and delegate to `skillNeedsInstallForClients` and `installSkillForClients`. - `src/application/SetupTypes.ts`: Updated `SetupHost` interface so `skillNeedsInstall` and `installSkill` optionally accept `clients?: readonly SetupClient[]`. - `src/application/SetupPlan.ts`: Passed `selectedClients` to `setupPlan` and updated `install_skill` detail disclosure when Claude Code is among selected clients. - `src/application/Setup.ts`: Threaded selected client candidates into `skillNeedsInstall` detection and passed `planSelection.selectedClients` to `installSkillAction`. - `src/application/Uninstall.ts`: Updated `removeManagedSkills` to clean up client skill paths (e.g. `claude_code`) before removing the canonical skill. - `docs/installation.md`: Added documentation explaining Claude Code's personal skills directory linking and `CLAUDE_CONFIG_DIR` behavior. - `tests/boundary/filesystem/setupSkill.test.ts`: Added test coverage for client skill linking, repair of stale/broken links, directory copy fallback, setup dry-run disclosure and execution with uninstall cleanup, and `CLAUDE_CONFIG_DIR` override. ## Contract and boundary impact - Semantic owner and earliest changed stage: `src/application/SupportedClients.ts` (client metadata boundary) and `src/application/SetupSkill.ts` (filesystem skill transaction). - CLI and MCP/tool-catalog contract: Unchanged. `install_skill` retains its canonical action ID. - Provider, bridge, target-format, or platform compatibility: Cross-platform. Uses directory junctions on Windows (`win32`) to avoid elevation requirements for non-admin users, and directory symlinks on POSIX. Respects `CLAUDE_CONFIG_DIR`. - Evidence, artifact, provenance, or reconstruction contract: None. - Process execution, authorization, cleanup, or containment impact: Unchanged. Idempotent setup and non-blocking plan disclosure. `uninstall` removes client-specific skill links and directories. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: Documentation updated; verified with `npm run docs:check`. ## Evidence and regression coverage - Tests added or updated: Added `client skill linking and lifecycle` test suite in `tests/boundary/filesystem/setupSkill.test.ts`: - `installs canonical skill and links into Claude Code personal skill location` - `repairs a broken or pointing-elsewhere client skill link` - `updates an existing directory with skill files when symlinking is not used` - `discloses Claude Code skill linking in setup plan and uninstalls cleanly` - `respects CLAUDE_CONFIG_DIR environment override` - Base reproduction: `rea setup --client claude_code --dry-run --json` planned action now discloses: `"Install or update the bundled REA reverse-engineering skill and on-demand references, and link into Claude Code's skills directory."` - User-visible CLI/MCP output: - `rea setup --client claude_code` installs to `~/.agents/skills/reverse-engineer-anything` and links to `~/.claude/skills/reverse-engineer-anything`. - Claude Code discovers and loads the skill from its personal skills directory. ## Validation performed - `npx vitest run tests/boundary/filesystem/setupSkill.test.ts`: passed (8 passed) - `npm run check:fast`: passed (typecheck and lint clean) - `npm run docs:check`: passed (all 6 tasks successful, no doc drift) - `npx oxfmt`: passed (all modified files formatted) ## Compatibility, safety, and release - Breaking changes or migration steps: None. Fully additive and idempotent. - Real Hopper/Ghidra, browser, or OS coverage: Verified on Windows with NTFS junction creation and POSIX path handling. - Package or release metadata impact: None. - Security, privacy, process, or containment review: Local-only, atomic writes with backups, no privilege escalation or external network calls required. ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-17 21:10:38 +00:00