AI Agent Skills 中文导航平台

Using the

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

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>
```
).

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.

Example: publishing

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.

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.

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.

sk

NPX Install

Tags

SKILL.md Content

Using the
`sk`
CLI

When to reach for this skill

Core workflow

Example: publishing
`sk`

Guardrails

Debug tips