skill-link-check

Original：🇨🇳 Chinese

Translated

2 scripts

Audit project and global .agents/skills and .claude/skills directory layouts. Verify that .agents/skills contains the actual source files and .claude/skills mirrors it through a parent-level symlink or per-skill symlinks. Use this tool whenever a skill or slash command is missing, fails to load, is duplicated, inconsistent, or when issues such as "skill not working", "skill inconsistency", "why isn't the skill recognized", "check skill links", ghost skill, broken skill link, or missing skill are encountered. It should also be used when a skill exists in one directory but not the other.

7installs

Sourceyan-labs/yan-skills

Added on2026-08-22

NPX Install

npx skill4agent add yan-labs/yan-skills skill-link-check

SKILL.md Content (Chinese)

View Translation Comparison →

Skill Link Check

Installation and Update

Source: Skills.sh

bash

# First-time global installation, or reinstall when update fails
npx skills add yan-labs/yan-skills --skill skill-link-check -g -y

# Update the installed global Skill
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

In

/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"

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

# 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

# Output stable JSON evidence; still returns 1 when issues are found
python3 "$(dirname "$0")/check.py" --json

Two Valid Layouts

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
```
: 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

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.

Validate the Skill Itself

bash

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

skill-link-check

NPX Install

Tags

SKILL.md Content (Chinese)

Skill Link Check

Installation and Update

Goal Contract

Execution Methods

Two Valid Layouts

Issue Categories

Reporting Rules

Validate the Skill Itself