build-raycast-script-command

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build Raycast Script Command

构建Raycast Script Command

Build Raycast Script Commands with correct metadata, mode selection, argument wiring, and runtime behavior.

使用正确的元数据、模式选择、参数配置和运行时行为来构建Raycast Script Commands。

Trigger boundary

触发边界

Use this skill when the task involves:

Creating a new Raycast Script Command from scratch
Converting an existing Python or Bash script into a Raycast Script Command
Choosing between
```
fullOutput
```
,
```
compact
```
,
```
silent
```
, and
```
inline
```
Adding or fixing Script Command arguments
Fixing why a Script Command does not appear in Raycast
Fixing output, refresh, or failure behavior in a Script Command
Making a Script Command more shareable or closer to Raycast community conventions

Do NOT use this skill for:

Full Raycast Extensions API work with
```
@raycast/api
```
, React, List, Grid, Form, or Detail views
General shell scripting that is not intended for Raycast
General Python scripting that has no Raycast integration

If the project already imports

@raycast/api

or uses

ray build

ray develop

, stop and use a Raycast Extensions skill instead.

当任务涉及以下内容时使用本技能：

从零开始创建新的Raycast Script Command
将现有的Python或Bash脚本转换为Raycast Script Command
在
```
fullOutput
```
、
```
compact
```
、
```
silent
```
和
```
inline
```
之间选择合适的模式
添加或修复Script Command的参数
排查Script Command未在Raycast中显示的原因
修复Script Command的输出、刷新或失败行为
让Script Command更易于分享或更贴近Raycast社区规范

请勿在以下场景使用本技能：

使用
```
@raycast/api
```
、React、List、Grid、Form或Detail视图进行完整的Raycast扩展API开发
不用于Raycast的通用Shell脚本开发
未集成Raycast的通用Python脚本开发

如果项目已导入

@raycast/api

或使用

ray build

ray develop

，请停止使用本技能，转而使用Raycast扩展相关技能。

Behavioral flow

行为流程

Step 1: Detect what exists

步骤1：检测现有内容

Inspect the current workspace before writing anything.

Look for:

an existing
```
.py
```
or
```
.sh
```
file to convert
metadata lines such as
```
@raycast.title
```
a request for a greenfield command vs a repair task
whether the command is Python-first, Bash-first, or undecided

在编写任何内容之前，先检查当前工作区。

查找：

待转换的现有
```
.py
```
或
```
.sh
```
文件
类似
```
@raycast.title
```
的元数据行
是从零开始创建命令还是修复任务的需求
命令优先使用Python、Bash还是未确定

Step 2: Choose the branch

步骤2：选择分支

Use this decision tree:

text

User request
├─ "Create a new command from scratch"
│  ├─ Python is the best fit or unspecified
│  │  → Read references/foundations/workflow.md
│  │  → Read references/python/file-anatomy.md
│  │  → Read references/metadata/mode-selection.md
│  │  → Read references/examples/python-recipes.md
│  └─ Bash is clearly the best fit
│     → Read references/foundations/workflow.md
│     → Read references/bash/bash-script-patterns.md
│     → Read references/metadata/mode-selection.md
│     → Read references/examples/bash-recipes.md
│
├─ "Convert an existing script into a Raycast command"
│  → Read references/foundations/workflow.md
│  → Read references/metadata/required-fields.md
│  → Read references/conventions/dependencies-and-portability.md
│  → Read references/troubleshooting/discovery-checklist.md
│
├─ "Choose or change the output mode"
│  → Read references/metadata/mode-selection.md
│  → Read references/metadata/inline-refresh-and-errors.md
│
├─ "Add or fix arguments"
│  → Read references/arguments/typed-arguments.md
│  → Read references/python/implementation-patterns.md or references/bash/bash-script-patterns.md
│
├─ "Why doesn't this command show up in Raycast?"
│  → Read references/troubleshooting/discovery-checklist.md
│  → Read references/metadata/required-fields.md
│
├─ "Why does runtime behavior/output feel wrong?"
│  → Read references/troubleshooting/runtime-and-output-issues.md
│  → Read references/metadata/mode-selection.md
│  → Read references/metadata/inline-refresh-and-errors.md
│
├─ "Should this be Python or Bash?"
│  → Read references/foundations/language-selection.md
│
└─ "Make this repo-ready or shareable"
   → Read references/conventions/community-repo-conventions.md
   → Read references/conventions/dependencies-and-portability.md

使用以下决策树：

text

User request
├─ "Create a new command from scratch"
│  ├─ Python is the best fit or unspecified
│  │  → Read references/foundations/workflow.md
│  │  → Read references/python/file-anatomy.md
│  │  → Read references/metadata/mode-selection.md
│  │  → Read references/examples/python-recipes.md
│  └─ Bash is clearly the best fit
│     → Read references/foundations/workflow.md
│     → Read references/bash/bash-script-patterns.md
│     → Read references/metadata/mode-selection.md
│     → Read references/examples/bash-recipes.md
│
├─ "Convert an existing script into a Raycast command"
│  → Read references/foundations/workflow.md
│  → Read references/metadata/required-fields.md
│  → Read references/conventions/dependencies-and-portability.md
│  → Read references/troubleshooting/discovery-checklist.md
│
├─ "Choose or change the output mode"
│  → Read references/metadata/mode-selection.md
│  → Read references/metadata/inline-refresh-and-errors.md
│
├─ "Add or fix arguments"
│  → Read references/arguments/typed-arguments.md
│  → Read references/python/implementation-patterns.md or references/bash/bash-script-patterns.md
│
├─ "Why doesn't this command show up in Raycast?"
│  → Read references/troubleshooting/discovery-checklist.md
│  → Read references/metadata/required-fields.md
│
├─ "Why does runtime behavior/output feel wrong?"
│  → Read references/troubleshooting/runtime-and-output-issues.md
│  → Read references/metadata/mode-selection.md
│  → Read references/metadata/inline-refresh-and-errors.md
│
├─ "Should this be Python or Bash?"
│  → Read references/foundations/language-selection.md
│
└─ "Make this repo-ready or shareable"
   → Read references/conventions/community-repo-conventions.md
   → Read references/conventions/dependencies-and-portability.md

Step 3: Implement directly

步骤3：直接实现

Once the branch is clear:

Read only the routed references for that branch.
Build or edit the Script Command directly.
Use the templates in
```
assets/templates/
```
only as starting points, not rigid output.
Keep the implementation minimal and aligned with Raycast's documented behavior.

一旦分支明确：

仅阅读该分支对应的参考文档。
直接构建或编辑Script Command。
仅将
```
assets/templates/
```
中的模板作为起点，而非严格的输出标准。
保持实现简洁，与Raycast文档记录的行为一致。

Step 4: Validate before stopping

步骤4：结束前验证

Always verify these:

required metadata exists
chosen
```
mode
```
matches the shape of output
```
inline
```
commands include
```
refreshTime
```
arguments match how the script reads positional inputs
failure paths print a human-readable final line and exit non-zero
dependency instructions exist when the command depends on extra tools or packages

始终验证以下内容：

存在必填元数据
选择的
```
mode
```
与输出格式匹配
```
inline
```
命令包含
```
refreshTime
```
参数与脚本读取位置输入的方式匹配
失败路径输出易读的最终行并以非零状态退出
当命令依赖额外工具或包时，存在依赖说明

Core defaults

核心默认规则

Default to Python for API calls, JSON parsing, text processing, and richer logic.
Default to Bash for tiny shell-native wrappers around existing CLIs or OS actions.
Default to
```
fullOutput
```
if the result is meant to be read.
Default to
```
compact
```
or
```
silent
```
for single-line confirmations or actions.
Use
```
inline
```
only for dashboard-style, one-line status commands.

对于API调用、JSON解析、文本处理和复杂逻辑，默认使用Python。
对于围绕现有CLI或操作系统操作的小型Shell原生封装，默认使用Bash。
如果结果用于阅读，默认使用
```
fullOutput
```
。
对于单行确认或操作，默认使用
```
compact
```
或
```
silent
```
。
仅针对仪表板风格的单行状态命令使用
```
inline
```
。

Key patterns

关键模式

Pattern 1: minimal Python command

模式1：极简Python命令

python

#!/usr/bin/env python3

python

#!/usr/bin/env python3

@raycast.schemaVersion 1

@raycast.title Example Python Command

@raycast.mode fullOutput

@raycast.packageName Examples

print("Hello from Raycast")

undefined

print("Hello from Raycast")

undefined

Pattern 2: safe optional arguments in Python

模式2：Python中的安全可选参数

python

import sys

def arg(index: int, default: str = "") -> str:
    return sys.argv[index] if len(sys.argv) > index else default

query = arg(1)

python

import sys

def arg(index: int, default: str = "") -> str:
    return sys.argv[index] if len(sys.argv) > index else default

query = arg(1)

Pattern 3: clean failure path

模式3：清晰的失败路径

python

print("Missing API token")
raise SystemExit(1)

python

print("Missing API token")
raise SystemExit(1)

Pattern 4: minimal Bash command

模式4：极简Bash命令

bash

#!/usr/bin/env bash
set -euo pipefail

bash

#!/usr/bin/env bash
set -euo pipefail

@raycast.schemaVersion 1

@raycast.title Example Bash Command

@raycast.mode compact

@raycast.packageName Examples

echo "Done"

undefined

echo "Done"

undefined

Minimal reading sets

极简参考文档集

"Create a new Python Script Command"

"创建新的Python Script Command"

```
references/foundations/workflow.md
```
```
references/python/file-anatomy.md
```

references/python/implementation-patterns.md

```
references/metadata/mode-selection.md
```
```
references/examples/python-recipes.md
```

```
references/foundations/workflow.md
```
```
references/python/file-anatomy.md
```

references/python/implementation-patterns.md

```
references/metadata/mode-selection.md
```
```
references/examples/python-recipes.md
```

"Create a new Bash Script Command"

"创建新的Bash Script Command"

```
references/foundations/workflow.md
```
```
references/bash/bash-script-patterns.md
```
```
references/metadata/mode-selection.md
```
```
references/examples/bash-recipes.md
```

```
references/foundations/workflow.md
```
```
references/bash/bash-script-patterns.md
```
```
references/metadata/mode-selection.md
```
```
references/examples/bash-recipes.md
```

"Convert an existing script"

"转换现有脚本"

```
references/foundations/workflow.md
```
```
references/metadata/required-fields.md
```

references/conventions/dependencies-and-portability.md

references/troubleshooting/discovery-checklist.md

```
references/foundations/workflow.md
```
```
references/metadata/required-fields.md
```

references/conventions/dependencies-and-portability.md

references/troubleshooting/discovery-checklist.md

"Add arguments"

"添加参数"

```
references/arguments/typed-arguments.md
```

references/python/implementation-patterns.md

```
references/bash/bash-script-patterns.md
```

```
references/arguments/typed-arguments.md
```

references/python/implementation-patterns.md

```
references/bash/bash-script-patterns.md
```

"Fix inline/compact/silent/fullOutput behavior"

"修复inline/compact/silent/fullOutput行为"

```
references/metadata/mode-selection.md
```

references/metadata/inline-refresh-and-errors.md

references/troubleshooting/runtime-and-output-issues.md

```
references/metadata/mode-selection.md
```

references/metadata/inline-refresh-and-errors.md

references/troubleshooting/runtime-and-output-issues.md

"Make it community-repo ready"

"使其符合社区仓库规范"

references/conventions/community-repo-conventions.md

references/conventions/dependencies-and-portability.md

references/troubleshooting/discovery-checklist.md

references/conventions/community-repo-conventions.md

references/conventions/dependencies-and-portability.md

references/troubleshooting/discovery-checklist.md

Templates

模板

When a user wants a quick scaffold, start from:

assets/templates/python-script-command.py

```
assets/templates/bash-script-command.sh
```

Then adapt the template to the user's exact mode, arguments, and dependencies.

当用户需要快速脚手架时，从以下模板开始：

assets/templates/python-script-command.py

```
assets/templates/bash-script-command.sh
```

然后根据用户的具体模式、参数和依赖调整模板。

Common pitfalls

常见陷阱

Pitfall	Fix
Using Extensions API concepts in a Script Command	Stop and switch skills; Script Commands are metadata plus normal script execution
Choosing `compact` for multi-line output	Move to `fullOutput`
Choosing `inline` without `refreshTime`	Add `refreshTime` or switch modes
Reading optional args unsafely	Guard Python `sys.argv` and Bash positional params
Leaving user-specific placeholders in a runnable file	Use `.template.` or fully configure the command
Missing dependency instructions	Add top-of-file dependency notes and readable missing-dependency failures

陷阱	修复方案
在Script Command中使用扩展API概念	停止并切换技能；Script Command仅包含元数据和常规脚本执行逻辑
为多行输出选择 `compact` 模式	切换到 `fullOutput`
选择 `inline` 模式但未设置 `refreshTime`	添加 `refreshTime` 或切换模式
不安全地读取可选参数	对Python的 `sys.argv` 和Bash的位置参数进行保护
在可运行文件中保留用户特定占位符	使用 `.template.` 后缀或完全配置命令
缺少依赖说明	在文件顶部添加依赖说明，并在缺少依赖时输出清晰的失败信息

Reference files

参考文件

File	When to read
`references/foundations/scope-and-fit.md`	Read when deciding whether the task is really a Script Command and not a full Raycast extension.
`references/foundations/workflow.md`	Read when creating or converting a command and you need the end-to-end build flow.
`references/foundations/language-selection.md`	Read when deciding between Python and Bash.
`references/metadata/required-fields.md`	Read when adding or repairing metadata headers.
`references/metadata/mode-selection.md`	Read when choosing between `fullOutput` , `compact` , `silent` , and `inline` .
`references/metadata/inline-refresh-and-errors.md`	Read when working on inline refresh, first-line/last-line behavior, or failure semantics.
`references/arguments/typed-arguments.md`	Read when adding, changing, or debugging Script Command arguments.
`references/python/file-anatomy.md`	Read when creating a Python command file or checking placement of metadata and code.
`references/python/implementation-patterns.md`	Read when wiring `sys.argv` , dependency notes, failure messages, or Python output patterns.
`references/bash/bash-script-patterns.md`	Read when building or fixing a Bash-based Script Command.
`references/conventions/community-repo-conventions.md`	Read when the command should follow Raycast community-repo conventions.
`references/conventions/dependencies-and-portability.md`	Read when the command depends on tools/packages or must stay portable.
`references/troubleshooting/discovery-checklist.md`	Read when a command does not appear in Raycast or seems not to be recognized.
`references/troubleshooting/runtime-and-output-issues.md`	Read when output, refresh, or failure behavior is wrong.
`references/examples/python-recipes.md`	Read when you need concrete Python command patterns.
`references/examples/bash-recipes.md`	Read when you need concrete Bash command patterns.
`references/sources/source-map.md`	Read when you need the provenance for the internal references or want to expand the skill from the original Raycast research docs.

文件	阅读时机
`references/foundations/scope-and-fit.md`	当需要判断任务是否属于Script Command而非完整Raycast扩展时阅读。
`references/foundations/workflow.md`	当创建或转换命令，需要端到端构建流程时阅读。
`references/foundations/language-selection.md`	当需要在Python和Bash之间做选择时阅读。
`references/metadata/required-fields.md`	当添加或修复元数据头部时阅读。
`references/metadata/mode-selection.md`	当需要在 `fullOutput` 、 `compact` 、 `silent` 和 `inline` 之间选择时阅读。
`references/metadata/inline-refresh-and-errors.md`	当处理inline刷新、首行/末行行为或失败语义时阅读。
`references/arguments/typed-arguments.md`	当添加、修改或调试Script Command参数时阅读。
`references/python/file-anatomy.md`	当创建Python命令文件或检查元数据与代码的放置位置时阅读。
`references/python/implementation-patterns.md`	当配置 `sys.argv` 、依赖说明、失败消息或Python输出模式时阅读。
`references/bash/bash-script-patterns.md`	当构建或修复基于Bash的Script Command时阅读。
`references/conventions/community-repo-conventions.md`	当命令需要遵循Raycast社区仓库规范时阅读。
`references/conventions/dependencies-and-portability.md`	当命令依赖工具/包或需要保持可移植性时阅读。
`references/troubleshooting/discovery-checklist.md`	当命令未在Raycast中显示或未被识别时阅读。
`references/troubleshooting/runtime-and-output-issues.md`	当输出、刷新或失败行为异常时阅读。
`references/examples/python-recipes.md`	当需要具体的Python命令模式时阅读。
`references/examples/bash-recipes.md`	当需要具体的Bash命令模式时阅读。
`references/sources/source-map.md`	当需要内部参考的来源或想从Raycast原始研究文档扩展本技能时阅读。

Guardrails

约束规则

Do not invent metadata fields that are not verified in Raycast-owned sources.
Do not use Extensions API components or
```
@raycast/api
```
patterns in a Script Command.
Do not choose
```
inline
```
without
```
refreshTime
```
.
Do not emit noisy multi-line progress output for
```
compact
```
,
```
silent
```
, or
```
inline
```
.
Do not read optional arguments unsafely; guard Python
```
sys.argv
```
access and shell
```
$2
```
/
```
$3
```
usage.
Do not hide missing dependencies; document them and fail clearly.
Do not leave
```
.template.
```
in a filename unless the command intentionally requires user edits before use.
Do not bloat the response with generic shell or Python tutorials when the routed references already cover the needed pattern.

不要发明未在Raycast官方来源中验证的元数据字段。
不要在Script Command中使用扩展API组件或
```
@raycast/api
```
模式。
不要在未设置
```
refreshTime
```
的情况下选择
```
inline
```
模式。
不要为
```
compact
```
、
```
silent
```
或
```
inline
```
模式输出冗余的多行进度信息。
不要不安全地读取可选参数；保护Python的
```
sys.argv
```
访问和Shell的
```
$2
```
/
```
$3
```
使用。
不要隐藏缺失的依赖；记录依赖并清晰地提示失败信息。
除非命令需要用户编辑后才能使用，否则不要在文件名中保留
```
.template.
```
后缀。
当相关参考文档已涵盖所需模式时，不要在回复中添加通用Shell或Python教程内容。

Final check

最终检查

Before stopping, make sure the command would pass a practical smoke test:

visible metadata at the top
plausible mode
consistent argument count
readable success/failure output
no obvious mismatch between implementation language and task

结束前，请确保命令能通过实际的冒烟测试：

文件顶部有可见的元数据
模式合理
参数数量一致
成功/失败输出易读
实现语言与任务之间无明显不匹配