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.
Files changed (65) hide show
  1. {skm_cli-0.3.0 → skm_cli-0.4.0}/AGENTS.md +15 -7
  2. {skm_cli-0.3.0 → skm_cli-0.4.0}/PKG-INFO +28 -12
  3. {skm_cli-0.3.0 → skm_cli-0.4.0}/README.md +27 -11
  4. skm_cli-0.4.0/kb/known-issues.md +22 -0
  5. skm_cli-0.4.0/kb/plans/2026-10-28-agent-override.md +346 -0
  6. skm_cli-0.4.0/kb/sessions/2026-10-28-agent-override.md +50 -0
  7. skm_cli-0.4.0/kb/sessions/2026-10-29-agent-override-review-and-fixes.md +62 -0
  8. skm_cli-0.4.0/kb/sessions/2026-10-29-skm-ovfix-alias.md +65 -0
  9. skm_cli-0.4.0/kb/sessions/2026-10-29-skm-ovfix-decline.md +51 -0
  10. skm_cli-0.4.0/kb/sessions/2026-10-29-skm-ovfix-home.md +34 -0
  11. skm_cli-0.4.0/kb/sessions/2026-10-29-skm-ovfix-relpath.md +45 -0
  12. {skm_cli-0.3.0 → skm_cli-0.4.0}/pyproject.toml +1 -1
  13. skm_cli-0.4.0/src/skm/agents.py +30 -0
  14. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/cli.py +40 -42
  15. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/install.py +126 -48
  16. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/list_cmd.py +14 -15
  17. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/update.py +22 -8
  18. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/linker.py +13 -12
  19. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/types.py +50 -51
  20. skm_cli-0.4.0/src/skm/utils.py +26 -0
  21. skm_cli-0.4.0/tests/test_agent_override.py +384 -0
  22. skm_cli-0.4.0/tests/test_agents.py +55 -0
  23. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_cli_e2e.py +1 -1
  24. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_config.py +17 -1
  25. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_install.py +30 -11
  26. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_linker.py +18 -17
  27. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_list_cmd.py +6 -10
  28. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_local_path.py +6 -5
  29. skm_cli-0.4.0/tests/test_utils.py +21 -0
  30. {skm_cli-0.3.0 → skm_cli-0.4.0}/uv.lock +1 -1
  31. skm_cli-0.3.0/kb/known-issues.md +0 -15
  32. skm_cli-0.3.0/src/skm/utils.py +0 -9
  33. {skm_cli-0.3.0 → skm_cli-0.4.0}/.gitignore +0 -0
  34. {skm_cli-0.3.0 → skm_cli-0.4.0}/draft.md +0 -0
  35. {skm_cli-0.3.0 → skm_cli-0.4.0}/images/skm-install.png +0 -0
  36. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/notes/2026-10-23-github-pr-requirements-research.md +0 -0
  37. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/plans/2026-03-09-skm-skill-manager.md +0 -0
  38. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/plans/2026-09-04-sparse-checkout-clone.md +0 -0
  39. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-09-refactor-config-structure.md +0 -0
  40. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-add-local-path-support.md +0 -0
  41. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-extend-skm-install-direct-source.md +0 -0
  42. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-handle-existing-skill-dir-override.md +0 -0
  43. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-implement-skm-view-command.md +0 -0
  44. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-03-10-install-idempotent-sync.md +0 -0
  45. {skm_cli-0.3.0 → skm_cli-0.4.0}/kb/sessions/2026-09-04-sparse-checkout-clone.md +0 -0
  46. {skm_cli-0.3.0 → skm_cli-0.4.0}/link-skill +0 -0
  47. {skm_cli-0.3.0 → skm_cli-0.4.0}/skills.example.yaml +0 -0
  48. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/__init__.py +0 -0
  49. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/clonefile.py +0 -0
  50. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/__init__.py +0 -0
  51. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/check_updates.py +0 -0
  52. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/remove.py +0 -0
  53. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/commands/view.py +0 -0
  54. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/config.py +0 -0
  55. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/detect.py +0 -0
  56. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/git.py +0 -0
  57. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/lock.py +0 -0
  58. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/py.typed +0 -0
  59. {skm_cli-0.3.0 → skm_cli-0.4.0}/src/skm/tui.py +0 -0
  60. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_clonefile.py +0 -0
  61. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_detect.py +0 -0
  62. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_git.py +0 -0
  63. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_install_from_source.py +0 -0
  64. {skm_cli-0.3.0 → skm_cli-0.4.0}/tests/test_lock.py +0 -0
  65. {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 KNOWN_AGENTS are active (omit = all)
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 `KNOWN_AGENTS` are used as the base set. Per-package `agents.includes/excludes` then filters from that base set.
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 `KNOWN_AGENTS`:
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
- All agents get symlinks except `openclaw`, which `AGENT_OPTIONS` sets to `use_hardlink` because OpenClaw skips symlinks that resolve outside its skill roots. `standard` used hardlinks until 2026-10-23, since OpenClaw also reads `~/.agents/skills`. Codex (0.164) and Hermes (0.22) were tested and load symlinked skills there. In symlink mode `link_skill()` swaps a leftover materialized copy for a symlink when `_is_managed_materialized_dir()` says nothing in it differs from the source.
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 symlinks; creates subdirs per agent name (overrides `KNOWN_AGENTS` paths)
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.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
- Only links tracked in `skills-lock.yaml` are affected. Manually created files or skills installed by other tools in agent directories are never touched.
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
- Skills are symlinked into these directories by default:
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
- | Agent | Path |
155
- |---|---|
156
- | `standard` | `~/.agents/skills/` |
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
- When `use_hardlink: true` is set for an agent in `AGENT_OPTIONS`, skm creates hardlinks instead. 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**.
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
- use_hardlink enabled?
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
- Only links tracked in `skills-lock.yaml` are affected. Manually created files or skills installed by other tools in agent directories are never touched.
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
- Skills are symlinked into these directories by default:
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
- | Agent | Path |
144
- |---|---|
145
- | `standard` | `~/.agents/skills/` |
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
- When `use_hardlink: true` is set for an agent in `AGENT_OPTIONS`, skm creates hardlinks instead. 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**.
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
- use_hardlink enabled?
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
+ - 临时方式:使用绝对路径或 `~/...`。后续应先补相对源路径的失败测试,再在源路径解析时统一转为绝对路径。