Skill Bundle Check

Your skill works in the repo. Does it still work after installation?

Skill Bundle Check has two read-only checks. check compares a source Agent Skill with the exact folder produced by your installer or release build, including its local references. check-agent looks for SKILL.md in a supported agent's documented install directory and reports when the file exists only in a different shared root.

It does not run the skill, start the agent, or claim that the agent loaded it at runtime.

Why this exists

People have reported Agent Skills whose SKILL.md points to files that are missing or unreachable after installation. This shows up in different forms:

• Agent-Reach, Hallmark, Tastemaker, and Microsoft APM report supporting files omitted from installed skills.
• Addy Osmani's agent-skills #468 reports shared references that remain unreachable even in a full plugin install because the links resolve from each skill directory. #597 documents the related single-skill install case.
• OpenAI Codex #8364 records a referenced script missing from the installed skill; the maintainer linked it to a separate fix in progress.
• CLI-Anything #331 reports an installer that copies the skill but leaves its referenced methodology files behind.
• Vercel Skills #1851 reports a successful global install that places a Skill in a shared directory instead of Antigravity CLI's documented global directory.

Format validation alone may not catch these failures. A reproduction report shows a skill-reference check passing while the referenced file is missing. This tool checks the actual source and installed folders instead.

Existing structure and security checks are useful before publishing. This tool adds one narrow check: compare the skill folder you intend to ship with the copy users will actually install.

Quick start

Use Node.js 20 or later. No dependencies, account, or network access are needed.

git clone https://github.com/LydiaTools/skill-bundle-check.git
cd skill-bundle-check
node src/cli.js check ./examples/source ./examples/installed

Run it against a real installation or build output:

node src/cli.js check ./skills/my-skill ~/.agents/skills/my-skill

The first path is the source skill folder containing SKILL.md. The second is the exact installed or packaged folder to verify. The command only reads files; it does not run install scripts or skill code.

Check whether an agent has a Skill at its documented global path:

node src/cli.js check-agent --agent claude-code --skill my-skill --scope global
node src/cli.js check-agent --agent codex-cli --skill my-skill --scope global
node src/cli.js check-agent --agent antigravity-cli --skill my-skill --scope global
node src/cli.js check-agent --agent antigravity-ide --skill my-skill --scope global

For a repository-local Skill, use --scope project:

node src/cli.js check-agent --agent claude-code --skill my-skill --scope project
node src/cli.js check-agent --agent codex-cli --skill my-skill --scope project

For another agent, pass its documented Skills root directly:

node src/cli.js check-agent --root ./custom-agent/skills --skill my-skill --scope global

Built-in profiles cover claude-code, codex-cli, antigravity-cli, antigravity-ide, and antigravity-app. Profile paths link to the platform documentation used for the mapping: Claude Code Skills, Codex Skills, and Antigravity Skills. Project scope checks the project directory represented by the current working directory. A missing Skill returns exit code 1. If the Skill is found in ~/.agents/skills but not in the selected global root, the report shows both paths. A documented legacy Antigravity IDE path is also recognized. This checks file placement; it does not confirm runtime discovery or execution.

Reproduce an install-path mismatch with the included synthetic fixture:

node src/cli.js check-agent --agent antigravity-cli --skill probe-skill --scope global --home ./examples/agent-paths

The command intentionally exits with code 1 and reports that probe-skill exists under the shared .agents/skills root, not Antigravity CLI's documented global root. No agent is launched.

The repository includes both a preserved bundle and a deliberately broken installation. The failing fixture demonstrates the exact check:

$ node src/cli.js check ./examples/source ./examples/installed-missing
REFERENCE_MISSING_FROM_INSTALL  installed/SKILL.md:8  Referenced file is missing: references/setup.md

FAIL  2 local references checked
source: 2 Markdown files · installed: 1 Markdown files

GitHub Actions

Run your normal packaging/install step first, then check its output:

steps:
  - uses: actions/checkout@v4
  - name: Build skill bundle
    run: ./scripts/build-skill.sh
  - uses: LydiaTools/skill-bundle-check@v0.3.0
    with:
      source: ./skills/my-skill
      installed: ./dist/my-skill

Findings become inline GitHub annotations. For a local JSON report:

node src/cli.js check ./skills/my-skill ./dist/my-skill --format json

What it checks

• SKILL.md exists in both folders.
• Local links in Markdown and HTML references point to files or directories that exist in the source.
• Referenced files remain present at the same relative paths in the installed bundle.
• Relative links in the installed copy resolve inside that bundle.
• Absolute paths, missing files, broken symlinks, and links that escape the bundle root are reported with file and line.

It reads Markdown links, reference-style link definitions, HTML href/src, and conventional assets/, references/, or scripts/ paths written in inline code. It does not parse every Markdown extension or execute examples.

check-agent checks for the selected Skill's SKILL.md at the chosen documented root. Built-in paths link to the platform documentation used for that mapping; custom roots are checked exactly as supplied.

Examples

The fixture models a package with a supporting file preserved:

examples/
├── source/
│   ├── SKILL.md
│   └── references/setup.md
├── installed/
│   ├── SKILL.md
│   └── references/setup.md
└── installed-missing/
    └── SKILL.md

If references/setup.md is omitted from installed/, the check fails and reports the source line that still points to it.

Development

npm test

License

MIT. Source code is original to this repository; the cited issues are examples of reported problems, not endorsements.