script-discovery-annotation

name	script-discovery-annotation
description	Add or validate SCRIPT_JDOC metadata on skill-shipped and workspace scripts so list_scripts and future script discovery can find them reliably.
distribution	public

Script Discovery Annotation

Use this skill when adding or updating TypeScript scripts that should be discoverable by list_scripts or future script-catalog tooling.

What to annotate

Apply SCRIPT_JDOC blocks to script files under surfaces such as:

• packaged skill scripts: runtime/skills/**/*.ts
• packaged extension skill scripts: runtime/extensions/**/skills/**/*.ts
• workspace skill scripts: .pi/skills/**/*.ts
• workspace note scripts: notes/**/*.ts

Workflow

1. Preview scaffold metadata for a file or directory:

   bun ./annotate-script-jdoc.ts --path <file-or-dir>
   

2. Write scaffold metadata in place:

   bun ./annotate-script-jdoc.ts --path <file-or-dir> --write
   

3. For helper/support modules that should not be treated as standalone entrypoints:

   bun ./annotate-script-jdoc.ts --path <file-or-dir> --write --role module
   

4. Validate that every target script has a parseable SCRIPT_JDOC block:

   bun ./annotate-script-jdoc.ts --path <file-or-dir> --check