skill-link-check

Skill Link Check

Installation and Update

# 首次全局安装，或更新失败时重新安装
npx skills add yan-labs/yan-skills --skill skill-link-check -g -y

# 更新已安装的全局 Skill
npx skills update skill-link-check -g -y

If using project-level installation, remove from the install command the -g; for project-level updates use npx skills update skill-link-check -p -y。

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

.agents/skills/<name>/ Save the real source files.
.claude/skills Either link the whole thing to .agents/skills, or mirror it via per-child links.

The most common drift is a Skill being created directly as a .claude/skills/<name>/ real directory, yet not entering .agents/skills/. It appears installed, but in reality it will not be preserved by normal backup, sync, or migration processes.

Completion Conditions and Exit Codes

In /goal or a continuously executing task, use complete audit evidence as the completion condition: run the script from the target project, and report the layout, issue classification, and exit status for each applicable scope. When there are issues, list the count, paths, and suggested commands; when there are no issues, report clean. The script does not modify the audited directory.

0: Audit completed with no issues.
1: Audit completed with issues found; this is still a valid result.
Python traceback, argument error, or target unreadable: execution failed; investigate and rerun.

How to Run

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

Default audit:

Project: in the current directory, .agents/skills and .claude/skills。
Global：$HOME directories with the same name under it.

Automation or a checker can use:

# 明确指定项目，避免依赖当前工作目录
python3 "$(dirname "$0")/check.py" --project-root /path/to/project

# 只查一个作用域
python3 "$(dirname "$0")/check.py" --project-only
python3 "$(dirname "$0")/check.py" --global-only

# 输出稳定 JSON 证据；发现问题时仍返回 1
python3 "$(dirname "$0")/check.py" --json

Two Valid Layouts

Both modes should pass:

Parent symlink：.claude/skills itself points to .agents/skills. Newly added Skills 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 detects the mode and does not require remodeling an already healthy layout just to unify the style.

Issue Classification

orphan-in-claude：.claude/skills/ has a real entry, but .agents/skills/ has no corresponding source file. List this first when reporting.
missing-link: The source Skill exists, but the runtime mirror is missing.
not-symlink: In per-child mode, the mirror location is a duplicate real file or directory.
broken-symlink: The link target does not exist, including broken parent links.
wrong-target: The link exists, but points to the wrong Skill or is outside .agents/skills .

Reporting Rules

First give the total issue count and category counts; when there is orphan-in-claude , report it first.
For each item, give the name, evidence path, and a one-line explanation.
Attach the script-generated suggested fix commands as-is, so the user can review before executing.
Do not auto-fix. Orphan directories may be work the user has not yet migrated, and duplicate directories may already have diverged; automatically moving or deleting them would cause data loss.
If everything is healthy, a single sentence stating the applicable scope and layout mode is enough to conclude.

Verify the Skill itself

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