sk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using the

sk

CLI

使用

sk

CLI

sk

is the repo-scoped Skills manager that installs, audits, and syncs Claude Skills listed in

skills.lock.json

. Treat it like Cargo for skills: installs live under

./skills

, while the cache stays in

~/.cache/sk/repos

sk

是仓库范围的Skills管理器，用于安装、审计和同步

skills.lock.json

中列出的Claude Skills。可以将其视为Skills领域的Cargo：安装的技能存放在

./skills

目录下，缓存则保存在

~/.cache/sk/repos

中。

When to reach for this skill

适用场景

You need to install or upgrade a skill from the canonical skills repo (
```
https://github.com/lambdamechanic/skills
```
).
You want to verify the working tree is clean (
```
sk doctor --status
```
,
```
sk doctor --summary
```
).
You are preparing to sync edits back to the upstream skills repository (
```
sk sync-back <install>
```
).

你需要从标准技能仓库（
```
https://github.com/lambdamechanic/skills
```
）安装或升级技能。
你想要验证工作树是否干净（
```
sk doctor --status
```
、
```
sk doctor --summary
```
）。
你准备将本地编辑同步回上游技能仓库（
```
sk sync-back <install>
```
）。

Core workflow

核心工作流程

Refresh the cache (optional but fast):
bash
```
target/debug/sk update
```

Install or upgrade a skill (alias keeps folder names stable):

bash

target/debug/sk install https://github.com/lambdamechanic/skills testing-patterns --alias testing
target/debug/sk upgrade testing

Audit local installs before landing work:

bash

target/debug/sk doctor --status --json   # detect dirty trees vs lockfile
target/debug/sk doctor --summary --json  # shows pending upgrades or cache drift

Sync edits upstream after modifying a skill under
```
./skills/<name>
```
:
bash
```
target/debug/sk sync-back <name> --message "Describe the change"
```
Once
```
sk config set default_repo <repo>
```
is configured,
```
sk sync-back <name>
```
automatically targets that repo, uses
```
<name>
```
for the skill-path, and generates
```
sk/sync/<name>/<timestamp>
```
branches so the quickstart
```
-m
```
flag is the only required argument. Supply
```
--repo
```
/
```
--skill-path
```
only when you need to override the defaults.
This creates a temp branch in the cached repo, copies your edited skill directory, commits, and pushes. On success
```
sk
```
runs
```
gh
```
for you: it auto-opens a PR, enables auto-merge when GitHub reports the branch is clean, and prints the PR URL (or a conflict warning) so you can follow up if automation gets blocked. If the GitHub CLI is missing or the repo isn’t reachable via GitHub, you’ll see a warning plus manual PR instructions and can run
```
gh pr create
```
yourself once available.
PR automation tips
- Run
```
gh auth status
```
  once per machine to ensure the GitHub CLI is logged in;
```
sk
```
  will reuse your credentials.
- Missing
```
rsync
```
  prints a warning and falls back to a recursive copy before committing; install
```
rsync
```
  to keep large skills fast.
- After the push, watch the terminal output:
  - ```
  Opened PR …
```
  (or
```
  Reusing PR …
```
  ) links to the branch that was just published.
- ```
Auto-merge armed…
```
    means GitHub will land it once checks pass; otherwise you’ll see
```
Auto-merge blocked…
```
    with a link to fix conflicts manually.
  - ```
  Auto-merge skipped…
```
  appears when checks can’t be armed (e.g., required approvals disabled); click through and finish by hand.
- When
```
gh
```
  is missing or unauthenticated you’ll see “Skipping PR automation …”; install/auth and rerun
```
sk sync-back
```
  to finish the upload.
- Automation currently uses GitHub’s standard
```
--merge
```
  strategy; if your repo enforces
```
--squash
```
  /
```
--rebase
```
  , turn off auto-merge in the UI and land it manually after review.
- If your PR output says
```
enablePullRequestAutoMerge
```
  , run
```
gh repo edit <owner>/<repo> --enable-auto-merge
```
  (or visit the repo’s Settings → General page) once to flip the toggle.
Publish a brand-new skill that doesn’t exist upstream yet:
bash
```
target/debug/sk sync-back <name> \
  --repo https://github.com/lambdamechanic/skills \
  --skill-path <subdir> \
  --message "Add <name> skill"
```
Provide
```
--repo
```
/
```
--skill-path
```
only if you need something other than the configured defaults.
```
sk
```
clones that repo, branches from the default tip (or your custom
```
--branch
```
), copies your local folder, pushes, and rewrites
```
skills.lock.json
```
with the exact commit SHA/digest so status checks stay clean. You will always see the temporary branch name in the CLI output, e.g.
```
Pushed branch 'sk/sync/<name>/<timestamp>' …
```
, even though that branch is meant to be merged and deleted once the upstream PR lands.

刷新缓存（可选但速度很快）：
bash
```
target/debug/sk update
```

安装或升级技能（别名可保持文件夹名称稳定）：

bash

target/debug/sk install https://github.com/lambdamechanic/skills testing-patterns --alias testing
target/debug/sk upgrade testing

在提交工作前审计本地安装：

bash

target/debug/sk doctor --status --json   # 检测工作树与lockfile是否不一致
target/debug/sk doctor --summary --json  # 显示待升级项或缓存偏移

修改
./skills/<name>
下的技能后同步到上游：
bash
```
target/debug/sk sync-back <name> --message "描述所做更改"
```
配置
```
sk config set default_repo <repo>
```
后，
```
sk sync-back <name>
```
会自动指向该仓库，使用
```
<name>
```
作为技能路径，并生成
```
sk/sync/<name>/<timestamp>
```
分支，因此快速启动时仅需提供必填的
```
-m
```
参数即可。仅当需要覆盖默认设置时，才需指定
```
--repo
```
/
```
--skill-path
```
。
此命令会在缓存仓库中创建一个临时分支，复制你编辑过的技能目录，提交并推送。成功后，
```
sk
```
会自动调用
```
gh
```
：它会自动打开一个PR，当GitHub报告分支干净时启用自动合并，并打印PR URL（或冲突警告），以便在自动化受阻时进行后续处理。如果缺少GitHub CLI或无法访问GitHub仓库，你会看到一条警告以及手动创建PR的说明，待条件满足后可自行运行
```
gh pr create
```
。
PR自动化技巧
- 每台机器上运行一次
```
gh auth status
```
  以确保GitHub CLI已登录；
```
sk
```
  会复用你的凭据。
- 若缺少
```
rsync
```
  ，会打印警告并在提交前回退到递归复制；安装
```
rsync
```
  可提升大型技能的同步速度。
- 推送完成后，关注终端输出：
  - ```
  Opened PR …
```
  （或
```
  Reusing PR …
```
  ）链接到刚刚发布的分支。
- ```
Auto-merge armed…
```
    表示GitHub会在检查通过后自动合并；否则你会看到
```
Auto-merge blocked…
```
    及手动解决冲突的链接。
  - ```
  Auto-merge skipped…
```
  出现在无法启用检查时（例如禁用了必需的审批）；点击链接手动完成合并。
- 若
```
gh
```
  缺失或未认证，你会看到“跳过PR自动化 …”的提示；安装/认证后重新运行
```
sk sync-back
```
  即可完成上传。
- 自动化目前使用GitHub标准的
```
--merge
```
  策略；若你的仓库强制使用
```
--squash
```
  /
```
--rebase
```
  ，请在UI中关闭自动合并，审核后手动合并。
- 若PR输出显示
```
enablePullRequestAutoMerge
```
  ，请运行一次
```
gh repo edit <owner>/<repo> --enable-auto-merge
```
  （或访问仓库的设置→常规页面）来开启该功能。
发布上游尚未存在的全新技能：
bash
```
target/debug/sk sync-back <name> \
  --repo https://github.com/lambdamechanic/skills \
  --skill-path <subdir> \
  --message "Add <name> skill"
```
仅当需要覆盖配置的默认值时，才需提供
```
--repo
```
/
```
--skill-path
```
。
```
sk
```
会克隆该仓库，从默认分支（或你指定的
```
--branch
```
）创建分支，复制本地文件夹，推送并使用确切的提交SHA/摘要重写
```
skills.lock.json
```
，确保状态检查保持正常。你总会在CLI输出中看到临时分支名称，例如
```
Pushed branch 'sk/sync/<name>/<timestamp>' …
```
，尽管该分支在上游PR合并后会被删除。

Example: publishing

sk

示例：发布

sk

bash

cd /path/to/sk-decisions
target/debug/sk sync-back sk \
  --repo https://github.com/lambdamechanic/skills \
  --skill-path sk \
  --branch sk/add-sk-skill-doc \
  --message "Add sk skill doc"

What happens:

```
sk
```
prints both the temporary branch name and the upstream repo it pushed to, so you can follow up on GitHub immediately.
The branch only needs to live long enough for you (or automation) to open a PR; the lockfile entry pins the pushed commit hash, so it’s safe to delete the branch once merged.
```
skills.lock.json
```
gains a new entry for
```
sk
```
with the push timestamp, digest, and commit ID; subsequent
```
sk doctor --status
```
runs stay green because the on-disk tree matches that digest.

bash

cd /path/to/sk-decisions
target/debug/sk sync-back sk \
  --repo https://github.com/lambdamechanic/skills \
  --skill-path sk \
  --branch sk/add-sk-skill-doc \
  --message "Add sk skill doc"

执行过程：

```
sk
```
会打印临时分支名称和推送的上游仓库，以便你立即在GitHub上跟进。
该分支只需存在到你（或自动化）打开PR即可；lockfile条目会固定推送的提交哈希，因此合并后删除分支是安全的。
```
skills.lock.json
```
会新增一个
```
sk
```
的条目，包含推送时间戳、摘要和提交ID；后续运行
```
sk doctor --status
```
会保持绿色，因为磁盘上的工作树与该摘要匹配。

Guardrails

注意事项

Always run
```
bd update
```
/
```
bd close
```
so
```
.beads/issues.jsonl
```
matches any skill changes.
Never edit
```
skills.lock.json
```
by hand. Let
```
sk install
```
,
```
sk upgrade
```
, or
```
sk remove
```
update it; commit the lockfile alongside the skill changes.
If
```
sk doctor --status
```
reports
```
dirty
```
, fix the local tree before running
```
sk upgrade
```
or
```
sk sync-back
```
to avoid partial syncs.
```
sk upgrade --all
```
skips skills with local edits and prints reminders to
```
sk sync-back <name>
```
; treat that as a temporary state and clean them up promptly so future upgrades stay automatic.
When creating a new skill, always specify the upstream repo/path so
```
sk
```
can register it and refresh the lockfile automatically.
Use
```
sk precommit
```
(once implemented) to block local-only sources such as
```
file://
```
entries.

始终运行
```
bd update
```
/
```
bd close
```
，确保
```
.beads/issues.jsonl
```
与技能的任何更改保持一致。
切勿手动编辑
```
skills.lock.json
```
。让
```
sk install
```
、
```
sk upgrade
```
或
```
sk remove
```
来更新它；提交技能更改时一并提交lockfile。
若
```
sk doctor --status
```
报告
```
dirty
```
，请在运行
```
sk upgrade
```
或
```
sk sync-back
```
前修复本地工作树，避免部分同步。
```
sk upgrade --all
```
会跳过有本地编辑的技能，并提醒运行
```
sk sync-back <name>
```
；将此视为临时状态并及时处理，以便未来的升级保持自动化。
创建新技能时，始终指定上游仓库/路径，以便
```
sk
```
能自动注册并刷新lockfile。
使用
```
sk precommit
```
（待实现）来阻止本地源（如
```
file://
```
条目）。

Debug tips

调试技巧

```
target/debug/sk doctor --apply
```
rebuilds missing installs or cache entries.
```
target/debug/sk where <name>
```
prints the absolute path of an installed skill and its cached repo clone.
Set
```
SK_TRACE=1
```
to surface extra logging when diagnosing cache fetches or rsync failures.

```
target/debug/sk doctor --apply
```
可重建缺失的安装或缓存条目。
```
target/debug/sk where <name>
```
会打印已安装技能的绝对路径及其缓存仓库克隆地址。
设置
```
SK_TRACE=1
```
可在诊断缓存获取或rsync失败时显示额外日志。

sk

Original

Translation

Using the
`sk`
CLI

使用
`sk`
CLI

When to reach for this skill

适用场景

Core workflow

核心工作流程

Example: publishing
`sk`

示例：发布
`sk`

Guardrails

注意事项

Debug tips

调试技巧

sk

Original

Translation

Using the sk CLI

使用sk CLI

When to reach for this skill

适用场景

Core workflow

核心工作流程

Example: publishing sk

示例：发布sk

Guardrails

注意事项

Debug tips

调试技巧

Using the
`sk`
CLI

使用
`sk`
CLI

Example: publishing
`sk`

示例：发布
`sk`