讓 Claude Code 讀到 .agents/skills

Claude Code 沒有掃 .agents/skills

Agent Skills 規格定義 SKILL.md 的結構，各個 client 仍可決定安裝位置。 許多工具採用 .agents/skills；Claude Code 的專案路徑則是 .claude/skills/<skill-name>/SKILL.md。檔案可讀，不等於原生 discovery 會找到它。

既有實體目錄現在會被擋下

vibeLinker 把 .agents\skills 定為唯一 Skill root，再為 Claude 與 Gemini 建立 Junction。舊版遇到實體目錄時只會跳過；目前版本會核對 Link 的實際 target， 把實體副本或錯誤 target 記成契約違規，最後以 exit code 1 結束。

$directoryLinks = [ordered]@{
    ".claude\skills" = ".agents\skills"
    ".gemini\skills" = ".agents\skills"
}

$instructionLinks = [ordered]@{
    "AGENTS.md" = "AGENTS.md"
    "CLAUDE.md" = "AGENTS.md"
    "GEMINI.md" = "AGENTS.md"
}

1. bootstrap 解析 canonical Skill root 與 host 端 target。
2. 既有 Junction 會比對實際 target；相符才視為已接好。
3. 實體副本或錯誤 target 會留下違規紀錄並讓 setup 失敗。

舊失敗模式仍值得保留：發現實體 .claude\skills 時，先分類 portable 與 Claude-only Skill，完成差異與備份後才遷移。直接刪除可能把 Claude-only Skill 一併移除。

動手前，先確認 .claude\skills 是什麼

• 以下命令都在專案根目錄執行。
• .agents\skills 必須存在，每個 Skill 目錄內要有 SKILL.md。
• 查清楚 .claude\skills 是實體目錄、Junction，還是 Symbolic Link，並核對 target。
• Hard Link 的來源與目標必須位於同一個 volume。
• Junction 可跨本機 volume，但不能指向映射的網路磁碟。

$repoRoot = (Resolve-Path ".").Path
$agentsSkills = Join-Path $repoRoot ".agents\skills"
$claudeSkills = Join-Path $repoRoot ".claude\skills"

if (-not (Test-Path -LiteralPath $agentsSkills)) {
    throw "找不到 Skill 來源目錄：$agentsSkills"
}

Get-Item -LiteralPath $agentsSkills -Force |
    Select-Object FullName, Attributes, LinkType, Target

if (Test-Path -LiteralPath $claudeSkills) {
    Get-Item -LiteralPath $claudeSkills -Force |
        Select-Object FullName, Attributes, LinkType, Target
}

兩種接法怎麼選

接法 A：整個 Skills 目錄做 Junction

$repoRoot = (Resolve-Path ".").Path
$source = Join-Path $repoRoot ".agents\skills"
$claudeDir = Join-Path $repoRoot ".claude"
$target = Join-Path $claudeDir "skills"

if (-not (Test-Path -LiteralPath $source)) {
    throw "找不到來源：$source"
}

New-Item -ItemType Directory -Path $claudeDir -Force | Out-Null

if (Test-Path -LiteralPath $target) {
    throw "目標已存在，未建立 Link：$target"
}

New-Item `
    -ItemType Junction `
    -Path $target `
    -Target (Resolve-Path $source) |
    Select-Object FullName, LinkType, Target

接法 B：只連需要共用的 Skill

.claude 已有內容時，從一個可攜 Skill 開始最安全。這個目錄之外的設定與 Claude-only Skills 都不會被碰到。

$repoRoot = (Resolve-Path ".").Path
$skillName = "my-skill"
$source = Join-Path $repoRoot ".agents\skills\$skillName"
$claudeSkills = Join-Path $repoRoot ".claude\skills"
$target = Join-Path $claudeSkills $skillName

if (-not (Test-Path -LiteralPath (Join-Path $source "SKILL.md"))) {
    throw "來源不是有效 Skill：$source"
}

New-Item -ItemType Directory -Path $claudeSkills -Force | Out-Null

if (Test-Path -LiteralPath $target) {
    throw "Claude Skill entry 已存在，未覆蓋：$target"
}

New-Item `
    -ItemType Junction `
    -Path $target `
    -Target (Resolve-Path $source) |
    Select-Object FullName, LinkType, Target

Windows 已開啟 Developer Mode，或目前 shell 具備 symlink 權限時，也可以建立 Symbolic Link：

New-Item `
    -ItemType SymbolicLink `
    -Path $target `
    -Target (Resolve-Path $source)

規則檔不必再複製一份

方案 A：薄 CLAUDE.md import

@AGENTS.md

## Claude Code

- 把只適用 Claude Code 的補充規則放在這裡。

方案 B：以 Hard Link 共用規則檔

$repoRoot = (Resolve-Path ".").Path
$agentsFile = Join-Path $repoRoot "AGENTS.md"
$claudeFile = Join-Path $repoRoot "CLAUDE.md"

if (-not (Test-Path -LiteralPath $agentsFile)) {
    throw "找不到 AGENTS.md 來源檔"
}

if (Test-Path -LiteralPath $claudeFile) {
    throw "CLAUDE.md 已存在，未建立 Hard Link"
}

New-Item `
    -ItemType HardLink `
    -Path $claudeFile `
    -Target $agentsFile

驗收要看 Link 身分，也要看內容

1. Link 型態與 target

Get-Item -LiteralPath ".claude\skills\my-skill" -Force |
    Select-Object FullName, Attributes, LinkType, Target

預期 Attributes 包含 ReparsePoint，LinkType 為 Junction 或 SymbolicLink，且 Target 指向預期來源。

2. Entrypoint 與 SHA-256

Test-Path -LiteralPath ".claude\skills\my-skill\SKILL.md"

Get-FileHash ".agents\skills\my-skill\SKILL.md"
Get-FileHash ".claude\skills\my-skill\SKILL.md"

Test-Path 應回傳 True，兩個 SHA-256 應一致。

3. Hard Link 身分

fsutil hardlink list ".\AGENTS.md"

預期清單同時包含 AGENTS.md 與 CLAUDE.md。內容相同的兩份副本不能當成 Hard Link 證據。

回到 Claude Code 做最後三項驗收

claude --version

1. 如果 session 啟動時還沒有頂層 .claude\skills，建立後重啟 Claude Code。
2. 輸入 /my-skill，確認 slash autocomplete 能看到該 Skill。
3. 用符合 frontmatter description 的自然語言任務，確認 auto-invocation。
4. 執行 /context，確認 Memory files 已載入 CLAUDE.md。

Link bootstrap 會碰哪些檔案

整套 bootstrap 會處理 metadata、wrapper、專案根目錄標記與清理流程。只想讓 Claude Code 看見一個 portable Skill 時，手動建立單一 Link 的變更面較小。

AST parse 只能證明 PowerShell 語法可解析，不能證明檔案變更符合預期。 在隔離的測試專案完成建立與清理流程前，不要把語法檢查當成安全驗收。

卡住時，從這裡查

交付前逐項確認

• .agents/skills/<name>/SKILL.md 是可攜 Skill 的唯一來源。
• .claude/skills/<name> 的 LinkType 與 Target 正確。
• Claude path 的 SKILL.md 可讀，SHA-256 與來源一致。
• /my-skill 出現在 slash autocomplete。
• 自然語言任務能觸發該 Skill。
• /context 顯示 CLAUDE.md。
• 使用 Hard Link 時，fsutil hardlink list 同時列出兩個檔名。
• bootstrap 或團隊文件已記錄 clone 後如何重建 Link。

資料來源與驗證邊界

• Claude Code：Extend Claude with skills
• Claude Code：Manage Claude's memory
• Agent Skills：Adding skills support to your agent
• Microsoft：Hard Links and Junctions
• PowerShell：New-Item