Troubleshoot Skill | Agent Skills

Troubleshoot

Diagnose and fix common Script Kit issues.

Log Files

~/.scriptkit/logs/script-kit-gpui.jsonl

JSONL format — each line is a JSON object with timestamp, level, message, and optional fields.

Reading Logs

# Last 50 lines
tail -50 ~/.scriptkit/logs/script-kit-gpui.jsonl

# Filter errors
grep '"level":"ERROR"' ~/.scriptkit/logs/script-kit-gpui.jsonl | tail -20

# Filter by module
grep '"target":"script_kit"' ~/.scriptkit/logs/script-kit-gpui.jsonl | tail -20

Compact AI Log Mode

Set SCRIPT_KIT_AI_LOG=1 for compact, human-readable log output (useful for debugging):

SCRIPT_KIT_AI_LOG=1 ~/.scriptkit/cache/Script\ Kit.app/Contents/MacOS/script-kit-gpui

Common Issues

Script Not Appearing in Menu

Check file location: Must be in ~/.scriptkit/plugins/main/scripts/*.ts
Check metadata export: Must have export const metadata = { name: "..." }
Check syntax: Run bun check ~/.scriptkit/plugins/main/scripts/your-script.ts
Check logs: Look for parse errors in the log file

Script Crashes on Run

Check SDK import: First line must be import "@scriptkit/sdk";
Check Bun availability: Run which bun in terminal
Check for Node.js patterns: Replace CommonJS imports, fs.readFile, child_process with Bun equivalents
Check logs for the error stack trace

Hotkey Not Working

Check config syntax: Validate ~/.scriptkit/config.ts has correct hotkey format
Check for conflicts: Another app may have claimed the hotkey
Try a different hotkey: Some key combinations are reserved by macOS
Restart Script Kit: Close and reopen the app

Theme Not Applying

Validate JSON: Run cat ~/.scriptkit/theme.json | python3 -m json.tool
Check color format: Use "#RRGGBB", "rgb(r,g,b)", or "rgba(r,g,b,a)"
Save the file: Theme reloads on save, not on edit

Extensions Not Loading

Check file location: Must be in ~/.scriptkit/plugins/main/scriptlets/*.md
Check frontmatter: Must have ---\nname: ...\n--- at the top
Check fence syntax: Use ```bash, ```tool:name, or ```template:name
Check for syntax errors in tool: scriptlets

Debugging a Script

Add Logging

import "@scriptkit/sdk";

export const metadata = { name: "Debug Example", description: "Testing" };

console.log("Script started");
const input = await arg("Enter something");
console.log("User entered:", input);
// Check logs for output

Test in Terminal

cd ~/.scriptkit
bun run plugins/main/scripts/your-script.ts

Check TypeScript Errors

cd ~/.scriptkit
bun run typecheck

File Locations Quick Reference

| What | Where | |------|-------| | App logs | ~/.scriptkit/logs/script-kit-gpui.jsonl | | Scripts | ~/.scriptkit/plugins/main/scripts/ | | Extensions | ~/.scriptkit/plugins/main/scriptlets/ | | Config | ~/.scriptkit/config.ts | | Theme | ~/.scriptkit/theme.json | | SDK (read-only) | ~/.scriptkit/sdk/kit-sdk.ts | | Databases | ~/.scriptkit/db/ | | Cache | ~/.scriptkit/cache/ |

Reset to Defaults

To reset configuration:

rm ~/.scriptkit/config.ts
rm ~/.scriptkit/theme.json

Script Kit will recreate them with defaults on next launch.

To reset everything (nuclear option):

rm -rf ~/.scriptkit

Script Kit will recreate the full workspace on next launch.

Agent Skills: Troubleshoot

Install this agent skill to your local

Skill Files