1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | clerk-cli（所属合集仓库自述名称为 “Clerk Skills”，故单列记录） | GitHub |
| 作者/维护者 | Clerk（身份认证 SaaS 平台，官方组织仓库） | GitHub API |
| 来源链接 | https://github.com/clerk/skills/tree/main/skills/core/clerk-cli | — |
| 许可证 | MIT（README 与 SKILL.md frontmatter 均明确声明，仓库根目录未附独立 LICENSE 文件） | GitHub API + 仓库核对 |
| GitHub Stars / Forks | 所属仓库 64★ / 4 forks（该数字属整个 20 个技能的合集，不代表本技能个体热度，仅供了解仓库规模） | GitHub API |
| 子技能自身证据 | 近 2 个月内由 3 位不同工程师（含仓库主要维护者）通过 4 次提交迭代，均关联具体 PR（如 #52、#57、#60） | GitHub API（按路径查询提交历史） |
| 最新版本 | 无独立语义化版本号；跟随 clerk CLI 二进制的 latest 版本 |
SKILL.md |
| 安装方式 | npx skills add clerk/skills、Codex 插件市场，或手动 git clone（见第 10 章） |
官方 README |
2. 功能介绍与亮点
clerk-cli 教会编码 agent 操作 Clerk 官方 CLI（clerk 二进制），把用户/组织/会话管理、身份模拟、本地 webhook 联调、部署校验、实例配置、环境变量拉取、功能开关等操作，统一封装成结构化命令，替代 agent 手写 curl 调 REST API。
主要亮点：
- 自带 OpenAPI 端点目录：
clerk api ls可动态发现 Backend/Platform API 全部端点，agent 不需要凭记忆猜路径 - 变更前置预览：所有写操作（
config patch/put、api -X POST/PATCH/DELETE）都要求先--dry-run预览，这是 agent 场景下唯一真正生效的安全阀 - Agent 模式与人类模式分离：CLI 会自动探测非交互环境，跳过交互式选择器，同时对“沙箱环境可能读不到系统密钥链/主目录状态”给出明确一次性告警
- 凭据走系统密钥链：
clerk auth login用 OAuth 登录后把 token 存进操作系统密钥链，不落地明文文件 - 对高风险操作坦诚披露：
clerk impersonate（身份模拟）文档明确写出“生产环境下会绕过用户 MFA，可能占用模拟配额，动手前请先与用户确认”，而不是把风险藏起来
3. 适用场景
固定分类：集成与工作流自动化
面向已经在项目中使用 Clerk 做身份认证、希望编码 agent 能直接完成用户排查、组织与计费开关、部署前校验、本地 webhook 联调等运维型操作的开发者——尤其是在生产环境处理“某个用户登录不了”“webhook 没触发”“这次部署 OAuth 配置对不对”这类需要直接查询/操作 Clerk 后台数据的场景，agent 用该 skill 调用官方 CLI 比手写 REST 调用更省心，也更不容易查错端点。
4. 跨 Agent 兼容性
- Claude Code：原生支持，仓库自带
.claude-plugin/marketplace.json，README 提供手动git clone到~/.claude/skills/clerk的独立安装路径 - Codex：原生支持，仓库自带
.codex-plugin/plugin.json，官方文档给出codex plugin marketplace add clerk/skills的专门安装步骤 - OpenClaw / Hermes Agent：未验证——官方材料只点名 Claude Code、Cursor、GitHub Copilot，未提及这两个平台，遵循“skills”开放规范理论上可手动安装，但缺乏官方确认
5. 推荐理由
这是身份认证赛道头部厂商官方维护、面向 AI 编码 agent 专门设计的运维工具封装：它把“agent 在沙箱里可能读不到密钥链/网络受限”这类容易踩坑的边界条件写得清清楚楚，把每一个有风险的操作（身份模拟、生产环境变更）都标注了后果而不是留给用户自己发现，这种对 agent 场景的针对性打磨在同类官方 CLI 封装里并不常见，能直接降低 agent 误操作身份认证后台的概率。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Clerk 官方为此发布过独立 changelog 公告与专门文档页，clerk-cli 自身有 3 位工程师跨两个月的持续提交与 PR 记录；但所属合集仓库整体星数（64★）规模不大，独立第三方讨论证据有限 |
| 可用性 | 9 | 三条安装路径均一步到位；文档详尽到逐条命令给出 agent 模式下的具体行为差异；近两个月持续维护；使用该 skill 本身免费，仅需一个可免费开通的 Clerk 账号 |
| 安全性 | 8 | 见下方安全检查清单 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | 执行官方 clerk 二进制，权限范围明确限定在 Clerk 自身账号数据（用户/组织/实例配置），非任意 shell |
| ② 运行时联网外发 | 调用 Clerk 官方 API（用户本就在使用的服务），传输目标透明；若选择 npx skills add 这一条安装路径，所依赖的第三方安装器另有未解决的遥测上传投诉（详见第 11 章） |
| ③ API Key/凭据存储 | OAuth token 存入操作系统密钥链，非明文落盘；env pull 写入的 .env.local 文档明确提示需加入 .gitignore、不得粘贴进代码或对话 |
| ④ 可疑指令 | 未发现提示注入或隐藏指令；文档反而主动披露高风险操作（如身份模拟会绕过生产环境 MFA）的后果 |
| ⑤ 作者/组织信誉 | Clerk 为知名身份认证 SaaS 厂商，官方组织账号，无造假迹象 |
| ⑥ License | MIT，README 与 SKILL.md 均明确声明 |
| ⑦ 最近维护 | 近两个月内有多次提交，含正在进行的 PR 式迭代 |
综合评分 = 三项均值 = 8.0
7. 跟同类 Skills 相比的优势
身份认证/后端即服务（BaaS）领域，同类可比的编码 agent 技能包括：
| Skill | 定位 | 与 clerk-cli 的差异 |
|---|---|---|
Auth0 Agent Skills（auth0/agent-skills） |
Auth0 官方出品，单一路由型 skill，覆盖 30 余种前后端框架的接入指导，并内置从 Firebase Auth/AWS Cognito/Supabase Auth/Clerk 等平台的迁移指南 | 定位互补而非重叠：Auth0 skill 教 agent 怎么把认证功能接入代码，clerk-cli 教 agent 怎么运维一个已在用的 Clerk 后台（查用户、切环境、验部署），后者更偏向线上排障与日常管理 |
Firebase Basics（firebase/agent-skills） |
Google 官方出品，聚焦 Firebase 项目初始化与认证配置的一条命令搭建 | 覆盖阶段不同：Firebase Basics 偏“从零搭建”，clerk-cli 偏“已上线后的持续运维”，两者都不含对方产品线的运维能力 |
Supabase 系列 skills（supabase/agent-skills） |
覆盖 Supabase 全平台（数据库+认证+存储等）的 agent 技能 | Supabase 的认证只是其全平台能力的一部分，而 clerk-cli 是身份认证这一单点的深度运维工具，命令覆盖度（用户/组织/会话/部署校验/webhook 联调）在纯认证场景下更细 |
8. 用户评价
该技能所属的 Clerk Skills 合集目前在第三方 AI Skill 目录站（如 explainx.ai、skillscout.sh）有收录条目，但均为目录聚合展示，尚无独立于官方渠道的具名用户评价可供引用。
9. 其他补充
clerk-cli 是 Clerk Skills 合集中 20 个技能之一，合集内还含框架专属模式（Next.js/React/Vue/Nuxt/Astro/TanStack/Chrome Extension）、功能专属技能（组织/计费/webhook/测试）与原生移动端技能（Swift/Android/Expo），需要对应能力时可在同一仓库内按需取用。
10. 安装使用方式
方式一（推荐，Claude Code 手动安装，不依赖第三方安装脚本）：
git clone https://github.com/clerk/skills ~/.claude/skills/clerk方式二（Codex）：
codex plugin marketplace add clerk/skills添加市场后重启 Codex，打开 /plugins，选择 Clerk Skills 安装并启用 clerk-skills，再开始新会话。
方式三（Agent Skills 通用安装器）：
npx skills add clerk/skills安装后注意事项：
- 使用前需在 Clerk Dashboard 获取 API Key，并在项目中配置
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY、CLERK_SECRET_KEY - 首次使用建议先执行
clerk doctor --json做健康检查，确认 CLI 已登录、项目已关联 - 涉及主目录/密钥链/网络访问的命令（登录、关联项目、拉取环境变量等）应在宿主终端而非沙箱环境中执行，CLI 会在检测到沙箱限制时给出告警
11. 注意事项
- 身份模拟需人工确认：
clerk impersonate在生产环境会绕过目标用户的 MFA，且可能占用模拟配额，动手前应与用户当面确认，不建议 agent 自主触发 - agent 模式下确认门槛降低：除
unlink外，其余写操作在 agent 模式下不会等待交互确认，--yes参数实际不改变行为，唯一有效的安全网是先--dry-run预览 - 第三方安装器的已知问题：若选择
npx skills add这条安装路径，其底层依赖的通用安装 CLI（vercel-labs/skills）当前存在两个未解决的社区投诉——安装时可能在未明确告知的情况下上传使用遥测数据。选择本报告方式一（手动git clone）或方式二（Codex 插件市场）可完全绕开这一层 - 跨 Agent 支持范围有限：官方仅确认 Claude Code、Cursor、GitHub Copilot 与 Codex，OpenClaw、Hermes Agent 用户需自行验证兼容性