skm-cli 0.3.0__tar.gz → 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {skm_cli-0.3.0 → skm_cli-0.4.0}/AGENTS.md +15 -7
- {skm_cli-0.3.0 → skm_cli-0.4.0}/PKG-INFO +28 -12
- {skm_cli-0.3.0 → skm_cli-0.4.0}/README.md +27 -11
- skm_cli-0.4.0/kb/known-issues.md +22 -0
- skm_cli-0.4.0/kb/plans/2026-10-28-agent-override.md +346 -0
- skm_cli-0.4.0/kb/sessions/2026-10-28-agent-override.md +50 -0
- skm_cli-0.4.0/kb/sessions/2026-10-29-agent-override-review-and-fixes.md +62 -0
- skm_cli-0.4.0/kb/sessions/2026-10-29-skm-ovfix-alias.md +65 -0
- skm_cli-0.4.0/kb/sessions/2026-10-29-skm-ovfix-decline.md +51 -0
- skm_cli-0.4.0/kb/sessions/2026-10-29-skm-ovfix-home.md +34 -0
- skm_cli-0.4.0/kb/sessions/2026-10-29-skm-ovfix-relpath.md +45 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/pyproject.toml +1 -1
- skm_cli-0.4.0/src/skm/agents.py +30 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/cli.py +40 -42
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/install.py +126 -48
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/list_cmd.py +14 -15
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/update.py +22 -8
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/linker.py +13 -12
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/types.py +50 -51
- skm_cli-0.4.0/src/skm/utils.py +26 -0
- skm_cli-0.4.0/tests/test_agent_override.py +384 -0
- skm_cli-0.4.0/tests/test_agents.py +55 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_cli_e2e.py +1 -1
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_config.py +17 -1
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_install.py +30 -11
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_linker.py +18 -17
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_list_cmd.py +6 -10
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_local_path.py +6 -5
- skm_cli-0.4.0/tests/test_utils.py +21 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/uv.lock +1 -1
- skm_cli-0.3.0/kb/known-issues.md +0 -15
- skm_cli-0.3.0/src/skm/utils.py +0 -9
- {skm_cli-0.3.0 → skm_cli-0.4.0}/.gitignore +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/draft.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/images/skm-install.png +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/notes/2026-10-23-github-pr-requirements-research.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/plans/2026-03-09-skm-skill-manager.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/plans/2026-09-04-sparse-checkout-clone.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-09-refactor-config-structure.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-add-local-path-support.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-extend-skm-install-direct-source.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-handle-existing-skill-dir-override.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-implement-skm-view-command.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-install-idempotent-sync.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-09-04-sparse-checkout-clone.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/link-skill +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/skills.example.yaml +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/__init__.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/clonefile.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/__init__.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/check_updates.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/remove.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/view.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/config.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/detect.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/git.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/lock.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/py.typed +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/tui.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_clonefile.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_detect.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_git.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_install_from_source.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_lock.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_types.py +0 -0
|
@@ -14,6 +14,7 @@ A CLI tool that manages AI agent skills by cloning GitHub repos, detecting skill
|
|
|
14
14
|
src/skm/
|
|
15
15
|
├── cli.py # Click CLI entry point (group + subcommands)
|
|
16
16
|
├── types.py # Pydantic data models + constants
|
|
17
|
+
├── agents.py # Runtime agent path/mode resolution shared by install, update, list
|
|
17
18
|
├── config.py # Load skills.yaml → SkmConfig
|
|
18
19
|
├── lock.py # Read/write skills-lock.yaml
|
|
19
20
|
├── detect.py # Walk cloned repos for SKILL.md files; select_skill_dirs() applies the same rules to a git tree listing
|
|
@@ -38,7 +39,7 @@ tests/
|
|
|
38
39
|
|
|
39
40
|
## Key Paths
|
|
40
41
|
|
|
41
|
-
- **Config:** `~/.config/skm/skills.yaml` — YAML dict with `packages` (repo list) and optional `agents.default`
|
|
42
|
+
- **Config:** `~/.config/skm/skills.yaml` — YAML dict with `packages` (repo list) and optional `agents.default` / `agents.override`
|
|
42
43
|
- **Lock:** `~/.config/skm/skills-lock.yaml` — tracks installed skills, commits, symlink paths
|
|
43
44
|
- **Store:** `~/.local/share/skm/skills/` — cloned repos cached here
|
|
44
45
|
- **Agent dirs:** Skills are symlinked into each agent's skill directory (e.g. `~/.claude/skills/`, `~/.codex/skills/`)
|
|
@@ -59,7 +60,7 @@ All git subprocess calls go through `run_cmd()` in `git.py`, which captures stdo
|
|
|
59
60
|
|
|
60
61
|
## Path Handling
|
|
61
62
|
|
|
62
|
-
Paths stored in `skills-lock.yaml` (e.g. `linked_to`) use `compact_path()` from `utils.py` to replace the home directory with `~`, avoiding exposure of usernames. When reading these paths back for filesystem operations, `Path.expanduser()` is used.
|
|
63
|
+
Paths stored in `skills-lock.yaml` (e.g. `linked_to`) use `compact_path()` from `utils.py` to replace the home directory with `~`, avoiding exposure of usernames. It only compacts at a path-separator boundary, so a sibling such as `/Users/x2/...` stays absolute (`~2/...` would make `expanduser()` raise). When reading these paths back for filesystem operations, `Path.expanduser()` is used.
|
|
63
64
|
|
|
64
65
|
## CLI Commands
|
|
65
66
|
|
|
@@ -74,9 +75,14 @@ Top-level YAML dict with `packages` and optional `agents`:
|
|
|
74
75
|
|
|
75
76
|
```yaml
|
|
76
77
|
agents:
|
|
77
|
-
default: # optional: select which
|
|
78
|
+
default: # optional: select which BUILTIN_AGENTS are active (omit = all)
|
|
78
79
|
- claude
|
|
79
80
|
- standard
|
|
81
|
+
override:
|
|
82
|
+
standard:
|
|
83
|
+
install_mode: materialize
|
|
84
|
+
claude:
|
|
85
|
+
path: ~/custom-claude/skills
|
|
80
86
|
|
|
81
87
|
packages:
|
|
82
88
|
- repo: https://github.com/vercel-labs/agent-skills
|
|
@@ -91,7 +97,7 @@ packages:
|
|
|
91
97
|
- repo: https://github.com/blader/humanizer # installs all detected skills to default agents
|
|
92
98
|
```
|
|
93
99
|
|
|
94
|
-
`agents.default` selects which agents from `
|
|
100
|
+
`agents.default` selects which agents from `BUILTIN_AGENTS` are used as the base set. Per-package `agents.includes/excludes` then filters from that base set.
|
|
95
101
|
|
|
96
102
|
## Skill Detection
|
|
97
103
|
|
|
@@ -105,14 +111,16 @@ During traversal, `.git` and directories whose names start with `_` are skipped.
|
|
|
105
111
|
|
|
106
112
|
## Known Agents
|
|
107
113
|
|
|
108
|
-
Defined in `src/skm/types.py` as `
|
|
114
|
+
Defined in `src/skm/types.py` as `BUILTIN_AGENTS`:
|
|
109
115
|
- `standard` → `~/.agents/skills`
|
|
110
116
|
- `claude` → `~/.claude/skills`
|
|
111
117
|
- `codex` → `~/.codex/skills`
|
|
112
118
|
- `openclaw` → `~/.openclaw/skills`
|
|
113
119
|
- `pi` → `~/.pi/agent/skills`
|
|
114
120
|
|
|
115
|
-
|
|
121
|
+
`BUILTIN_AGENTS` stores `AgentSpec` definitions; `agents.resolve_agents()` returns runtime `ResolvedAgent` paths and modes. Priority: `--agents-dir` → override path → non-empty agent environment variable (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PI_CODING_AGENT_DIR`, each with `/skills`) → built-in path. Only openclaw defaults to `materialize`; other agents default to `symlink`, and `agents.override` can change either field for built-in names only. `override.path` must be absolute or start with `~`; relative paths are rejected at config validation because cleanup would resolve them against whatever cwd the next command runs in.
|
|
122
|
+
|
|
123
|
+
Pass resolved agents into install/update/list; linker receives only the path and `install_mode`. List compares exact parent directories and falls back with a warning on unreadable config; normal list recognizes all built-ins, while `--all` scans defaults. Install, direct package reinstall, and updates with new commits clean tracked obsolete paths; unchanged updates retain old installs and lock paths. Cleanup never compares lock paths as plain strings only: an old path that is the same location as a new one (`utils.same_install_location`, same name and `samefile` parent) is kept, so symlinked or case-different agent dirs do not lose fresh installs. A target the user declined to overwrite is kept and dropped from the lock.
|
|
116
124
|
|
|
117
125
|
## Testing
|
|
118
126
|
|
|
@@ -149,7 +157,7 @@ skm --config /tmp/test.yaml \
|
|
|
149
157
|
- `--config` — path to `skills.yaml` (default: `~/.config/skm/skills.yaml`)
|
|
150
158
|
- `--lock` — path to `skills-lock.yaml` (default: `~/.config/skm/skills-lock.yaml`)
|
|
151
159
|
- `--store` — directory for cloned repos (default: `~/.local/share/skm/skills/`)
|
|
152
|
-
- `--agents-dir` — base directory for agent
|
|
160
|
+
- `--agents-dir` — base directory for agent installs; creates subdirs per agent name (overrides `BUILTIN_AGENTS` paths)
|
|
153
161
|
|
|
154
162
|
### E2E Test Helpers
|
|
155
163
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: skm-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
4
4
|
Summary: Skill Manager - manage agent skills from GitHub repos
|
|
5
5
|
Author-email: Reorx <novoreorx@gmail.com>
|
|
6
6
|
Requires-Python: >=3.12
|
|
@@ -93,6 +93,11 @@ agents:
|
|
|
93
93
|
default: # optional: select which agents are active (omit = all)
|
|
94
94
|
- claude
|
|
95
95
|
- standard
|
|
96
|
+
override: # optional: customize built-in agents
|
|
97
|
+
standard:
|
|
98
|
+
install_mode: materialize # symlink or materialize
|
|
99
|
+
claude:
|
|
100
|
+
path: ~/custom-claude/skills # complete skill directory
|
|
96
101
|
|
|
97
102
|
packages:
|
|
98
103
|
- repo: https://github.com/vercel-labs/agent-skills
|
|
@@ -126,6 +131,10 @@ Repo packages are cloned with a sparse checkout: skm runs `git clone --filter=bl
|
|
|
126
131
|
|
|
127
132
|
`skills` and `skills_excludes` are mutually exclusive. `skills` installs only the listed skills; `skills_excludes` installs all detected skills except the listed ones. Omitting both installs all detected skills.
|
|
128
133
|
|
|
134
|
+
`agents.default` selects the active agents; package `includes` / `excludes` only filter that set. Names in `includes` outside that set produce a warning and are ignored. Direct installation offers only the active agents; accepting all keeps the package following future changes to `agents.default`.
|
|
135
|
+
|
|
136
|
+
`agents.override` can change a built-in agent's `path`, `install_mode`, or both. Override paths must be absolute or start with `~` and expand to an absolute path. Omitted values retain their defaults. Unknown agents, empty or relative paths, invalid modes, and misspelled override fields are rejected before installation.
|
|
137
|
+
|
|
129
138
|
## Install Sync Behavior
|
|
130
139
|
|
|
131
140
|
`skm install` treats `skills.yaml` as a declarative state file. Each run syncs the agent directories to match the config:
|
|
@@ -134,7 +143,11 @@ Repo packages are cloned with a sparse checkout: skm runs `git clone --filter=bl
|
|
|
134
143
|
- **Removed skills** (dropped from a package's `skills:` list, or entire package removed) have their links deleted.
|
|
135
144
|
- **Agent config changes** (e.g. adding `excludes: [openclaw]`) remove links from excluded agents while keeping links in others.
|
|
136
145
|
|
|
137
|
-
|
|
146
|
+
Changing an override path moves tracked installs on the next `skm install`. Reinstalling a source also cleans up that source's old locations. `skm update` does this when it pulls a new commit; an already-current repo keeps its existing installs until the next `skm install`.
|
|
147
|
+
|
|
148
|
+
Only installation paths tracked in `skills-lock.yaml` are affected. Manually created files or skills installed by other tools in agent directories are never touched.
|
|
149
|
+
|
|
150
|
+
If you decline an overwrite during `skm install` or `skm install <source>`, that target is preserved and removed from lock tracking. Later cleanup leaves it alone.
|
|
138
151
|
|
|
139
152
|
## Skill Detection
|
|
140
153
|
|
|
@@ -149,14 +162,17 @@ If a package sets `skills_dir`, this default order is bypassed and only that dir
|
|
|
149
162
|
|
|
150
163
|
## Known Agents
|
|
151
164
|
|
|
152
|
-
|
|
165
|
+
| Agent | Default skill directory | Config-root environment variable | Default mode |
|
|
166
|
+
|---|---|---|---|
|
|
167
|
+
| `standard` | `~/.agents/skills/` | — | `symlink` |
|
|
168
|
+
| `claude` | `~/.claude/skills/` | `CLAUDE_CONFIG_DIR` | `symlink` |
|
|
169
|
+
| `codex` | `~/.codex/skills/` | `CODEX_HOME` | `symlink` |
|
|
170
|
+
| `openclaw` | `~/.openclaw/skills/` | — | `materialize` |
|
|
171
|
+
| `pi` | `~/.pi/agent/skills/` | `PI_CODING_AGENT_DIR` | `symlink` |
|
|
153
172
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
| `claude` | `~/.claude/skills/` |
|
|
158
|
-
| `codex` | `~/.codex/skills/` |
|
|
159
|
-
| `openclaw` | `~/.openclaw/skills/` |
|
|
173
|
+
Path priority: `--agents-dir` (`<dir>/<agent>`) → `agents.override.<agent>.path` → a non-empty environment variable (`<value>/skills`) → the built-in directory. Paths support `~`; override paths must be absolute or start with `~` and expand to an absolute path (for example, `~/custom-claude/skills`). Setting only `install_mode` leaves path selection unchanged.
|
|
174
|
+
|
|
175
|
+
`skm list` recognizes agents using these same directories, including agents outside `agents.default`; `skm list --all` scans only active agents. If the config cannot be read, list warns and uses the built-in agents (still honoring environment variables and `--agents-dir`).
|
|
160
176
|
|
|
161
177
|
## Copy Strategy
|
|
162
178
|
|
|
@@ -170,9 +186,9 @@ If the agent dir holds a copy that an older skm version materialized (every file
|
|
|
170
186
|
|
|
171
187
|
### 2. Hardlink
|
|
172
188
|
|
|
173
|
-
|
|
189
|
+
With `install_mode: materialize`, skm prefers hardlinks. Each file in the skill directory gets its own hardlink pointing to the same inode as the source. This only works when source and target are on the **same filesystem/device**.
|
|
174
190
|
|
|
175
|
-
Only `openclaw` uses this, because OpenClaw skips skill symlinks whose real path is outside its skill root. Hardlinks break when an editor saves a file by replacing it, and new or dot-prefixed files are not carried over, so the copy needs another `skm install` after the source changes.
|
|
191
|
+
Only `openclaw` uses this by default, because OpenClaw skips skill symlinks whose real path is outside its skill root. Hardlinks break when an editor saves a file by replacing it, and new or dot-prefixed files are not carried over, so the copy needs another `skm install` after the source changes.
|
|
176
192
|
|
|
177
193
|
### 3. Reflink (copy-on-write)
|
|
178
194
|
|
|
@@ -192,7 +208,7 @@ If reflink is not available (unsupported filesystem, non-Unix platform, etc.), s
|
|
|
192
208
|
### Selection flow
|
|
193
209
|
|
|
194
210
|
```
|
|
195
|
-
|
|
211
|
+
install_mode: materialize?
|
|
196
212
|
├── No → symlink
|
|
197
213
|
└── Yes → same device?
|
|
198
214
|
├── Yes → hardlink
|
|
@@ -82,6 +82,11 @@ agents:
|
|
|
82
82
|
default: # optional: select which agents are active (omit = all)
|
|
83
83
|
- claude
|
|
84
84
|
- standard
|
|
85
|
+
override: # optional: customize built-in agents
|
|
86
|
+
standard:
|
|
87
|
+
install_mode: materialize # symlink or materialize
|
|
88
|
+
claude:
|
|
89
|
+
path: ~/custom-claude/skills # complete skill directory
|
|
85
90
|
|
|
86
91
|
packages:
|
|
87
92
|
- repo: https://github.com/vercel-labs/agent-skills
|
|
@@ -115,6 +120,10 @@ Repo packages are cloned with a sparse checkout: skm runs `git clone --filter=bl
|
|
|
115
120
|
|
|
116
121
|
`skills` and `skills_excludes` are mutually exclusive. `skills` installs only the listed skills; `skills_excludes` installs all detected skills except the listed ones. Omitting both installs all detected skills.
|
|
117
122
|
|
|
123
|
+
`agents.default` selects the active agents; package `includes` / `excludes` only filter that set. Names in `includes` outside that set produce a warning and are ignored. Direct installation offers only the active agents; accepting all keeps the package following future changes to `agents.default`.
|
|
124
|
+
|
|
125
|
+
`agents.override` can change a built-in agent's `path`, `install_mode`, or both. Override paths must be absolute or start with `~` and expand to an absolute path. Omitted values retain their defaults. Unknown agents, empty or relative paths, invalid modes, and misspelled override fields are rejected before installation.
|
|
126
|
+
|
|
118
127
|
## Install Sync Behavior
|
|
119
128
|
|
|
120
129
|
`skm install` treats `skills.yaml` as a declarative state file. Each run syncs the agent directories to match the config:
|
|
@@ -123,7 +132,11 @@ Repo packages are cloned with a sparse checkout: skm runs `git clone --filter=bl
|
|
|
123
132
|
- **Removed skills** (dropped from a package's `skills:` list, or entire package removed) have their links deleted.
|
|
124
133
|
- **Agent config changes** (e.g. adding `excludes: [openclaw]`) remove links from excluded agents while keeping links in others.
|
|
125
134
|
|
|
126
|
-
|
|
135
|
+
Changing an override path moves tracked installs on the next `skm install`. Reinstalling a source also cleans up that source's old locations. `skm update` does this when it pulls a new commit; an already-current repo keeps its existing installs until the next `skm install`.
|
|
136
|
+
|
|
137
|
+
Only installation paths tracked in `skills-lock.yaml` are affected. Manually created files or skills installed by other tools in agent directories are never touched.
|
|
138
|
+
|
|
139
|
+
If you decline an overwrite during `skm install` or `skm install <source>`, that target is preserved and removed from lock tracking. Later cleanup leaves it alone.
|
|
127
140
|
|
|
128
141
|
## Skill Detection
|
|
129
142
|
|
|
@@ -138,14 +151,17 @@ If a package sets `skills_dir`, this default order is bypassed and only that dir
|
|
|
138
151
|
|
|
139
152
|
## Known Agents
|
|
140
153
|
|
|
141
|
-
|
|
154
|
+
| Agent | Default skill directory | Config-root environment variable | Default mode |
|
|
155
|
+
|---|---|---|---|
|
|
156
|
+
| `standard` | `~/.agents/skills/` | — | `symlink` |
|
|
157
|
+
| `claude` | `~/.claude/skills/` | `CLAUDE_CONFIG_DIR` | `symlink` |
|
|
158
|
+
| `codex` | `~/.codex/skills/` | `CODEX_HOME` | `symlink` |
|
|
159
|
+
| `openclaw` | `~/.openclaw/skills/` | — | `materialize` |
|
|
160
|
+
| `pi` | `~/.pi/agent/skills/` | `PI_CODING_AGENT_DIR` | `symlink` |
|
|
142
161
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
| `claude` | `~/.claude/skills/` |
|
|
147
|
-
| `codex` | `~/.codex/skills/` |
|
|
148
|
-
| `openclaw` | `~/.openclaw/skills/` |
|
|
162
|
+
Path priority: `--agents-dir` (`<dir>/<agent>`) → `agents.override.<agent>.path` → a non-empty environment variable (`<value>/skills`) → the built-in directory. Paths support `~`; override paths must be absolute or start with `~` and expand to an absolute path (for example, `~/custom-claude/skills`). Setting only `install_mode` leaves path selection unchanged.
|
|
163
|
+
|
|
164
|
+
`skm list` recognizes agents using these same directories, including agents outside `agents.default`; `skm list --all` scans only active agents. If the config cannot be read, list warns and uses the built-in agents (still honoring environment variables and `--agents-dir`).
|
|
149
165
|
|
|
150
166
|
## Copy Strategy
|
|
151
167
|
|
|
@@ -159,9 +175,9 @@ If the agent dir holds a copy that an older skm version materialized (every file
|
|
|
159
175
|
|
|
160
176
|
### 2. Hardlink
|
|
161
177
|
|
|
162
|
-
|
|
178
|
+
With `install_mode: materialize`, skm prefers hardlinks. Each file in the skill directory gets its own hardlink pointing to the same inode as the source. This only works when source and target are on the **same filesystem/device**.
|
|
163
179
|
|
|
164
|
-
Only `openclaw` uses this, because OpenClaw skips skill symlinks whose real path is outside its skill root. Hardlinks break when an editor saves a file by replacing it, and new or dot-prefixed files are not carried over, so the copy needs another `skm install` after the source changes.
|
|
180
|
+
Only `openclaw` uses this by default, because OpenClaw skips skill symlinks whose real path is outside its skill root. Hardlinks break when an editor saves a file by replacing it, and new or dot-prefixed files are not carried over, so the copy needs another `skm install` after the source changes.
|
|
165
181
|
|
|
166
182
|
### 3. Reflink (copy-on-write)
|
|
167
183
|
|
|
@@ -181,7 +197,7 @@ If reflink is not available (unsupported filesystem, non-Unix platform, etc.), s
|
|
|
181
197
|
### Selection flow
|
|
182
198
|
|
|
183
199
|
```
|
|
184
|
-
|
|
200
|
+
install_mode: materialize?
|
|
185
201
|
├── No → symlink
|
|
186
202
|
└── Yes → same device?
|
|
187
203
|
├── Yes → hardlink
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Known Issues
|
|
2
|
+
|
|
3
|
+
> 当前影响使用或稳定性、仍待处理的问题;解决后删除,处理结果写入 KB。
|
|
4
|
+
|
|
5
|
+
## openclaw:源文件被替换式保存后硬链副本变旧,install 卡在覆盖确认
|
|
6
|
+
|
|
7
|
+
- 记录:2026-10-23,standard 改为软链时确认 openclaw 仍走硬链(内置 `install_mode: materialize`)。
|
|
8
|
+
- 编辑器、agent 的 Edit 工具和 `sed -i` 保存时会换掉 inode,`~/.openclaw/skills` 里的副本还是旧内容,源里新增的文件和点开头的文件也不会带过去。之后 `skm install` 判定副本"不是受管副本",逐个询问是否覆盖;非终端环境下直接报错退出。只影响启用了 openclaw 的用户,本机目前没启用。
|
|
9
|
+
- 处理方向:OpenClaw 新版支持 `skills.load.allowSymlinkTargets`,配置 skm store 和 local_path 目录后也许可以改回软链,需要实测;或者把 lock 里记录过的副本直接当作受管副本刷新,前提是先确认副本里没有只存在于副本的改动。
|
|
10
|
+
|
|
11
|
+
## update:两个包提供同名 skill 时,清理会删掉另一个包正在用的安装
|
|
12
|
+
|
|
13
|
+
- 记录:2026-10-29,agent override 评审第 5 条;复现场景 `update_shared_path`(`tmp/2026-10-29-agent-override-review/repro.py`)。
|
|
14
|
+
- 仓库 A、B 都有 `demo`,后装的 B 占了 `codex/demo`。给 A 加 `excludes: [codex]`,A 有新提交后执行 `skm update`,B 的 `codex/demo` 被删,lock 仍记录 B 装在 codex,下次 `skm install` 才恢复。直接安装和全量 install 会保护其他包仍在用的路径,只有 `update.py` 的清理不会。
|
|
15
|
+
- 处理方向:update 清理时排除 lock 里其他条目的 `linked_to`,最好复用 `install.py` 的 `_remove_stale_links`。
|
|
16
|
+
|
|
17
|
+
## 相对 local_path:软链目标相对于安装目录,导致 skill 不可读
|
|
18
|
+
|
|
19
|
+
- 记录:2026-10-28,agent override 的隔离终端验收发现。
|
|
20
|
+
- `skm install tmp/.../source` 将相对路径原样写入 local_path 并作为软链目标,系统从 agent 安装目录解析该目标,导致 dangling symlink;CLI 仍然报告安装成功。已有 `cli.py` / `linker.py` 路径处理即如此,与 override 无关。
|
|
21
|
+
- 复现:`tmp/2026-10-28-agent-override/manual/`;初次安装后的 `readlink new-claude/override-demo` 返回 `tmp/2026-10-28-agent-override/manual/source`,从该目标目录无法访问源文件。把配置里的 local_path 改成绝对路径并重新 install 后文件可读。
|
|
22
|
+
- 临时方式:使用绝对路径或 `~/...`。后续应先补相对源路径的失败测试,再在源路径解析时统一转为绝对路径。
|