Agent Skills › rcarmo/piclaw › script-discovery-annotation

script-discovery-annotation

GitHub

用于为 TypeScript 脚本生成或验证 SCRIPT_JDOC 元数据，确保脚本能被 list_scripts 等工具可靠发现。支持预览、写入及校验模式，帮助维护脚本目录的可发现性。

skel/.pi/skills/script-discovery-annotation/SKILL.md rcarmo/piclaw

Trigger Scenarios

添加新脚本需被目录发现更新现有脚本元数据验证脚本注释完整性

Install

npx skills add rcarmo/piclaw --skill script-discovery-annotation -g -y

More Options

Non-standard path

npx skills add https://github.com/rcarmo/piclaw/tree/main/skel/.pi/skills/script-discovery-annotation -g -y

Use without installing

npx skills use rcarmo/piclaw@script-discovery-annotation

指定 Agent (Claude Code)

npx skills add rcarmo/piclaw --skill script-discovery-annotation -a claude-code -g -y

安装 repo 全部 skill

npx skills add rcarmo/piclaw --all -g -y

预览 repo 内 skill

npx skills add rcarmo/piclaw --list

SKILL.md

Frontmatter

{
    "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

Preview scaffold metadata for a file or directory:

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

Write scaffold metadata in place:

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

For helper/support modules that should not be treated as standalone entrypoints:
```
bun ./annotate-script-jdoc.ts --path <file-or-dir> --write --role module
```
Validate that every target script has a parseable SCRIPT_JDOC block:
```
bun ./annotate-script-jdoc.ts --path <file-or-dir> --check
```

Review checklist

After scaffolding, hand-tune the JSON block so it reflects the real user-facing purpose:

summary should be a short, literal description
aliases should match phrases a human would actually type
domains, verbs, and nouns should help intent matching
keywords should stay short and relevant
examples should be short task-shaped phrases
role should be entrypoint for runnable scripts and module for helper files
kind / weight should reflect real behavior and cost

Primary script purpose matters more than path scaffolding. Keep the metadata compact and human-facing.

Canonical fields

{
  summary?: string,
  aliases?: string[],
  domains?: string[],
  verbs?: string[],
  nouns?: string[],
  keywords?: string[],
  guidance?: string[],
  examples?: string[],
  kind?: "read-only" | "mutating" | "mixed",
  weight?: "lightweight" | "standard" | "heavy",
  role?: "entrypoint" | "module"
}

Notes

The helper script creates or updates only the SCRIPT_JDOC comment block.
Preview mode prints the generated block without modifying files.
--force replaces an existing block; without it, existing metadata is left alone.
Prefer manual review after scaffolding, especially for high-value scripts.
If list_scripts is available, use it after annotation to confirm the script is discoverable.