Script Kit Scripting

Patterns for writing scripts and scriptlet bundles.

Script Metadata (Preferred: Global Export)

Use for all new scripts/tests:

import '../../scripts/kit-sdk';

export const metadata = {
  name: "My Script",
  description: "Does something useful",
  shortcut: "cmd+shift+m",
  author: "Your Name",
  // more typed fields available
};

Why prefer global metadata:

• •Type safety (TS types)
• •IDE autocomplete + validation
• •More fields + easier extensibility
• •Compile-time feedback (vs runtime parsing)

Legacy Comment-Based Metadata

Supported for backwards compatibility:

// Name: My Script
// Description: Does something useful
// Shortcut: cmd+shift+m
import '../../scripts/kit-sdk';

SDK Import in Tests

Tests import from repo path:

import '../../scripts/kit-sdk'; // globals: arg(), div(), editor(), fields(), captureScreenshot(), getLayoutInfo(), ...

Production scripts use runtime-extracted SDK at ~/.scriptkit/sdk/kit-sdk.ts.

Scriptlet Bundles (~/.scriptkit/snippets/*.md)

Optional YAML frontmatter (line 1 must be ---, closed by --- on its own line):

---
name: My API Tools
description: Collection of useful API utilities
author: John Doe
icon: api
---

Fields: name, description, author, icon (all optional). Unknown fields ignored.

Backwards Compatibility

• •Frontmatter optional; bundles without it still work
• •Filename fallback: missing name uses filename (sans .md)
• •Invalid frontmatter logs warnings but does not break parsing

Validation Behavior

• •Missing closing --- → warn (line #), skip frontmatter
• •Invalid YAML → warn (error + line #), skip frontmatter
• •Errors surface to users via HUD notifications with line #

Default Icon Mapping

When no explicit icon::

• •template → text-cursor-input
• •tool → wrench
• •snippet → code
• •script → terminal
• •prompt → message-circle
• •action → zap
• •fallback → file-text

Icon resolution priority:

1. •explicit frontmatter icon
2. •tool-type default
3. •bundle fallback file-text

Troubleshooting

• •Frontmatter not parsed → must start on line 1 with --- and have closing --- on its own line
• •Icon not showing → verify icon name exists; check [CACHE] logs
• •HUD validation error → use the reported line number; quote special chars
• •Metadata not updating → touch file to refresh cache; check logs