audit-clerk-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clerk CLI Skill Audit

Clerk CLI Skill 审计

Cross-check

skills/core/clerk-cli/

in this repository against the actual Clerk CLI source and propose precise edits where the skill has drifted. The CLI is the source of truth; the skill is maintainer documentation that must track it.

This task needs a complete command inventory, not a quick grep pass. Build the source model first, then compare it to the skill's current claims.

将本仓库中的

skills/core/clerk-cli/

与实际的Clerk CLI源码进行交叉校验，针对skill出现偏差的地方提出精准修改建议。CLI是权威来源；skill是维护者文档，必须与CLI保持一致。

此任务需要完整的命令清单，而非简单的grep扫描。首先构建源码模型，再将其与skill当前的描述进行对比。

Inputs

输入

CLI source of truth: a

clerk/cli

checkout containing

packages/cli-core/src/commands/**

, plus

packages/cli-core/src/cli.ts

cli-program.ts

mode.ts

, and any referenced files in

packages/cli-core/src/lib/

Target skill:

skills/core/clerk-cli/SKILL.md

and

skills/core/clerk-cli/references/*.md

CLI权威来源：包含

packages/cli-core/src/commands/**

的

clerk/cli

检出代码，以及

packages/cli-core/src/cli.ts

、

cli-program.ts

、

mode.ts

和

packages/cli-core/src/lib/

中所有被引用的文件。

目标skill：

skills/core/clerk-cli/SKILL.md

和

skills/core/clerk-cli/references/*.md

。

Source Checkout Resolution

源码检出路径解析

Resolve the CLI source checkout in this order:

Use

--source <path>

when supplied. The path must contain

packages/cli-core/src/commands/

If the current repository itself contains
```
packages/cli-core/src/commands/
```
, use the current repository root.
If
```
CLERK_CLI_REPO
```
is set, use that path. Do not print the variable value if it contains sensitive path fragments.
In Conductor, look for exactly one sibling workspace matching
```
../cli/*/packages/cli-core/src/commands/
```
. If multiple match, ask which one to use.
If no checkout is available and network access is acceptable for the task, clone the public CLI repository into
```
.context/clerk-cli-source
```
:

mkdir -p .context
cd .context
git clone --depth 1 https://github.com/clerk/cli.git clerk-cli-source

If none of these work, stop and ask the user for a CLI source path. Do not audit against the installed

clerk

binary alone, because the binary may be stale and does not expose every source-level branch.

按以下顺序确定CLI源码检出路径：

如果提供了
```
--source <path>
```
参数，则使用该路径。该路径必须包含
```
packages/cli-core/src/commands/
```
。
如果当前仓库本身包含
```
packages/cli-core/src/commands/
```
，则使用当前仓库根目录。
如果已设置
```
CLERK_CLI_REPO
```
环境变量，则使用该路径。若变量值包含敏感路径片段，请勿打印。
在Conductor中，查找恰好一个匹配
```
../cli/*/packages/cli-core/src/commands/
```
的同级工作区。如果找到多个，询问用户使用哪一个。
如果没有可用的检出代码，且任务允许网络访问，则将公开的CLI仓库克隆到
```
.context/clerk-cli-source
```
：

mkdir -p .context
cd .context
git clone --depth 1 https://github.com/clerk/cli.git clerk-cli-source

如果以上方法都不适用，请停止操作并询问用户提供CLI源码路径。请勿仅针对已安装的

clerk

二进制文件进行审计，因为二进制文件可能已过时，且无法展示所有源码层面的分支。

Workflow

工作流程

1. Inventory the CLI

1. 梳理CLI命令清单

Walk

packages/cli-core/src/commands/

and build a structured inventory. For each top-level command and subcommand capture:

Full command path, such as
```
clerk config patch
```
or
```
clerk api ls
```
.
Purpose, from the command description or help string in source.
Flags, including short form, type, default, and destructive behavior.
Exit codes beyond the default if the command overrides them.
Agent-mode branches gated on
```
isAgentMode()
```
,
```
CLERK_MODE
```
, TTY detection, or related helpers.
Whether the command mutates remote state and needs
```
--dry-run
```
,
```
--yes
```
, or production-targeting guidance.

Read

packages/cli-core/src/commands/<name>/README.md

as secondary context only. Use those files to flag mocked or stubbed commands and to cross-check API endpoint claims in

references/recipes.md

. Do not propose copying command READMEs into this repository; they include internal implementation detail and would bloat the skill.

Also capture cross-cutting behavior:

Runner preference logic, including lockfile to package-runner mapping.
Auth, key resolution,
```
--app
```
, and
```
--instance
```
targeting.
```
doctor
```
checks and
```
--json
```
output shape.
Agent-mode behavior for prompts, JSON defaults, browser opening, OAuth callbacks, deploy handoff, and sandbox warnings.
```
clerk init --prompt
```
or equivalent handoff behavior if the skill mentions it.

Prefer reading source over running the binary. When runtime behavior is unclear, use tests under

packages/cli-core/src/**/*.test.ts

packages/cli-core/src/test/

as supporting evidence.

遍历

packages/cli-core/src/commands/

并构建结构化的命令清单。针对每个顶级命令和子命令，记录以下信息：

完整命令路径，例如
```
clerk config patch
```
或
```
clerk api ls
```
。
用途，取自源码中的命令描述或帮助字符串。
标志（Flags），包括短格式、类型、默认值和破坏性行为。
若命令覆盖了默认退出码，则记录非默认的退出码。
基于
```
isAgentMode()
```
、
```
CLERK_MODE
```
、TTY检测或相关助手函数的agent-mode分支逻辑。
命令是否会修改远程状态，以及是否需要
```
--dry-run
```
、
```
--yes
```
或面向生产环境的指导说明。

仅将

packages/cli-core/src/commands/<name>/README.md

作为辅助参考。使用这些文件标记模拟（mocked）或存根（stubbed）命令，并交叉校验

references/recipes.md

中关于API端点的描述。请勿提议将命令的README文件复制到本仓库；这些文件包含内部实现细节，会导致skill内容冗余。

同时记录通用行为：

运行器偏好逻辑，包括锁文件到包运行器的映射。
认证（Auth）、密钥解析、
```
--app
```
和
```
--instance
```
目标定位。
```
doctor
```
检查和
```
--json
```
输出格式。
Agent-mode下的提示、JSON默认值、浏览器打开、OAuth回调、部署交接和沙箱警告行为。
如果skill中提及，则记录
```
clerk init --prompt
```
或等效的交接行为。

优先阅读源码而非运行二进制文件。当运行时行为不明确时，使用

packages/cli-core/src/**/*.test.ts

或

packages/cli-core/src/test/

下的测试用例作为佐证。

2. Extract the Skill's Claims

2. 提取Skill的描述内容

Read

skills/core/clerk-cli/SKILL.md

and each file under

skills/core/clerk-cli/references/

. Extract every concrete claim:

Commands in the core command table and invocation guidance.
Flags named in prose, tables, and examples.
Agent-mode behavior bullets.
Exit code, error format, and JSON output claims.
Cross-references between
```
SKILL.md
```
and
```
references/*.md
```
.

读取

skills/core/clerk-cli/SKILL.md

和

skills/core/clerk-cli/references/

下的所有文件，提取每一项具体描述：

核心命令表中的命令和调用指导。
在正文、表格和示例中提及的标志。
Agent-mode行为的项目符号描述。
退出码、错误格式和JSON输出的描述。
```
SKILL.md
```
与
```
references/*.md
```
之间的交叉引用。

3. Diff Source Against Skill

3. 对比源码与Skill的差异

Produce a structured diff with four buckets:

Missing from skill: commands, subcommands, flags, or behaviors that exist in source but are not mentioned anywhere in the skill.
Stale in skill: claims in the skill that no longer match source, including renamed flags, changed defaults, removed commands, shifted exit codes, or reworked agent-mode branches.
Thin in skill: commands mentioned but under-specified relative to their real complexity or footgun surface.
Over-specified: details the skill encodes that
```
clerk <cmd> --help
```
, generated examples, or referenced files cover better.

For buckets 1 through 3, cite both the source file and line and the target skill location.

生成结构化差异报告，分为四类：

Skill中缺失的内容：源码中存在但skill未提及的命令、子命令、标志或行为。
Skill中过时的内容：skill中的描述与源码不符，包括重命名的标志、修改的默认值、已移除的命令、变更的退出码或重构的agent-mode分支。
Skill中描述不足的内容：已提及但相对于实际复杂度或风险点描述不够详细的命令。
Skill中过度描述的内容：
```
clerk <cmd> --help
```
、生成的示例或引用文件已能更好覆盖的细节，skill却额外进行了编码描述。

对于第1到第3类，需同时引用源码文件及行号，以及目标skill的位置。

4. Decide Placement

4. 确定修改内容的放置位置

Route changes by maintenance value:

Core loop, mental model, and safety stay in
```
SKILL.md
```
.
Per-command flag details, recipes, and edge cases belong in
```
references/recipes.md
```
or a new reference file.
Agent-mode branches belong in
```
references/agent-mode.md
```
;
```
SKILL.md
```
gets only a concise summary.
Auth, key resolution, and targeting belong in
```
references/auth.md
```
.

Prefer

clerk <command> --help

over duplicating generated help. Flags with destructive semantics, hidden interactions, or agent-mode divergence deserve skill coverage. Self-explanatory flags should usually be removed from prose and delegated to

--help

Treat skill shrinkage as a valid proposal when it reduces drift risk. The goal is an accurate, durable skill, not a larger one.

根据维护价值确定修改内容的放置位置：

核心流程、心智模型和安全相关内容保留在
```
SKILL.md
```
中。
每个命令的标志细节、使用示例和边缘情况应放在
```
references/recipes.md
```
或新的参考文件中。
Agent-mode分支逻辑放在
```
references/agent-mode.md
```
中；
```
SKILL.md
```
仅保留简洁的摘要。
认证、密钥解析和目标定位放在
```
references/auth.md
```
中。

优先使用

clerk <command> --help

而非重复生成的帮助内容。具有破坏性语义、隐藏交互或与agent-mode行为不一致的标志值得在skill中覆盖说明。自解释性的标志通常应从正文中移除，交由

--help

处理。

当缩减skill内容能降低偏差风险时，这是一个合理的提议。目标是打造准确、持久的skill，而非内容更庞大的skill。

5. Propose Edits

5. 提出修改建议

Emit a review-ready proposal. For each change include:

Path, such as

skills/core/clerk-cli/SKILL.md

skills/core/clerk-cli/references/agent-mode.md

Severity:
```
drift
```
,
```
gap
```
, or
```
polish
```
.

Why, with a source citation such as

packages/cli-core/src/commands/<cmd>/<file>.ts:<line>

Target location in this repository.
A unified diff when practical, otherwise a concise before and after block.

Group the proposal by target file. Do not rewrite accurate neighboring sections just because they are nearby.

生成可供审核的修改建议。每项修改需包含：

文件路径，例如

skills/core/clerk-cli/SKILL.md

或

skills/core/clerk-cli/references/agent-mode.md

。

严重程度：
```
drift
```
（偏差）、
```
gap
```
（缺失）或
```
polish
```
（优化）。

修改原因，并引用源码，例如

packages/cli-core/src/commands/<cmd>/<file>.ts:<line>

。

本仓库中的目标位置。
可行时提供统一差异（unified diff），否则提供简洁的修改前后对比块。

按目标文件分组整理修改建议。请勿仅因为相邻就重写内容准确的章节。

6. Apply or Hand Back

6. 应用修改或返回建议

Default behavior: present the proposal and stop for review.

If invoked with

--apply

, apply

drift

and

gap

edits directly, then list

polish

suggestions for review. After applying edits, run available formatting or validation commands for this repository. If no formatter exists, validate Markdown and JSON structure with lightweight checks.

默认行为：展示修改建议并等待审核。

如果使用

--apply

参数调用，则直接应用

drift

和

gap

类修改，然后列出

polish

类建议供审核。应用修改后，运行本仓库可用的格式化或验证命令。如果没有格式化工具，则通过轻量检查验证Markdown和JSON结构。

Guardrails

约束规则

Never invent flags. If a flag appears in tests but not in the command parser, mark it for human review.
Preserve the existing
```
clerk-cli
```
skill's terse, third-person voice.
Do not use em dashes in proposals or edits.
Keep
```
skills/core/clerk-cli/SKILL.md
```
near the 500-line guidance. Move detailed material to
```
references/
```
instead of bloating the main skill.
Do not treat the installed
```
clerk
```
binary as authoritative over source. Use
```
--help
```
only to confirm generated presentation when source and tests leave ambiguity.
Do not commit or print secrets. If the audit touches env guidance, preserve the repository's 1Password and no-plaintext-secret rules.

切勿凭空创造标志。如果某个标志仅出现在测试中而未在命令解析器中定义，标记出来供人工审核。
保留现有
```
clerk-cli
```
skill简洁的第三人称语气。
在修改建议或编辑内容中请勿使用破折号。
保持
```
skills/core/clerk-cli/SKILL.md
```
的内容接近500行的指导规模。将详细内容移至
```
references/
```
目录，避免主skill内容冗余。
切勿将已安装的
```
clerk
```
二进制文件视为比源码更权威的来源。仅当源码和测试存在歧义时，使用
```
--help
```
确认生成的展示内容。
切勿提交或打印机密信息。如果审计涉及环境配置指导，请遵守仓库的1Password和明文机密禁止规则。

Output Shape

输出格式

Return the proposal as:

markdown

undefined

按以下格式返回修改建议：

markdown

undefined

clerk-cli skill audit - <YYYY-MM-DD>

Summary

skills/core/clerk-cli/SKILL.md

<section name>

[drift|gap|polish] <one-line description>
- source: packages/cli-core/src/commands/<...>:<line>
- target: skills/core/clerk-cli/SKILL.md:<line>
- change: <diff or concise before/after>

[drift|gap|polish] <one-line description>
- source: packages/cli-core/src/commands/<...>:<line>
- target: skills/core/clerk-cli/SKILL.md:<line>
- change: <diff or concise before/after>

skills/core/clerk-cli/references/<file>.md

...

New files

...

Open questions

...


Keep the result skimmable so a maintainer can approve, reject, or apply each entry independently.

...


保持结果易于浏览，以便维护者可以独立批准、拒绝或应用每一项修改建议。