skill-link-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Link Check

安装与更新

Installation and Update

来源：Skills.sh

bash

undefined

Source: Skills.sh

bash

undefined

首次全局安装，或更新失败时重新安装

First-time global installation, or reinstall when update fails

npx skills add yan-labs/yan-skills --skill skill-link-check -g -y

更新已安装的全局 Skill

Update the installed global Skill

npx skills update skill-link-check -g -y


若使用项目级安装，去掉安装命令中的 `-g`；项目级更新使用 `npx skills update skill-link-check -p -y`。

本 Skill 只审计目录布局，不自动移动、删除或覆盖文件：

- `.agents/skills/<name>/` 保存真实源文件。
- `.claude/skills` 要么整体链接到 `.agents/skills`，要么通过逐个子项链接镜像它。

最常见的漂移是 Skill 被直接创建成 `.claude/skills/<name>/` 真实目录，却没有进入 `.agents/skills/`。它看似已安装，实际不会随正常备份、同步或迁移流程保存。

npx skills update skill-link-check -g -y


For project-level installation, remove the `-g` flag from the installation command; use `npx skills update skill-link-check -p -y` for project-level updates.

This Skill only audits directory layouts and does not automatically move, delete, or overwrite files:

- `.agents/skills/<name>/` stores the actual source files.
- `.claude/skills` is either linked entirely to `.agents/skills` or mirrors it via per-child symlinks.

The most common drift occurs when a Skill is directly created as a real directory in `.claude/skills/<name>/` without being added to `.agents/skills/`. It appears to be installed but will not be preserved during normal backup, synchronization, or migration processes.

Goal Contract

在

/goal

、autopilot 或其他持续执行器中，本 Skill 的完成条件是“审计证据完整”，不是“退出码必须为 0”。发现问题是有效结果，不能为了让检查通过而擅自修复。

xml

<goal>审计所有适用作用域，判定 Skill 源目录与运行时镜像是否一致，并为每个问题提供可复核证据和修复命令。</goal>
<gate>检查脚本已从用户目标项目运行；每个适用作用域都有布局模式、问题分类和退出状态。</gate>
<done-when>无问题时明确报告 clean；有问题时完整列出数量、类别、路径和建议命令；未自动修改任何被审计目录。</done-when>

因此：

退出码
```
0
```
：审计完成且没有发现问题。
退出码
```
1
```
：审计完成且发现问题，不代表 Skill 执行失败。
Python traceback、参数错误或无法读取目标：才属于执行失败，需要修复后重跑。

/goal

, autopilot or other continuous executors, the completion condition for this Skill is "complete audit evidence", not "exit code must be 0". Identifying issues is a valid result, and no unauthorized fixes should be made to pass the check.

xml

<goal>Audit all applicable scopes, determine if Skill source directories and runtime mirrors are consistent, and provide reviewable evidence and repair commands for each issue.</goal>
<gate>Check script has run from the user's target project; each applicable scope has layout pattern, issue classification, and exit status.</gate>
<done-when>Clearly report clean when no issues exist; fully list the number, category, path, and suggested commands when issues are found; no audited directories are modified automatically.</done-when>

Therefore:

Exit code
```
0
```
: Audit completed with no issues found.
Exit code
```
1
```
: Audit completed with issues found; this does not indicate execution failure of the Skill.
Python traceback, parameter errors, or inability to read the target: these are considered execution failures and require fixes before re-running.

运行方式

Execution Methods

bash

python3 "$(dirname "$0")/check.py"

默认审计：

Project：当前目录下的
```
.agents/skills
```
与
```
.claude/skills
```
。
Global：
```
$HOME
```
下的同名目录。

自动化或 checker 可使用：

bash

undefined

bash

python3 "$(dirname "$0")/check.py"

Default audit scope:

Project:
```
.agents/skills
```
and
```
.claude/skills
```
in the current directory.
Global: The same-named directories under
```
$HOME
```
.

For automation or checkers, use:

bash

undefined

明确指定项目，避免依赖当前工作目录

Explicitly specify the project to avoid relying on the current working directory

python3 "$(dirname "$0")/check.py" --project-root /path/to/project

只查一个作用域

Audit only one scope

python3 "$(dirname "$0")/check.py" --project-only python3 "$(dirname "$0")/check.py" --global-only

输出稳定 JSON 证据；发现问题时仍返回 1

Output stable JSON evidence; still returns 1 when issues are found

python3 "$(dirname "$0")/check.py" --json

undefined

python3 "$(dirname "$0")/check.py" --json

undefined

两种合法布局

Two Valid Layouts

两种模式都应通过：

Parent symlink：
```
.claude/skills
```
本身指向
```
.agents/skills
```
。新增 Skill 自动保持一致。

Per-child symlinks：

.claude/skills

是真实目录，每个

.claude/skills/<name>

指向

../../.agents/skills/<name>

。

脚本会自动识别模式，不要求为了统一风格而改造一个本来健康的布局。

Both patterns should pass the audit:

Parent symlink:
```
.claude/skills
```
itself points to
```
.agents/skills
```
. Newly added Skills will automatically stay consistent.

Per-child symlinks:

.claude/skills

is a real directory, and each

.claude/skills/<name>

points to

../../.agents/skills/<name>

The script automatically identifies the pattern and does not require modifying a healthy layout for style consistency.

问题分类

Issue Categories

```
orphan-in-claude
```
：
```
.claude/skills/
```
中有真实条目，但
```
.agents/skills/
```
没有对应源文件。报告时优先列出。
```
missing-link
```
：源 Skill 存在，但运行时镜像缺失。
```
not-symlink
```
：逐子项模式下，镜像位置是重复的真实文件或目录。
```
broken-symlink
```
：链接目标不存在，包括损坏的父级链接。
```
wrong-target
```
：链接存在，但指向错误 Skill 或
```
.agents/skills
```
之外。

```
orphan-in-claude
```
: There is a real entry in
```
.claude/skills/
```
but no corresponding source file in
```
.agents/skills/
```
. This is prioritized in reports.
```
missing-link
```
: The source Skill exists but the runtime mirror is missing.
```
not-symlink
```
: In per-child symlink mode, the mirror location is a duplicate real file or directory.
```
broken-symlink
```
: The symlink target does not exist, including broken parent-level links.
```
wrong-target
```
: The symlink exists but points to the wrong Skill or outside
```
.agents/skills
```
.

报告规则

Reporting Rules

先给总问题数和分类计数；有
```
orphan-in-claude
```
时先报告它。
每项给出名称、证据路径和一行解释。
原样附上脚本生成的建议修复命令，便于用户复核后执行。
不自动修复。孤儿目录可能是用户尚未迁移的工作，重复目录也可能已经分叉；自动移动或删除会造成数据损失。
如果全部健康，一句话说明适用作用域及布局模式即可结束。

First provide the total number of issues and category counts; prioritize reporting
```
orphan-in-claude
```
if present.
For each issue, provide the name, evidence path, and a one-line explanation.
Include the script-generated suggested fix commands as-is for users to review and execute.
No automatic fixes. Orphan directories may be work the user has not yet migrated, and duplicate directories may have diverged; automatic moving or deletion could cause data loss.
If everything is healthy, conclude with a single statement indicating the applicable scope and layout pattern.

验证 Skill 自身

Validate the Skill Itself

bash

python3 -m unittest discover -s "$(dirname "$0")/tests" -v

bash

python3 -m unittest discover -s "$(dirname "$0")/tests" -v