claude-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Headless Mode

Claude Code 无界面模式

Use this skill when the job should be executed through Claude Code itself, not solved inline. Focus on commands and workflows that match current stable Claude Code behavior.

当任务需要通过Claude Code本身执行而非在线解决时，使用此技能。重点关注与当前稳定版Claude Code行为匹配的命令和工作流。

Core Rules

核心规则

Treat
```
claude --help
```
on the target machine as the compatibility floor. CLI flags move faster than blog posts and copied examples.
Permission rule syntax varies by build. Anthropic docs often show forms like
```
Bash(git diff *)
```
, while the installed
```
claude 2.1.71
```
help on this machine still shows
```
Bash(git:*)
```
. Mirror the syntax shown by the target machine's
```
claude --help
```
.
Default to the model the user already configured through
```
/model
```
, settings, or
```
ANTHROPIC_MODEL
```
.
Do not add
```
--model
```
unless the user explicitly asked for a model override or the workflow must pin a model for reproducibility.
Prefer
```
--append-system-prompt
```
over
```
--system-prompt
```
unless replacing the default Claude Code behavior is intentional.
Default to safe automation. If the user wants a truly unattended run, use explicit permission rules or
```
dontAsk
```
; reserve
```
bypassPermissions
```
for isolated environments.

以目标机器上的
```
claude --help
```
作为兼容性基准。CLI标志的更新速度快于博客文章和复制的示例。
权限规则语法因版本而异。Anthropic文档通常展示
```
Bash(git diff *)
```
这类格式，但本机安装的
```
claude 2.1.71
```
帮助文档仍显示
```
Bash(git:*)
```
。请遵循目标机器
```
claude --help
```
中展示的语法。
默认使用用户已通过
```
/model
```
、设置或
```
ANTHROPIC_MODEL
```
环境变量配置的模型。
除非用户明确要求覆盖模型，或工作流必须固定模型以保证可复现性，否则不要添加
```
--model
```
参数。
除非有意替换Claude Code的默认行为，否则优先使用
```
--append-system-prompt
```
而非
```
--system-prompt
```
。
默认采用安全自动化方式。如果用户需要真正无人值守的运行，请使用明确的权限规则或
```
dontAsk
```
模式；仅在隔离环境中使用
```
bypassPermissions
```
模式。

Quick Verification

快速验证

Run these checks before giving advanced advice:

bash

claude --version
claude auth status --text
claude --help

If installation or updates look odd, use:

bash

claude doctor

在提供高级建议前，先运行以下检查：

bash

claude --version
claude auth status --text
claude --help

如果安装或更新出现异常，使用：

bash

claude doctor

Installation Guidance

安装指南

Anthropic's getting-started docs still show
```
npm install -g @anthropic-ai/claude-code
```
as the standard install path.
Newer builds may also support native installer flows and
```
claude install
```
.
If the user needs installation help, point them to the official Claude Code setup docs and verify the result with
```
claude doctor
```
rather than assuming one installer path is universal.

Anthropic的入门文档仍将
```
npm install -g @anthropic-ai/claude-code
```
作为标准安装路径。
新版本可能还支持原生安装程序流程和
```
claude install
```
命令。
如果用户需要安装帮助，请引导他们查看官方Claude Code设置文档，并通过
```
claude doctor
```
验证安装结果，而非假设某一种安装路径是通用的。

Headless Command Patterns

无界面命令模式

Basic Non-Interactive Run

基础非交互式运行

Use

-p

--print

for non-interactive execution:

bash

claude -p "summarize the repository architecture"

Add

--output-format json

when the caller needs machine-readable output:

bash

claude -p "review the auth layer for risks" --output-format json

使用

-p

--print

参数执行非交互式任务：

bash

claude -p "summarize the repository architecture"

当调用方需要机器可读输出时，添加

--output-format json

：

bash

claude -p "review the auth layer for risks" --output-format json

Model Selection

模型选择

Omit
```
--model
```
by default.
If the user explicitly wants a model override, use
```
claude --model <alias-or-name> ...
```
.
For persistent defaults, prefer settings (
```
model
```
) or
```
ANTHROPIC_MODEL
```
.
For third-party deployments, pin models via settings or environment variables instead of bolting
```
--model
```
onto every command example.

默认省略
```
--model
```
参数。
如果用户明确要求覆盖模型，使用
```
claude --model <别名或名称> ...
```
。
如需持久化默认设置，优先使用配置（
```
model
```
）或
```
ANTHROPIC_MODEL
```
环境变量。
对于第三方部署，通过设置或环境变量固定模型，而非在每个命令示例中都添加
```
--model
```
参数。

Permission Modes

权限模式

Claude Code supports these permission modes:

Mode	Use
`default`	Interactive exploration. Prompts on first use of write/bash-style tools.
`acceptEdits`	Recommended starting point for coding automation. Auto-accepts edits, but command execution can still prompt.
`plan`	Analysis only. No file changes or command execution.
`dontAsk`	Auto-denies anything not already approved by permission rules. Good for unattended-but-constrained runs.
`bypassPermissions`	Skips prompts entirely. Only for strong sandbox / container / VM isolation.

Important clarifications:

```
acceptEdits
```
is the skill's recommended default, not the CLI default.
If the user says "no prompts at all," prefer permission rules or
```
dontAsk
```
with explicit allow rules.
Only recommend
```
bypassPermissions
```
when the environment is already isolated and the user accepts the risk.
For read-only analysis, prefer
```
--tools
```
plus
```
default
```
or
```
plan
```
; do not reach for
```
bypassPermissions
```
just to suppress prompts.

Claude Code支持以下权限模式：

模式	用途
`default`	交互式探索。首次使用写入/类Bash工具时会提示确认。
`acceptEdits`	编码自动化的推荐起始模式。自动接受编辑，但命令执行仍可能触发提示。
`plan`	仅分析模式。不修改文件或执行命令。
`dontAsk`	自动拒绝所有未被权限规则预先批准的操作。适用于无人值守但受约束的运行场景。
`bypassPermissions`	完全跳过提示。仅适用于强隔离的沙箱/容器/VM环境。

重要说明：

```
acceptEdits
```
是本技能推荐的默认模式，而非CLI的默认模式。
如果用户要求“完全无提示”，优先使用权限规则或带有明确允许规则的
```
dontAsk
```
模式。
仅当环境已隔离且用户接受风险时，才推荐使用
```
bypassPermissions
```
模式。
对于只读分析，优先使用
```
--tools
```
搭配
```
default
```
或
```
plan
```
模式；不要仅为了抑制提示就使用
```
bypassPermissions
```
。

Tool Availability vs Permission Approval

工具可用性与权限批准

Do not mix these up:

```
--tools
```
restricts which built-in tools are available at all.
```
--allowedTools
```
pre-approves specific tools or tool rules so Claude does not prompt for them.
```
--disallowedTools
```
removes tools or rules from context.

Permission rules follow

Tool

Tool(specifier)

syntax.

Use wildcard rules when the command will include arguments:

Good:
```
Bash(git diff *)
```
Good:
```
Bash(npm run test *)
```
Risky for real use:
```
Bash(find)
```
because it matches only the exact literal command
```
find
```

If the local CLI help shows colon syntax such as

Bash(find:*)

, use that form on that machine. The important part is to allow an argument-aware rule rather than an exact literal command.

If the user wants Claude limited to a narrow tool family, you should usually use both

--tools

and

--allowedTools

--tools

defines the hard boundary,

--allowedTools

removes prompts inside that boundary.

请勿混淆这两个概念：

```
--tools
```
限制可用的内置工具范围。
```
--allowedTools
```
预先批准特定工具或工具规则，避免Claude触发提示。
```
--disallowedTools
```
从上下文移除指定工具或规则。

权限规则遵循

Tool

或

Tool(指定符)

语法。

当命令包含参数时，使用通配符规则：

推荐：
```
Bash(git diff *)
```
推荐：
```
Bash(npm run test *)
```
实际使用有风险：
```
Bash(find)
```
（仅匹配字面命令
```
find
```
）

如果本地CLI帮助文档显示

Bash(find:*)

这类冒号语法，请在该机器上使用此格式。关键是使用支持参数的规则，而非精确匹配字面命令。

如果用户希望将Claude限制在特定工具家族内，通常应同时使用

--tools

和

--allowedTools

：

--tools

定义硬边界，

--allowedTools

移除边界内操作的提示。

Output Formats

输出格式

```
text
```
: default human-readable output
```
json
```
: one final structured result
```
stream-json
```
: event stream for long-running automation

Do not promise a fixed JSON schema unless you have validated it on the target version. Prefer wording like "returns a final result object with response text, timing, and session metadata."

```
text
```
：默认的人类可读输出
```
json
```
：单个最终结构化结果
```
stream-json
```
：适用于长时间运行自动化的事件流

除非已在目标版本上验证过固定JSON Schema，否则不要承诺固定的JSON格式。建议使用类似“返回包含响应文本、计时信息和会话元数据的最终结果对象”的表述。

Commonly Safe Flags

常用安全标志

These are appropriate starting points on current stable builds:

```
--append-system-prompt
```
```
--allowedTools
```
```
--disallowedTools
```
```
--tools
```
```
--permission-mode
```
```
--output-format
```
```
--mcp-config
```
```
--continue
```
/
```
--resume
```
```
--settings
```
/
```
--setting-sources
```
```
--session-id
```
```
--add-dir
```
```
--max-budget-usd
```
```
--fallback-model
```
for print mode

以下是当前稳定版中适合作为起始选项的标志：

```
--append-system-prompt
```
```
--allowedTools
```
```
--disallowedTools
```
```
--tools
```
```
--permission-mode
```
```
--output-format
```
```
--mcp-config
```
```
--continue
```
/
```
--resume
```
```
--settings
```
/
```
--setting-sources
```
```
--session-id
```
```
--add-dir
```
```
--max-budget-usd
```
```
--fallback-model
```
（适用于打印模式）

Version-Sensitive Flags

版本敏感标志

Published docs sometimes mention flags that are absent from the installed binary on a given machine. Before emitting less-common flags, verify them with

claude --help

已发布的文档有时会提及当前安装版本中不存在的标志。在使用不常见的标志前，请通过

claude --help

验证其存在性。

Recommended Command Templates

Execution Workflow

执行工作流

Confirm the user wants Claude Code CLI rather than an inline answer.
Verify the installed CLI shape with
```
claude --help
```
if you plan to use uncommon flags.
Choose the least-permissive mode that still fits the task.
Build the command without
```
--model
```
unless the user explicitly asked for an override.
Restrict tools with
```
--tools
```
when safety or predictability matters.
Use
```
--allowedTools
```
for prompt-free approval of known-safe actions.
Return exact commands plus short caveats about assumptions and safety.

确认用户需要的是Claude Code CLI而非在线解答。
如果计划使用不常见的标志，先通过
```
claude --help
```
验证当前安装的CLI支持情况。
选择既能满足任务需求又权限最低的模式。
构建命令时默认不添加
```
--model
```
参数，除非用户明确要求覆盖模型。
当安全性或可预测性很重要时，使用
```
--tools
```
限制可用工具。
使用
```
--allowedTools
```
预先批准已知安全的操作，避免触发提示。
返回精确的命令或命令序列，并附上关于假设前提和安全注意事项的简短说明。

When To Pause

何时暂停操作

Pause only when one of these is materially unclear:

The user wants a specific model or provider behavior that requires pinning.
They asked for a fully unattended run in an environment that is not clearly sandboxed.
The workflow depends on a Claude Code feature that is not visible in
```
claude --help
```
.

Otherwise, proceed and give the best current command.

仅当以下情况存在明显不确定性时才暂停：

用户需要特定模型或供应商行为，必须固定模型版本。
用户要求在未明确沙箱化的环境中进行完全无人值守运行。
工作流依赖的Claude Code功能未在
```
claude --help
```
中显示。

否则，继续操作并提供当前最优的命令。

Final Response Expectations

最终响应要求

When using this skill, the output should usually include:

the exact command or command sequence
a one-line note that the configured Claude model is being used by default
any permission or isolation caveat
the resume command if the workflow is meant to continue later

使用本技能时，输出通常应包含：

精确的命令或命令序列
一行说明：默认使用已配置的Claude模型
任何权限或隔离相关的注意事项
如果工作流需要后续继续，提供恢复命令

References

参考资料

```
references/examples.md
```
for extended patterns

```
references/examples.md
```
包含扩展模式示例

claude-skill

Original

Translation

Claude Code Headless Mode

Claude Code 无界面模式

Core Rules

核心规则

Quick Verification

快速验证

Installation Guidance

安装指南

Headless Command Patterns

无界面命令模式

Basic Non-Interactive Run

基础非交互式运行

Model Selection

模型选择

Permission Modes

权限模式

Tool Availability vs Permission Approval

工具可用性与权限批准

Output Formats

输出格式

Commonly Safe Flags

常用安全标志

Version-Sensitive Flags

版本敏感标志

Recommended Command Templates

推荐命令模板

Read-Only Analysis

只读分析

Safe Edit Run

安全编辑运行

JSON Report

JSON报告

Resume a Session

恢复会话

Continue the Most Recent Session

继续最近的会话

Use MCP Tools

使用MCP工具

Fully Unattended Execution in an Isolated Environment

隔离环境中的完全无人值守执行

Execution Workflow

执行工作流

When To Pause

何时暂停操作

Final Response Expectations

最终响应要求

References

参考资料