skills.rest
rcarmo
rcarmoCOMMUNITY
Explore all skills by this author →
Website𝕏@rcarmoGitHub

script-discovery-annotation

Annotate and validate SCRIPT_JDOC metadata on TypeScript scripts for discovery tooling.

847|79|Updated Feb 17, 2026
Search Tags:#CLI#Bun#code documentation#Metadata#typeScript#annotation#script discovery
One-click install
npx skills add https://github.com/rcarmo/piclaw --skill script-discovery-annotation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: script-discovery-annotation
Source: https://github.com/rcarmo/piclaw/tree/main/skel/.pi/skills/script-discovery-annotation
Command: npx skills add https://github.com/rcarmo/piclaw --skill script-discovery-annotation

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Scripts shipped with skills or stored in workspaces are hard for discovery tools like list_scripts to find and describe unless they carry structured metadata. This Skill scaffolds, writes, and validates SCRIPT_JDOC comment blocks so every TypeScript script is reliably discoverable.

Core Features & Use Cases

  • Metadata Scaffolding: Preview or write generated SCRIPT_JDOC JSON blocks inferred from file paths, names, and content heuristics.
  • Role and Kind Classification: Distinguish runnable entrypoints from helper modules and classify scripts as read-only, mutating, or mixed with weight hints.
  • Validation Mode: Run a check pass that fails when any target script is missing a parseable SCRIPT_JDOC block.
  • Use Case: After adding a new workspace skill script under .pi/skills, run the annotator in write mode, hand-tune the summary and aliases, then run check mode to confirm the script is discoverable by list_scripts.

Quick Start

Ask the agent to annotate the scripts in a skill directory with SCRIPT_JDOC metadata and then validate that every script passes the discovery check.

Frequently Asked Questions about script-discovery-annotation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add SCRIPT_JDOC metadata to a TypeScript script?▼

Run the annotate-script-jdoc.ts script with Bun, passing --path to a file or directory and --write to insert the generated block. Without --write it only prints a preview of the scaffolded metadata.

How do I validate that all scripts have SCRIPT_JDOC blocks?▼

Run the annotator with --path and --check. It exits with an error listing every file that is missing a parseable SCRIPT_JDOC comment, and prints a success count when all files pass.

What fields does a SCRIPT_JDOC block contain?▼

The block is a JSON object with summary, aliases, domains, verbs, nouns, keywords, guidance, examples, kind (read-only, mutating, or mixed), weight (lightweight, standard, or heavy), and role (entrypoint or module).

How do I mark a helper module so it is not treated as an entrypoint?▼

Pass --role module when writing the annotation. The generated metadata then describes the file as a support module rather than a runnable script entrypoint.

Does the annotator overwrite existing SCRIPT_JDOC metadata?▼

No, existing blocks are left untouched by default and the file is reported as already annotated. Pass --force together with --write to replace an existing block with freshly generated metadata.

Related Skills

Explore More Software Engineering Skills→
seb1nseb1n
147

note-taking

Create structured Markdown notes with tags, links, and date-prefixed filenames.

Community
Intermediate
samcdavidsamcdavid
4

help-skills

Match user intent to ranked skill recommendations from a catalog.

Community
Intermediate
ramybarsoumramybarsoum

napkin-sketch

Generate annotated ASCII wireframes and capture browser screenshots for design matching.

Community
Intermediate
corey-alixcorey-alix

Package.json Command Commenter

Add descriptive // comments to new or modified package.json scripts.

Official
Basic