Formalize script for enumerating skill references

[JasonYeMSFT (JasonYeMSFT)]

Description

This PR formalizes the reference script for reference file listing and added local references files to the output. This script will help detect dead reference files to guide clean up and optimization.

Checklist

• Tests pass locally (cd tests && npm test)
• If modifying skill descriptions: verified routing correctness with integration tests (npm run test:skills:integration -- <skill>)
• If modifying skill USE FOR / DO NOT USE FOR / PREFER OVER clauses: confirmed no routing regressions for competing skills

Related Issues

#2180

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR formalizes the references CLI by adding a JSON “list mode” that enumerates discovered local + remote links per skill, enabling detection of dead reference files and link inventories.

Changes:

• Adds local link details to per-skill validation results (localLinks) and propagates them through validation.
• Introduces --list CLI flag that outputs a structured JSON inventory of local/remote links plus totals.
• Updates CLI usage docs and adds exported list-result types.

Show a summary per file

File	Description
scripts/src/references/cli.ts	Adds local-link capture to validation results and implements --list JSON output for enumerating all links.

Copilot's findings

Comments suppressed due to low confidence (2)

scripts/src/references/cli.ts:493

• --list and --json can both be supplied, in which case --list silently wins due to ordering. To avoid surprising CLI behavior, consider making these flags mutually exclusive (emit a clear error + non-zero exit), or explicitly document precedence in the usage header.

  const jsonOutput = values.json ?? false;
  const listOutput = values.list ?? false;
  const requestedSkill = positionals[0];

  const skills = requestedSkill ? [requestedSkill] : listSkills();

scripts/src/references/cli.ts:493

• In --list mode, the CLI still runs the full validateSkill() pipeline (including issue/orphan checks) even though buildListJson() only consumes localLinks and remoteLinks. If orphan detection and issue validation are non-trivial, consider adding a lighter-weight collection path for list mode (e.g., a collectLinksForSkill() that skips orphan detection/issue checks) to reduce runtime and I/O when generating inventories.

  const skills = requestedSkill ? [requestedSkill] : listSkills();

• Files reviewed: 1/1 changed files
• Comments generated: 3