Skip to content

Add a validator that checks all agent- and skill-referenced files resolve after install #790

Description

@williamthorsen

Description

The installed agent and skill definitions reference helper scripts and bundled helpers through the {platform_home_dir}/scripts/… template (and {platform_home_dir}/skills/…/*.mjs for bundled helpers), which the install pipeline expands to an absolute path per platform target. Nothing verifies, after install, that those resolved paths actually point at files that exist. A packaging gap, a partial install, or a script renamed in some definitions but not others surfaces only when an agent invokes the path at runtime, often mid-run, where the failure is expensive and hard to attribute.

The existing script-invocation-conventions.test.ts guards that source content uses the correct template prefix, but it does not check that the installed targets resolve to present files. The two concerns are distinct: prefix-correctness is a content convention, whereas file-presence is an install and environment property.

This work was split out while narrowing #697. That ticket's original sixth acceptance criterion wanted an install-time check that fails when a script reference cannot be resolved. The intent is sound but orthogonal to the one-line content fix #697 became, and it is better served by a dedicated, user-runnable validator.

Acceptance criteria

Must have

  • A user-runnable command scans the installed agent and skill definitions and reports every referenced script or bundled-helper path that does not resolve to an existing file.
  • The command exits non-zero when any referenced path is missing, so it can gate a post-install check or CI.
  • Output names each missing file together with the definition that references it.
  • New and modified behavior is covered by tests.
  • The command is documented (help text and usage).

Should have

  • The validator covers both {platform_home_dir}/scripts/*.sh references and bundled .mjs helper references (for example, derive-session-context.mjs).
  • The validator checks every installed platform target (.claude, .codex, and so on), not just one.

Nice to have

  • An opt-in mode wires the validator into the install pipeline as a final self-check, surfacing missing files at install time.

Metadata

Metadata

Labels

featureAdded or improved external functionalityscope:agents

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions