Skip to content

Commit c031274

Browse files
Patrick-ErichsenPatrick-Erichsen
authored
feat: support git and local skill installs (#84793)
1 parent a30ac3f commit c031274

10 files changed

Lines changed: 994 additions & 41 deletions

File tree

‎docs/cli/skills.md‎

Lines changed: 29 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,15 @@
22
summary: "CLI reference for `openclaw skills` (search/install/update/list/info/check)"
33
read_when:
44
- You want to see which skills are available and ready to run
5-
- You want to search, install, or update skills from ClawHub
5+
- You want to search ClawHub or install skills from ClawHub, Git, or local directories
66
- You want to debug missing binaries/env/config for skills
77
title: "Skills"
88
---
99

1010
# `openclaw skills`
1111

12-
Inspect local skills and install/update skills from ClawHub.
12+
Inspect local skills, search ClawHub, install skills from ClawHub/Git/local directories, and update
13+
ClawHub-tracked installs.
1314

1415
Related:
1516

@@ -24,6 +25,9 @@ openclaw skills search "calendar"
2425
openclaw skills search --limit 20 --json
2526
openclaw skills install <slug>
2627
openclaw skills install <slug> --version <version>
28+
openclaw skills install git:owner/repo
29+
openclaw skills install git:owner/repo@main
30+
openclaw skills install ./path/to/skill --as custom-name
2731
openclaw skills install <slug> --force
2832
openclaw skills install <slug> --agent <id>
2933
openclaw skills install <slug> --global
@@ -45,23 +49,36 @@ openclaw skills check --agent <id>
4549
openclaw skills check --json
4650
```
4751

48-
`search`/`install`/`update` use ClawHub directly. By default, `install` and
49-
`update` target the active workspace `skills/` directory; with `--global`, they
50-
target the shared managed skills directory. `list`/`info`/`check` still inspect
51-
the local skills visible to the current workspace and config. Workspace-backed
52-
commands resolve the target workspace from `--agent <id>`, then the current
53-
working directory when it is inside a configured agent workspace, then the
54-
default agent.
52+
`search` and `update` use ClawHub directly. `install <slug>` installs a ClawHub
53+
skill, `install git:owner/repo[@ref]` clones a Git skill, and `install ./path`
54+
copies a local skill directory. By default, `install` and `update` target the
55+
active workspace `skills/` directory; with `--global`, they target the shared
56+
managed skills directory. `list`/`info`/`check` still inspect the local skills
57+
visible to the current workspace and config. Workspace-backed commands resolve
58+
the target workspace from `--agent <id>`, then the current working directory
59+
when it is inside a configured agent workspace, then the default agent.
5560

56-
This CLI `install` command downloads skill folders from ClawHub. Gateway-backed
57-
skill dependency installs triggered from onboarding or Skills settings use the
58-
separate `skills.install` request path instead.
61+
Git and local directory installs expect `SKILL.md` at the source root. The
62+
install slug comes from `SKILL.md` frontmatter `name` when it is valid, then the
63+
source directory or repository name; use `--as <slug>` to override it. `--version`
64+
is ClawHub-only. Skill installs do not support npm package specs or zip/archive
65+
paths, and `openclaw skills update` updates ClawHub-tracked installs only.
66+
67+
Gateway-backed skill dependency installs triggered from onboarding or Skills
68+
settings use the separate `skills.install` request path instead.
5969

6070
Notes:
6171

6272
- `search [query...]` accepts an optional query; omit it to browse the default
6373
ClawHub search feed.
6474
- `search --limit <n>` caps returned results.
75+
- `install git:owner/repo[@ref]` installs a Git skill. Branch refs may contain
76+
slashes, such as `git:owner/repo@feature/foo`.
77+
- `install ./path/to/skill` installs a local directory whose root contains
78+
`SKILL.md`.
79+
- `install --as <slug>` overrides the inferred slug for Git and local directory
80+
installs.
81+
- `install --version <version>` applies only to ClawHub skill slugs.
6582
- `install --force` overwrites an existing workspace skill folder for the same
6683
slug.
6784
- `--global` targets the shared managed skills directory and cannot be combined

‎docs/tools/skills.md‎

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -130,14 +130,16 @@ Use native `openclaw skills` commands for discover/install/update, or the
130130
separate `clawhub` CLI for publish/sync workflows. Full guide:
131131
[ClawHub](/clawhub).
132132

133-
| Action | Command |
134-
| -------------------------------------- | ----------------------------------------------- |
135-
| Install a skill into the workspace | `openclaw skills install <skill-slug>` |
136-
| Install a skill for all local agents | `openclaw skills install <skill-slug> --global` |
137-
| Update all workspace-installed skills | `openclaw skills update --all` |
138-
| Update a single shared managed skill | `openclaw skills update <skill-slug> --global` |
139-
| Update all shared managed/local skills | `openclaw skills update --all --global` |
140-
| Sync (scan + publish updates) | `clawhub sync --all` |
133+
| Action | Command |
134+
| -------------------------------------- | ------------------------------------------------------ |
135+
| Install a ClawHub skill into workspace | `openclaw skills install <skill-slug>` |
136+
| Install a Git skill into workspace | `openclaw skills install git:owner/repo@ref` |
137+
| Install a local skill into workspace | `openclaw skills install ./path/to/skill --as my-tool` |
138+
| Install a skill for all local agents | `openclaw skills install <skill-slug> --global` |
139+
| Update all workspace-installed skills | `openclaw skills update --all` |
140+
| Update a single shared managed skill | `openclaw skills update <skill-slug> --global` |
141+
| Update all shared managed/local skills | `openclaw skills update --all --global` |
142+
| Sync (scan + publish updates) | `clawhub sync --all` |
141143

142144
Native `openclaw skills install` installs into the active workspace
143145
`skills/` directory by default. Add `--global` to install into the shared
@@ -150,6 +152,14 @@ Configured skill roots also support one grouping level, such as
150152
`skills/<group>/<skill>/SKILL.md`, so related third-party skills can be
151153
kept under a shared folder without broad recursive scanning.
152154

155+
Git and local directory installs expect a `SKILL.md` at the source root. The
156+
install slug comes from `SKILL.md` frontmatter `name` when it is a valid slug,
157+
then falls back to the source directory or repository name. Use `--as <slug>` to
158+
override the inferred slug. `--version` applies only to ClawHub installs. Skill
159+
installs do not support npm package specs or zip/archive paths. `openclaw skills
160+
update` updates ClawHub-tracked installs only; reinstall Git or local sources to
161+
refresh them.
162+
153163
Gateway clients that need private, non-ClawHub delivery can stage a zip skill
154164
archive with `skills.upload.begin`, `skills.upload.chunk`, and
155165
`skills.upload.commit`, then install the committed upload with
@@ -183,7 +193,11 @@ Prefer sandboxed runs for untrusted inputs and risky tools. See
183193
`skills.install.allowUploadedArchives`; normal ClawHub installs do not require
184194
that setting.
185195
- Gateway-backed skill dependency installs (`skills.install`, onboarding, and the Skills settings UI) run the built-in dangerous-code scanner before executing installer metadata. `critical` findings block by default unless the caller explicitly sets the dangerous override; suspicious findings still warn only.
186-
- `openclaw skills install <slug>` is different — it downloads a ClawHub skill folder into the workspace, or into shared managed/local skills with `--global`, and does not use the installer-metadata path above.
196+
- `openclaw skills install <slug>` is different — it downloads a ClawHub skill
197+
folder into the workspace, or into shared managed/local skills with
198+
`--global`, and does not use the installer-metadata path above. Git and local
199+
directory installs copy a trusted `SKILL.md` directory into the same skills
200+
root, but are not tracked by `openclaw skills update`.
187201
- `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the **host** process for that agent turn (not the sandbox). Keep secrets out of prompts and logs.
188202

189203
For a broader threat model and checklists, see [Security](/gateway/security).

‎src/agents/skills-clawhub.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -401,3 +401,13 @@ export async function readTrackedClawHubSkillSlugs(workspaceDir: string): Promis
401401
const lock = await readClawHubSkillsLockfile(workspaceDir);
402402
return Object.keys(lock.skills).toSorted();
403403
}
404+
405+
export async function untrackClawHubSkill(workspaceDir: string, slug: string): Promise<void> {
406+
const trackedSlug = normalizeTrackedSkillSlug(slug);
407+
const lock = await readClawHubSkillsLockfile(workspaceDir);
408+
if (!lock.skills[trackedSlug]) {
409+
return;
410+
}
411+
delete lock.skills[trackedSlug];
412+
await writeClawHubSkillsLockfile(workspaceDir, lock);
413+
}

0 commit comments

Comments
 (0)