skm-cli 0.4.0__tar.gz → 0.5.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 (74) hide show
  1. {skm_cli-0.4.0 → skm_cli-0.5.0}/AGENTS.md +31 -2
  2. {skm_cli-0.4.0 → skm_cli-0.5.0}/PKG-INFO +84 -9
  3. {skm_cli-0.4.0 → skm_cli-0.5.0}/README.md +83 -8
  4. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/known-issues.md +15 -1
  5. skm_cli-0.5.0/kb/plans/2026-11-15-dynamic-skill.md +121 -0
  6. skm_cli-0.5.0/kb/sessions/2026-10-29-release-0.4.0.md +35 -0
  7. skm_cli-0.5.0/kb/sessions/2026-10-31-install-local-sources.md +50 -0
  8. skm_cli-0.5.0/kb/sessions/2026-11-15-dynamic-skill.md +50 -0
  9. skm_cli-0.5.0/kb/sessions/2026-11-19-install-noninteractive.md +45 -0
  10. skm_cli-0.5.0/kb/todo.md +5 -0
  11. {skm_cli-0.4.0 → skm_cli-0.5.0}/pyproject.toml +1 -1
  12. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/cli.py +207 -18
  13. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/commands/check_updates.py +4 -1
  14. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/commands/install.py +281 -142
  15. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/commands/list_cmd.py +5 -3
  16. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/commands/remove.py +29 -2
  17. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/commands/update.py +75 -7
  18. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/config.py +2 -0
  19. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/detect.py +7 -3
  20. skm_cli-0.5.0/src/skm/dynamic.py +81 -0
  21. skm_cli-0.5.0/src/skm/local_sources.py +92 -0
  22. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/tui.py +13 -0
  23. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/types.py +35 -4
  24. skm_cli-0.5.0/tests/test_dynamic.py +568 -0
  25. skm_cli-0.5.0/tests/test_local_sources.py +489 -0
  26. skm_cli-0.5.0/tests/test_noninteractive.py +244 -0
  27. {skm_cli-0.4.0 → skm_cli-0.5.0}/uv.lock +1 -1
  28. {skm_cli-0.4.0 → skm_cli-0.5.0}/.gitignore +0 -0
  29. {skm_cli-0.4.0 → skm_cli-0.5.0}/draft.md +0 -0
  30. {skm_cli-0.4.0 → skm_cli-0.5.0}/images/skm-install.png +0 -0
  31. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/notes/2026-10-23-github-pr-requirements-research.md +0 -0
  32. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/plans/2026-03-09-skm-skill-manager.md +0 -0
  33. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/plans/2026-09-04-sparse-checkout-clone.md +0 -0
  34. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/plans/2026-10-28-agent-override.md +0 -0
  35. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-03-09-refactor-config-structure.md +0 -0
  36. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-add-local-path-support.md +0 -0
  37. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-extend-skm-install-direct-source.md +0 -0
  38. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-handle-existing-skill-dir-override.md +0 -0
  39. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-implement-skm-view-command.md +0 -0
  40. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-install-idempotent-sync.md +0 -0
  41. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-09-04-sparse-checkout-clone.md +0 -0
  42. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-10-28-agent-override.md +0 -0
  43. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-10-29-agent-override-review-and-fixes.md +0 -0
  44. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-10-29-skm-ovfix-alias.md +0 -0
  45. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-10-29-skm-ovfix-decline.md +0 -0
  46. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-10-29-skm-ovfix-home.md +0 -0
  47. {skm_cli-0.4.0 → skm_cli-0.5.0}/kb/sessions/2026-10-29-skm-ovfix-relpath.md +0 -0
  48. {skm_cli-0.4.0 → skm_cli-0.5.0}/link-skill +0 -0
  49. {skm_cli-0.4.0 → skm_cli-0.5.0}/skills.example.yaml +0 -0
  50. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/__init__.py +0 -0
  51. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/agents.py +0 -0
  52. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/clonefile.py +0 -0
  53. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/commands/__init__.py +0 -0
  54. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/commands/view.py +0 -0
  55. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/git.py +0 -0
  56. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/linker.py +0 -0
  57. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/lock.py +0 -0
  58. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/py.typed +0 -0
  59. {skm_cli-0.4.0 → skm_cli-0.5.0}/src/skm/utils.py +0 -0
  60. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_agent_override.py +0 -0
  61. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_agents.py +0 -0
  62. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_cli_e2e.py +0 -0
  63. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_clonefile.py +0 -0
  64. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_config.py +0 -0
  65. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_detect.py +0 -0
  66. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_git.py +0 -0
  67. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_install.py +0 -0
  68. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_install_from_source.py +0 -0
  69. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_linker.py +0 -0
  70. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_list_cmd.py +0 -0
  71. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_local_path.py +0 -0
  72. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_lock.py +0 -0
  73. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_types.py +0 -0
  74. {skm_cli-0.4.0 → skm_cli-0.5.0}/tests/test_utils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  # SKM - Skill Manager
2
2
 
3
- A CLI tool that manages AI agent skills by cloning GitHub repos, detecting skills via `SKILL.md`, and symlinking them to agent directories based on a central YAML config.
3
+ A CLI tool that manages AI agent skills by cloning GitHub repos (or linking local dirs, or capturing a CLI's printed SKILL.md), detecting skills via `SKILL.md`, and symlinking them to agent directories based on a central YAML config.
4
4
 
5
5
  ## Tech Stack
6
6
 
@@ -21,6 +21,8 @@ src/skm/
21
21
  ├── git.py # Sparse clone (no-checkout + ls-tree + sparse-checkout), pull, fetch, commit SHA helpers (unified run_cmd error handling)
22
22
  ├── utils.py # Utility functions (compact_path)
23
23
  ├── linker.py # Symlink skills to agent dirs, resolve includes/excludes
24
+ ├── local_sources.py # Device-local sources: symlinks in <config dir>/local_sources/
25
+ ├── dynamic.py # source_cmd packages: run a shell command, validate its stdout as SKILL.md, write it under the store
24
26
  └── commands/
25
27
  ├── install.py # Clone repos, detect skills, link to agents, update lock
26
28
  ├── list_cmd.py # Print installed skills from lock file
@@ -34,6 +36,9 @@ tests/
34
36
  ├── test_git.py # Git operations (sparse clone command sequence, real local-repo sparse checkout, pull re-sparsing, clone failure handling)
35
37
  ├── test_linker.py # Symlink creation, agent filtering
36
38
  ├── test_install.py # Install command unit tests
39
+ ├── test_local_sources.py # `install --local`, local_sources scanning, remove of local-source skills
40
+ ├── test_dynamic.py # source_cmd packages across config, install, update, list, remove, check-updates, `install --cmd`
41
+ ├── test_noninteractive.py # `install -y` and prompts without a terminal (picker defaults, override answers No)
37
42
  └── test_cli_e2e.py # End-to-end CLI tests for all commands
38
43
  ```
39
44
 
@@ -41,7 +46,8 @@ tests/
41
46
 
42
47
  - **Config:** `~/.config/skm/skills.yaml` — YAML dict with `packages` (repo list) and optional `agents.default` / `agents.override`
43
48
  - **Lock:** `~/.config/skm/skills-lock.yaml` — tracks installed skills, commits, symlink paths
44
- - **Store:** `~/.local/share/skm/skills/` — cloned repos cached here
49
+ - **Local sources:** `~/.config/skm/local_sources/` — always `skills.yaml`'s parent dir (so `--config` isolates it too); holds a self-ignoring `.gitignore` (`*`)
50
+ - **Store:** `~/.local/share/skm/skills/` — cloned repos cached here; dynamic skills are generated into `_dynamic/<slug>-<hash8>/SKILL.md` inside it
45
51
  - **Agent dirs:** Skills are symlinked into each agent's skill directory (e.g. `~/.claude/skills/`, `~/.codex/skills/`)
46
52
 
47
53
  ## Architecture
@@ -65,10 +71,25 @@ Paths stored in `skills-lock.yaml` (e.g. `linked_to`) use `compact_path()` from
65
71
  ## CLI Commands
66
72
 
67
73
  - `skm install` — Sparse-clone repos (idempotent: skips pull if already cloned), detect skills, create symlinks, remove stale links, update lock. Treats `skills.yaml` as declarative state: removes links for skills dropped from config or agents changed by includes/excludes. Only removes links tracked in the lock file — manually created files in agent dirs are never touched.
74
+ - `skm install --local <dir>` — Symlink `<dir>` (resolved absolute) into `local_sources/` and install just that source; never writes `skills.yaml`. See Local Sources.
75
+ - `skm install --cmd "<cmd>"` — Run the command first and only then add a `source_cmd` package to `skills.yaml` and install it. See Dynamic Skills.
76
+ - `skm install <source>|--cmd ... -y` — Skip the skill/agent pickers and take their defaults (all skills, all default agents → no agents filter saved). Explicit `--agents-includes/excludes` still win. See Non-interactive Runs.
68
77
  - `skm list` — Show installed skills and their linked paths from lock file
69
78
  - `skm check-updates` — Fetch remotes, compare against locked commits, show changelog
70
79
  - `skm update <skill_name>` — Pull latest for a skill's repo, re-link, update lock
71
80
 
81
+ ## Local Sources
82
+
83
+ Lets one `skills.yaml` be shared across devices (config dir in git) while each device installs extra skills. Full `skm install` turns every usable entry into `SkillRepoConfig(local_path=<entry path>)` (all skills, default agents) and passes them via `run_install(local_sources=...)` — they must never be written to `skills.yaml`. Local sources win same-name conflicts: `install.LocalOverrides` maps each skill name to the owning local source (first entry name wins among local sources); every other package skips it and `run_install_package` drops other sources' lock entries for skills its local source takes over, so `update` never re-links an overridden skill. The lock's `local_path` is the entry path, not the resolved target, which is how `skm remove` recognises a local-source skill (`is_local_source_path`); remove only ever unlinks the entry, never its target.
84
+
85
+ ## Dynamic Skills
86
+
87
+ A `source_cmd:` package runs `sh -c <cmd>` (no stdin, cwd `~`, 60s timeout) and stores its stdout as one skill in `<store>/_dynamic/<slug>-<hash8>/`; the dir is keyed by the command string, so a changed command regenerates. Output is validated before anything is written: frontmatter `name` must match `^[A-Za-z0-9][A-Za-z0-9._-]*$` because it becomes a path in every agent dir. `install` runs the command only when nothing was generated yet and turns a failure into a warning that skips the package (shared configs on devices without the CLI); `update` always reruns it, fails loudly, rewrites `SKILL.md` in place (same inode, so hardlinked copies follow) and relinks only when the content changed. `check-updates` skips dynamic skills. Lock entries carry `source_cmd`; code that needs an entry's package uses `InstalledSkill.source`, never `repo or local_path`.
88
+
89
+ ## Non-interactive Runs
90
+
91
+ `tui.has_terminal()` (stdin is a TTY) gates every prompt. Without a terminal, `interactive_multi_select` returns its preselection (default: everything) and prints the choice in yellow, and `_confirm_override` answers No and points at `--force`; neither reads a key. The check lives inside the prompt functions, not in `cli.py`, so tests that monkeypatch `skm.cli.interactive_multi_select` or `_confirm_override` keep working under `CliRunner` (whose stdin is never a TTY). Never let a non-terminal default destroy anything: `-y` and the no-terminal path only pick defaults, they never imply `--force`.
92
+
72
93
  ## Config Format (skills.yaml)
73
94
 
74
95
  Top-level YAML dict with `packages` and optional `agents`:
@@ -95,6 +116,10 @@ packages:
95
116
  skills_excludes: # optional: install all skills EXCEPT these (mutually exclusive with skills)
96
117
  - team-squad
97
118
  - repo: https://github.com/blader/humanizer # installs all detected skills to default agents
119
+ - source_cmd: tinyhost skill # dynamic skill: the command's stdout is the SKILL.md
120
+ agents: # skills/skills_excludes/skills_dir/clone_strategy are rejected here
121
+ includes:
122
+ - claude
98
123
  ```
99
124
 
100
125
  `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.
@@ -193,3 +218,7 @@ uv run skm --help # run CLI
193
218
  ```
194
219
 
195
220
  Do not run formatters or style linters on the code.
221
+
222
+ ## Publishing
223
+
224
+ The PyPI package is `skm-cli`. Use `uv version --bump minor` (or the appropriate bump) to update both `pyproject.toml` and `uv.lock`; run the test suite and build with `uv build --out-dir tmp/<date>-release-<version>/dist`. Publish only that version's wheel and sdist with `uv publish <wheel> <sdist>` to avoid uploading old artifacts, then push the release commit and its `v<version>` tag.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: skm-cli
3
- Version: 0.4.0
3
+ Version: 0.5.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
@@ -11,7 +11,7 @@ Description-Content-Type: text/markdown
11
11
 
12
12
  # SKM - Skill Manager
13
13
 
14
- A CLI tool that manages **global** AI agent skills from GitHub repos or local directories. Clone repos or link local paths, detect skills via `SKILL.md`, and symlink them into agent directories — all driven by a single YAML config.
14
+ A CLI tool that manages **global** AI agent skills from GitHub repos, local directories, or CLIs that print their own skill. Clone repos or link local paths, detect skills via `SKILL.md`, and symlink them into agent directories — all driven by a single YAML config.
15
15
 
16
16
  > **Note:** skm manages skills at the user level (e.g. `~/.claude/skills/`), not at the project level. It is not intended for installing skills into project-scoped directories.
17
17
 
@@ -41,6 +41,7 @@ packages:
41
41
  - vercel-react-native-skills
42
42
  - repo: https://github.com/blader/humanizer
43
43
  - local_path: ~/Code/my-custom-skills # use a local directory instead of a git repo
44
+ - source_cmd: tinyhost skill # use the SKILL.md a CLI prints (see Dynamic skills)
44
45
  ```
45
46
 
46
47
  2. Run install (`skm i` for short):
@@ -49,7 +50,7 @@ packages:
49
50
  skm install
50
51
  ```
51
52
 
52
- Skills are cloned (or symlinked from local paths) into your agent directories (`~/.claude/skills/`, `~/.codex/skills/`, etc.).
53
+ Skills are cloned (or symlinked from local paths, or generated from a command's output) into your agent directories (`~/.claude/skills/`, `~/.codex/skills/`, etc.).
53
54
 
54
55
  ### Install from a source directly
55
56
 
@@ -65,24 +66,95 @@ skm install https://github.com/vercel-labs/agent-skills vercel-react-best-practi
65
66
  # Install from a local directory
66
67
  skm install ~/Code/my-custom-skills
67
68
 
69
+ # Install the skill a CLI prints to stdout (see Dynamic skills below)
70
+ skm install --cmd "tinyhost skill"
71
+
68
72
  # Skip interactive prompts with --agents-includes / --agents-excludes
69
73
  skm install https://github.com/blader/humanizer --agents-includes claude,codex
74
+
75
+ # Skip every prompt: all skills, default agents
76
+ skm install https://github.com/vercel-labs/agent-skills -y
70
77
  ```
71
78
 
72
79
  This detects available skills, lets you pick which ones to install (unless a specific skill name is given), and automatically adds the package to your `skills.yaml` config.
73
80
 
81
+ `-y` / `--yes` takes the pickers' defaults: every detected skill, and every default agent with no agent filter saved, so the package follows `agents.default`. When skm runs without a terminal (from a script or a coding agent), it does the same on its own and prints the choice it made. Neither overrides a real directory that is already in an agent's skill folder; that still needs `--force`.
82
+
83
+ ### Device-local skills
84
+
85
+ If you keep `~/.config/skm` in a git repo to share `skills.yaml` across machines, use `--local` for skills that only one machine should have:
86
+
87
+ ```bash
88
+ skm install --local ~/Code/work-only-skills
89
+ ```
90
+
91
+ This symlinks the directory to `~/.config/skm/local_sources/work-only-skills` and installs it right away. `skills.yaml` is not modified. The `local_sources/` directory contains a `.gitignore` with `*`, so it never gets committed, even if your repo's own `.gitignore` doesn't list it.
92
+
93
+ Every later `skm install` also installs each entry in `local_sources/` as a `local_path:` package: all detected skills, default agents. To drop one, delete its link and run `skm install`.
94
+
95
+ A local source wins over any `skills.yaml` package that provides a skill with the same name, so you can point one device at a development copy of a shared skill. The shared version is skipped (not linked, not in the lock), and every install prints the override:
96
+
97
+ ```
98
+ Local source overrides
99
+ demo: ~/.config/skm/local_sources/demo-dev overrides https://github.com/me/skills
100
+ ```
101
+
102
+ Delete the local source and run `skm install` to get the shared version back. When two local sources provide the same skill, the entry whose name sorts first wins. `skm remove <skill>` deletes the link for you when it removes the last installed skill from that source.
103
+
104
+ ### Dynamic skills (from a command's output)
105
+
106
+ Some CLIs print their own skill, e.g. `tinyhost skill` writes a complete `SKILL.md` to stdout. Install it with `--cmd`:
107
+
108
+ ```
109
+ $ skm install --cmd "tinyhost skill"
110
+ Running tinyhost skill...
111
+ Generated skill tinyhost
112
+ Select agents:
113
+ > [x] standard
114
+ [x] claude
115
+ Config saved: ~/.config/skm/skills.yaml
116
+ tinyhost tinyhost from `tinyhost skill`
117
+ tinyhost -> [standard] ~/.agents/skills/tinyhost
118
+ tinyhost -> [claude] ~/.claude/skills/tinyhost
119
+ added 1 skill
120
+ ```
121
+
122
+ Keep every agent checked and the package follows `agents.default`; uncheck some to save an `includes` list. `-y` skips the prompt and keeps every agent; `--agents-includes claude` or `--agents-excludes standard` skips it and saves a filter. The command is saved to `skills.yaml` as:
123
+
124
+ ```yaml
125
+ packages:
126
+ - source_cmd: tinyhost skill
127
+ ```
128
+
129
+ You can also write that entry by hand and run `skm install`. `skm list` shows the skill with its command:
130
+
131
+ ```
132
+ tinyhost
133
+ cmd: tinyhost skill
134
+ agents: claude, standard
135
+ ```
136
+
137
+ skm runs the command with `sh -c` (pipes and environment variables work), without stdin, from your home directory, with a 60-second timeout. The output must be a `SKILL.md` with a frontmatter `name` made of letters, digits, `.`, `_` and `-`. skm saves it under the store (`~/.local/share/skm/skills/_dynamic/`) and links it like any other skill.
138
+
139
+ - `skm install` runs the command only the first time. If it fails (for example, another device sharing your `skills.yaml` doesn't have that CLI), skm prints a warning, skips the package, and installs everything else.
140
+ - `skm update <skill>` (or `--all`) runs the command again and relinks if the output changed. A failure here is an error.
141
+ - `skm install --cmd` runs the command before touching `skills.yaml`, so a broken command never gets saved.
142
+ - `check-updates` skips dynamic skills; run `skm update` to regenerate.
143
+
74
144
  ## Commands
75
145
 
76
146
  | Command | Description |
77
147
  |---|---|
78
148
  | `skm install` (or `skm i`) | Install all packages from config. Clone repos (or link local paths), detect skills, symlink to agents, write lock file. Idempotent — also removes stale links (see below). |
79
- | `skm install <source> [skill]` (or `skm i`) | Install directly from a repo URL or local path without editing config. Interactively select skills and agents, then auto-update config. |
149
+ | `skm install <source> [skill]` (or `skm i`) | Install directly from a repo URL or local path without editing config. Interactively select skills and agents (`-y` takes all), then auto-update config. |
150
+ | `skm install --local <dir>` | Link a directory into `local_sources/` and install it on this device only; `skills.yaml` is not changed. |
151
+ | `skm install --cmd "<cmd>"` | Install a dynamic skill from a command's stdout and add it to `skills.yaml` as `source_cmd`. |
80
152
  | `skm list` | Show installed skills and their linked paths. |
81
153
  | `skm list --all` | Show all skills across all agent directories, marking which are managed by skm. |
82
154
  | `skm view <source>` | Browse and preview skills from a repo URL or local path without installing. |
83
155
  | `skm edit` | Open `skills.yaml` in `$EDITOR` (falls back to system default). Shows diff after editing. |
84
- | `skm check-updates` | Fetch remotes and show available updates (skips `local_path` packages). |
85
- | `skm update <skill>` | Pull latest for a skill's repo, re-detect, re-link, update lock (skips `local_path` packages). |
156
+ | `skm check-updates` | Fetch remotes and show available updates (skips `local_path` packages and dynamic skills). |
157
+ | `skm update <skill>` | Pull latest for a skill's repo (or rerun a dynamic skill's command), re-detect, re-link, update lock (skips `local_path` packages). |
86
158
 
87
159
  ## Config Format
88
160
 
@@ -119,9 +191,11 @@ packages:
119
191
  skills_excludes: # optional: install all skills EXCEPT these (mutually exclusive with skills)
120
192
  - team-squad
121
193
  - team-council
194
+
195
+ - source_cmd: tinyhost skill # dynamic skill: the command's stdout is the SKILL.md
122
196
  ```
123
197
 
124
- Each package must specify exactly one of `repo` or `local_path`. Local path packages use the directory directly (no cloning) and are skipped by `check-updates` and `update`.
198
+ Each package must specify exactly one of `repo`, `local_path` or `source_cmd`. Local path packages use the directory directly (no cloning) and are skipped by `check-updates` and `update`. A `source_cmd` package produces exactly one skill, so it only accepts `agents`; see [Dynamic skills](#dynamic-skills-from-a-commands-output).
125
199
 
126
200
  Repo packages are cloned with a sparse checkout: skm runs `git clone --filter=blob:none --no-checkout`, lists the tree with `git ls-tree`, and checks out only the directories that contain a `SKILL.md` (using the same detection rules as below, honoring `skills_dir`). A large monorepo that ships a couple of skills therefore costs a few hundred KB on disk instead of the whole working tree. The store stays a normal git repo, so `check-updates` and `update` work unchanged; the sparse set is recomputed after every pull so skills added upstream are picked up automatically. Repos whose root is itself a skill are checked out in full.
127
201
 
@@ -137,10 +211,10 @@ Repo packages are cloned with a sparse checkout: skm runs `git clone --filter=bl
137
211
 
138
212
  ## Install Sync Behavior
139
213
 
140
- `skm install` treats `skills.yaml` as a declarative state file. Each run syncs the agent directories to match the config:
214
+ `skm install` treats `skills.yaml` plus the entries in `local_sources/` as declarative state. Each run syncs the agent directories to match them:
141
215
 
142
216
  - **New skills** are linked to agent directories.
143
- - **Removed skills** (dropped from a package's `skills:` list, or entire package removed) have their links deleted.
217
+ - **Removed skills** (dropped from a package's `skills:` list, entire package removed, or local source link deleted) have their links deleted.
144
218
  - **Agent config changes** (e.g. adding `excludes: [openclaw]`) remove links from excluded agents while keeping links in others.
145
219
 
146
220
  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`.
@@ -235,6 +309,7 @@ skm --config /tmp/test.yaml \
235
309
 
236
310
  - **Config:** `~/.config/skm/skills.yaml`
237
311
  - **Lock:** `~/.config/skm/skills-lock.yaml`
312
+ - **Local sources:** `~/.config/skm/local_sources/` (next to `skills.yaml`, self-gitignored)
238
313
  - **Store:** `~/.local/share/skm/skills/`
239
314
 
240
315
  ## Development
@@ -1,6 +1,6 @@
1
1
  # SKM - Skill Manager
2
2
 
3
- A CLI tool that manages **global** AI agent skills from GitHub repos or local directories. Clone repos or link local paths, detect skills via `SKILL.md`, and symlink them into agent directories — all driven by a single YAML config.
3
+ A CLI tool that manages **global** AI agent skills from GitHub repos, local directories, or CLIs that print their own skill. Clone repos or link local paths, detect skills via `SKILL.md`, and symlink them into agent directories — all driven by a single YAML config.
4
4
 
5
5
  > **Note:** skm manages skills at the user level (e.g. `~/.claude/skills/`), not at the project level. It is not intended for installing skills into project-scoped directories.
6
6
 
@@ -30,6 +30,7 @@ packages:
30
30
  - vercel-react-native-skills
31
31
  - repo: https://github.com/blader/humanizer
32
32
  - local_path: ~/Code/my-custom-skills # use a local directory instead of a git repo
33
+ - source_cmd: tinyhost skill # use the SKILL.md a CLI prints (see Dynamic skills)
33
34
  ```
34
35
 
35
36
  2. Run install (`skm i` for short):
@@ -38,7 +39,7 @@ packages:
38
39
  skm install
39
40
  ```
40
41
 
41
- Skills are cloned (or symlinked from local paths) into your agent directories (`~/.claude/skills/`, `~/.codex/skills/`, etc.).
42
+ Skills are cloned (or symlinked from local paths, or generated from a command's output) into your agent directories (`~/.claude/skills/`, `~/.codex/skills/`, etc.).
42
43
 
43
44
  ### Install from a source directly
44
45
 
@@ -54,24 +55,95 @@ skm install https://github.com/vercel-labs/agent-skills vercel-react-best-practi
54
55
  # Install from a local directory
55
56
  skm install ~/Code/my-custom-skills
56
57
 
58
+ # Install the skill a CLI prints to stdout (see Dynamic skills below)
59
+ skm install --cmd "tinyhost skill"
60
+
57
61
  # Skip interactive prompts with --agents-includes / --agents-excludes
58
62
  skm install https://github.com/blader/humanizer --agents-includes claude,codex
63
+
64
+ # Skip every prompt: all skills, default agents
65
+ skm install https://github.com/vercel-labs/agent-skills -y
59
66
  ```
60
67
 
61
68
  This detects available skills, lets you pick which ones to install (unless a specific skill name is given), and automatically adds the package to your `skills.yaml` config.
62
69
 
70
+ `-y` / `--yes` takes the pickers' defaults: every detected skill, and every default agent with no agent filter saved, so the package follows `agents.default`. When skm runs without a terminal (from a script or a coding agent), it does the same on its own and prints the choice it made. Neither overrides a real directory that is already in an agent's skill folder; that still needs `--force`.
71
+
72
+ ### Device-local skills
73
+
74
+ If you keep `~/.config/skm` in a git repo to share `skills.yaml` across machines, use `--local` for skills that only one machine should have:
75
+
76
+ ```bash
77
+ skm install --local ~/Code/work-only-skills
78
+ ```
79
+
80
+ This symlinks the directory to `~/.config/skm/local_sources/work-only-skills` and installs it right away. `skills.yaml` is not modified. The `local_sources/` directory contains a `.gitignore` with `*`, so it never gets committed, even if your repo's own `.gitignore` doesn't list it.
81
+
82
+ Every later `skm install` also installs each entry in `local_sources/` as a `local_path:` package: all detected skills, default agents. To drop one, delete its link and run `skm install`.
83
+
84
+ A local source wins over any `skills.yaml` package that provides a skill with the same name, so you can point one device at a development copy of a shared skill. The shared version is skipped (not linked, not in the lock), and every install prints the override:
85
+
86
+ ```
87
+ Local source overrides
88
+ demo: ~/.config/skm/local_sources/demo-dev overrides https://github.com/me/skills
89
+ ```
90
+
91
+ Delete the local source and run `skm install` to get the shared version back. When two local sources provide the same skill, the entry whose name sorts first wins. `skm remove <skill>` deletes the link for you when it removes the last installed skill from that source.
92
+
93
+ ### Dynamic skills (from a command's output)
94
+
95
+ Some CLIs print their own skill, e.g. `tinyhost skill` writes a complete `SKILL.md` to stdout. Install it with `--cmd`:
96
+
97
+ ```
98
+ $ skm install --cmd "tinyhost skill"
99
+ Running tinyhost skill...
100
+ Generated skill tinyhost
101
+ Select agents:
102
+ > [x] standard
103
+ [x] claude
104
+ Config saved: ~/.config/skm/skills.yaml
105
+ tinyhost tinyhost from `tinyhost skill`
106
+ tinyhost -> [standard] ~/.agents/skills/tinyhost
107
+ tinyhost -> [claude] ~/.claude/skills/tinyhost
108
+ added 1 skill
109
+ ```
110
+
111
+ Keep every agent checked and the package follows `agents.default`; uncheck some to save an `includes` list. `-y` skips the prompt and keeps every agent; `--agents-includes claude` or `--agents-excludes standard` skips it and saves a filter. The command is saved to `skills.yaml` as:
112
+
113
+ ```yaml
114
+ packages:
115
+ - source_cmd: tinyhost skill
116
+ ```
117
+
118
+ You can also write that entry by hand and run `skm install`. `skm list` shows the skill with its command:
119
+
120
+ ```
121
+ tinyhost
122
+ cmd: tinyhost skill
123
+ agents: claude, standard
124
+ ```
125
+
126
+ skm runs the command with `sh -c` (pipes and environment variables work), without stdin, from your home directory, with a 60-second timeout. The output must be a `SKILL.md` with a frontmatter `name` made of letters, digits, `.`, `_` and `-`. skm saves it under the store (`~/.local/share/skm/skills/_dynamic/`) and links it like any other skill.
127
+
128
+ - `skm install` runs the command only the first time. If it fails (for example, another device sharing your `skills.yaml` doesn't have that CLI), skm prints a warning, skips the package, and installs everything else.
129
+ - `skm update <skill>` (or `--all`) runs the command again and relinks if the output changed. A failure here is an error.
130
+ - `skm install --cmd` runs the command before touching `skills.yaml`, so a broken command never gets saved.
131
+ - `check-updates` skips dynamic skills; run `skm update` to regenerate.
132
+
63
133
  ## Commands
64
134
 
65
135
  | Command | Description |
66
136
  |---|---|
67
137
  | `skm install` (or `skm i`) | Install all packages from config. Clone repos (or link local paths), detect skills, symlink to agents, write lock file. Idempotent — also removes stale links (see below). |
68
- | `skm install <source> [skill]` (or `skm i`) | Install directly from a repo URL or local path without editing config. Interactively select skills and agents, then auto-update config. |
138
+ | `skm install <source> [skill]` (or `skm i`) | Install directly from a repo URL or local path without editing config. Interactively select skills and agents (`-y` takes all), then auto-update config. |
139
+ | `skm install --local <dir>` | Link a directory into `local_sources/` and install it on this device only; `skills.yaml` is not changed. |
140
+ | `skm install --cmd "<cmd>"` | Install a dynamic skill from a command's stdout and add it to `skills.yaml` as `source_cmd`. |
69
141
  | `skm list` | Show installed skills and their linked paths. |
70
142
  | `skm list --all` | Show all skills across all agent directories, marking which are managed by skm. |
71
143
  | `skm view <source>` | Browse and preview skills from a repo URL or local path without installing. |
72
144
  | `skm edit` | Open `skills.yaml` in `$EDITOR` (falls back to system default). Shows diff after editing. |
73
- | `skm check-updates` | Fetch remotes and show available updates (skips `local_path` packages). |
74
- | `skm update <skill>` | Pull latest for a skill's repo, re-detect, re-link, update lock (skips `local_path` packages). |
145
+ | `skm check-updates` | Fetch remotes and show available updates (skips `local_path` packages and dynamic skills). |
146
+ | `skm update <skill>` | Pull latest for a skill's repo (or rerun a dynamic skill's command), re-detect, re-link, update lock (skips `local_path` packages). |
75
147
 
76
148
  ## Config Format
77
149
 
@@ -108,9 +180,11 @@ packages:
108
180
  skills_excludes: # optional: install all skills EXCEPT these (mutually exclusive with skills)
109
181
  - team-squad
110
182
  - team-council
183
+
184
+ - source_cmd: tinyhost skill # dynamic skill: the command's stdout is the SKILL.md
111
185
  ```
112
186
 
113
- Each package must specify exactly one of `repo` or `local_path`. Local path packages use the directory directly (no cloning) and are skipped by `check-updates` and `update`.
187
+ Each package must specify exactly one of `repo`, `local_path` or `source_cmd`. Local path packages use the directory directly (no cloning) and are skipped by `check-updates` and `update`. A `source_cmd` package produces exactly one skill, so it only accepts `agents`; see [Dynamic skills](#dynamic-skills-from-a-commands-output).
114
188
 
115
189
  Repo packages are cloned with a sparse checkout: skm runs `git clone --filter=blob:none --no-checkout`, lists the tree with `git ls-tree`, and checks out only the directories that contain a `SKILL.md` (using the same detection rules as below, honoring `skills_dir`). A large monorepo that ships a couple of skills therefore costs a few hundred KB on disk instead of the whole working tree. The store stays a normal git repo, so `check-updates` and `update` work unchanged; the sparse set is recomputed after every pull so skills added upstream are picked up automatically. Repos whose root is itself a skill are checked out in full.
116
190
 
@@ -126,10 +200,10 @@ Repo packages are cloned with a sparse checkout: skm runs `git clone --filter=bl
126
200
 
127
201
  ## Install Sync Behavior
128
202
 
129
- `skm install` treats `skills.yaml` as a declarative state file. Each run syncs the agent directories to match the config:
203
+ `skm install` treats `skills.yaml` plus the entries in `local_sources/` as declarative state. Each run syncs the agent directories to match them:
130
204
 
131
205
  - **New skills** are linked to agent directories.
132
- - **Removed skills** (dropped from a package's `skills:` list, or entire package removed) have their links deleted.
206
+ - **Removed skills** (dropped from a package's `skills:` list, entire package removed, or local source link deleted) have their links deleted.
133
207
  - **Agent config changes** (e.g. adding `excludes: [openclaw]`) remove links from excluded agents while keeping links in others.
134
208
 
135
209
  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`.
@@ -224,6 +298,7 @@ skm --config /tmp/test.yaml \
224
298
 
225
299
  - **Config:** `~/.config/skm/skills.yaml`
226
300
  - **Lock:** `~/.config/skm/skills-lock.yaml`
301
+ - **Local sources:** `~/.config/skm/local_sources/` (next to `skills.yaml`, self-gitignored)
227
302
  - **Store:** `~/.local/share/skm/skills/`
228
303
 
229
304
  ## Development
@@ -5,13 +5,15 @@
5
5
  ## openclaw:源文件被替换式保存后硬链副本变旧,install 卡在覆盖确认
6
6
 
7
7
  - 记录:2026-10-23,standard 改为软链时确认 openclaw 仍走硬链(内置 `install_mode: materialize`)。
8
- - 编辑器、agent 的 Edit 工具和 `sed -i` 保存时会换掉 inode,`~/.openclaw/skills` 里的副本还是旧内容,源里新增的文件和点开头的文件也不会带过去。之后 `skm install` 判定副本"不是受管副本",逐个询问是否覆盖;非终端环境下直接报错退出。只影响启用了 openclaw 的用户,本机目前没启用。
8
+ - 编辑器、agent 的 Edit 工具和 `sed -i` 保存时会换掉 inode,`~/.openclaw/skills` 里的副本还是旧内容,源里新增的文件和点开头的文件也不会带过去。之后 `skm install` 判定副本"不是受管副本",逐个询问是否覆盖;非终端环境下自动回答 N,旧副本留着并从 lock 里去掉,要用 `--force` 才会刷新。只影响启用了 openclaw 的用户,本机目前没启用。
9
+ - 另一个触发场景:local source 覆盖同名 skill 时,openclaw 里原有的副本属于被覆盖的那个来源,所以 `skm install --local` 开始覆盖会弹一次确认;删掉 local source、恢复共享版本时也会弹一次。覆盖期间重复 install 不会再弹。
9
10
  - 处理方向:OpenClaw 新版支持 `skills.load.allowSymlinkTargets`,配置 skm store 和 local_path 目录后也许可以改回软链,需要实测;或者把 lock 里记录过的副本直接当作受管副本刷新,前提是先确认副本里没有只存在于副本的改动。
10
11
 
11
12
  ## update:两个包提供同名 skill 时,清理会删掉另一个包正在用的安装
12
13
 
13
14
  - 记录:2026-10-29,agent override 评审第 5 条;复现场景 `update_shared_path`(`tmp/2026-10-29-agent-override-review/repro.py`)。
14
15
  - 仓库 A、B 都有 `demo`,后装的 B 占了 `codex/demo`。给 A 加 `excludes: [codex]`,A 有新提交后执行 `skm update`,B 的 `codex/demo` 被删,lock 仍记录 B 装在 codex,下次 `skm install` 才恢复。直接安装和全量 install 会保护其他包仍在用的路径,只有 `update.py` 的清理不会。
16
+ - dynamic skill 的 update(`_update_dynamic`)清理旧路径时也是同样的做法,有同样的问题。
15
17
  - 处理方向:update 清理时排除 lock 里其他条目的 `linked_to`,最好复用 `install.py` 的 `_remove_stale_links`。
16
18
 
17
19
  ## 相对 local_path:软链目标相对于安装目录,导致 skill 不可读
@@ -20,3 +22,15 @@
20
22
  - `skm install tmp/.../source` 将相对路径原样写入 local_path 并作为软链目标,系统从 agent 安装目录解析该目标,导致 dangling symlink;CLI 仍然报告安装成功。已有 `cli.py` / `linker.py` 路径处理即如此,与 override 无关。
21
23
  - 复现:`tmp/2026-10-28-agent-override/manual/`;初次安装后的 `readlink new-claude/override-demo` 返回 `tmp/2026-10-28-agent-override/manual/source`,从该目标目录无法访问源文件。把配置里的 local_path 改成绝对路径并重新 install 后文件可读。
22
24
  - 临时方式:使用绝对路径或 `~/...`。后续应先补相对源路径的失败测试,再在源路径解析时统一转为绝对路径。
25
+
26
+ ## install:skills.yaml 里两个包提供同名 skill 时,每次 install 都来回替换
27
+
28
+ - 记录:2026-10-31,`skm install --local` 验收时发现;复现脚本 `tmp/2026-10-31-local-sources/same_name.sh`(改成两个 skills.yaml 包即可复现)。
29
+ - 软链 agent 下,每次 `skm install` 先由前一个包换上自己的链接,后一个包再换回去,每次都报有新增,最终生效的是配置里排在后面的包。启用 openclaw 时,后一个包发现副本内容不同就弹覆盖确认,非终端环境下自动回答 N,留着前一个包的副本。local source 与 skills.yaml 之间、local source 彼此之间的同名已经有了明确优先级(local source 优先;local source 之间按条目名排序先者优先),这条只剩 skills.yaml 包之间的同名。
30
+ - 处理方向:检测到 skills.yaml 包之间同名时直接报错,或者沿用 `LocalOverrides` 的思路改成先者优先并提示。改之前要考虑现有用户:目前实际生效的是后者。同类问题另见上面 update 清理那一条。
31
+
32
+ ## 安全:repo / local_path 里 SKILL.md 的 `name` 没做路径校验,可能写到 agent 目录外
33
+
34
+ - 记录:2026-11-15,做 dynamic skill 时发现(`kb/plans/2026-11-15-dynamic-skill.md`)。
35
+ - `name` 直接用作 `<agent 目录>/<name>`。如果 repo 里写了 `name: ../../.zshrc`,链接会建到 agent 目录外面;加上 `--force` 或在覆盖提示里选 y,原来的文件或目录会被删掉再换成链接。装不受信任的 repo,或者 name 写错的 repo,都会遇到。dynamic skill 已经用 `dynamic.SAFE_SKILL_NAME_RE` 校验过,repo 和 local_path 来源还没有。
36
+ - 处理方向:在 `detect_skills` 或 `link_skill` 入口用同一个正则校验,不合法的 skill 打警告跳过。先补失败测试。
@@ -0,0 +1,121 @@
1
+ ---
2
+ created: 2026-11-15
3
+ tags:
4
+ - dynamic-skill
5
+ - source-cmd
6
+ - install
7
+ - update
8
+ ---
9
+
10
+ # Dynamic skill:用 CLI 输出生成 skill(`source_cmd`)
11
+
12
+ ## PRD
13
+
14
+ ### 背景
15
+
16
+ 有些 CLI 自带 skill,内容要运行命令才能拿到,例如 `tinyhost skill` 往 stdout 打印一份带 frontmatter(`name: tinyhost`)的完整 SKILL.md。skm 目前只能装 git repo 和本地目录里的 skill,这类 skill 只能手动重定向到文件再当 local_path 装,CLI 升级后内容不会跟着更新。
17
+
18
+ ### 目标
19
+
20
+ 在 skills.yaml 里写一行命令,skm 就能把它的输出装成 skill,和其他 skill 一样 link 到各 agent 目录;`skm update` 时重新运行命令刷新内容。
21
+
22
+ ### 功能与交互
23
+
24
+ ```yaml
25
+ packages:
26
+ - source_cmd: tinyhost skill
27
+ agents: # 可选,和其他包一样
28
+ includes: [claude]
29
+ ```
30
+
31
+ - **install**:第一次运行命令,把输出存成 skill 并 link。已经生成过就不重跑(和 repo 已 clone 就不 pull 一样)。命令失败(比如共享 skills.yaml 的另一台设备没装这个 CLI)时打黄色警告和原因,跳过这个包,其余照常装,退出码 0;下次 install 再试。
32
+ - **命令执行**:用 `sh -c` 运行,可以用管道和环境变量;不接 stdin,工作目录固定为 home,最多运行 60 秒。
33
+ - **输出校验**:必须是带 frontmatter 和 `name` 的 SKILL.md;`name` 只能由字母数字和 `._-` 组成且不以符号开头,否则报错,不会写入任何文件。
34
+ - **update**:`skm update <name>` 和 `--all` 都重跑命令。内容没变显示 `✔ Already up to date`;变了就刷新内容并重新 link(skill 名变了,旧名的链接会被删掉)。命令失败直接报错。
35
+ - **list**:显示 `cmd: tinyhost skill`;`list --all` 在来源处显示命令。
36
+ - **remove**:删除链接、lock 条目和 skills.yaml 里的包。
37
+ - **check-updates**:不对比,提示 `Skipping dynamic skill: tinyhost (run skm update tinyhost to regenerate)`。
38
+ - **local source**:同名时 local source 照样优先。
39
+ - **`skm install --cmd "<cmd>"`**:不能和 SOURCE、`--local` 同时用。先运行并校验,命令有错就不写 skills.yaml;已在配置里就沿用原有包。agent 选择同直接安装:`--agents-includes/--agents-excludes`,否则交互多选,全选时不写 agents。
40
+
41
+ ### 不做的事
42
+
43
+ - check-updates 不运行命令对比内容
44
+ - 一个命令只产出一个 skill,不支持 `skills`/`skills_excludes`/`skills_dir`/`clone_strategy`
45
+ - remove 不删除生成的文件(和 repo clone 一样留在 store 里)
46
+ - 不给 repo 里的 SKILL.md `name` 补路径校验
47
+
48
+ ### 验收标准
49
+
50
+ - skills.yaml 写了 `source_cmd` 后 `skm install`,agent 目录里出现同名 skill,内容就是命令输出
51
+ - 命令不存在时 install 打警告、退出码 0,其他包照常装
52
+ - 上游输出变化后 `skm update <name>` 刷新内容;没变化时提示已是最新
53
+ - `skm list`、`check-updates`、`remove` 表现如上
54
+ - `skm install --cmd` 写入配置并安装;命令失败时配置不变
55
+
56
+ ## Tech Design
57
+
58
+ ### 现状
59
+
60
+ - 包类型由 `SkillRepoConfig`(`src/skm/types.py`)的 `repo` / `local_path` 二选一决定;`source_key` 用于配置合并、lock 归属、local source 覆盖判断。
61
+ - `run_install` / `run_install_package`(`src/skm/commands/install.py`)按 `is_local` 分派到 `_install_local` / `_install_repo`,两者有一大段重复的"逐个 agent link 并记 lock"循环。
62
+ - lock 条目 `InstalledSkill` 用 `repo or local_path` 表示来源,散落在 install、remove、list 里。
63
+ - `config._raw_pkg_source_key` 只认 `local_path` 和 `repo`。
64
+
65
+ ### 方案
66
+
67
+ 新增 `source_cmd` 包类型:运行命令得到 SKILL.md 文本,校验后写到 store 下 skm 管理的目录,再走现有的 link 流程。
68
+
69
+ 关键决策:
70
+
71
+ - **生成目录** `<store>/_dynamic/<slug>-<hash8>/SKILL.md`:slug 是命令里 `[a-z0-9]+` 片段用 `-` 连接,最长 40;hash8 是命令 sha256 前 8 位。`--store` 一并隔离,不新增 flag;改命令即换目录。repo 目录名形如 `host_path`,不会以 `_` 开头,不会撞名。备选"放在 config 目录旁"被否决:config 目录可能在 git 里共享。
72
+ - **运行**:复用 `git.run_cmd(['sh', '-c', cmd], text=True, stdin=DEVNULL, cwd=Path.home(), timeout=60)`;非零退出由 `run_cmd` 抛 ClickException 带 stderr;超时抛 `subprocess.TimeoutExpired`。
73
+ - **先校验后写入**:去掉开头空白,用拆出来的 `parse_skill_name_text` 解析 name,再按 `^[A-Za-z0-9][A-Za-z0-9._-]*$` 校验——name 会成为 agent 目录下的路径名,`../x` 会写出目录外。
74
+ - **原地写入**:内容不变不写;变了 `write_text` 覆盖,不换 inode,materialize agent 的硬链副本自动同步(避开 known-issues 里替换式保存的问题)。
75
+ - **失败处理**:`_install_dynamic` 是失败处理的顶层,捕获 `ClickException`/`TimeoutExpired`/`ValueError` 后警告并返回空结果;底层 `dynamic.py` 不写 try/except。
76
+
77
+ ### 数据变动
78
+
79
+ - `SkillRepoConfig.source_cmd: str | None`;校验三选一;空白命令报错;与 `skills_dir`/`clone_strategy`/`skills`/`skills_excludes` 同时出现报错;`is_dynamic` 属性;`source_key` 返回命令。
80
+ - `InstalledSkill.source_cmd: str | None` 和 `source` 属性。lock 条目:`source_cmd: <cmd>`、`skill_path: '.'`、`commit: null`。`save_lock` dump 全部字段,现有条目会一次性多出 `source_cmd: null`。
81
+
82
+ ### 逻辑变动
83
+
84
+ - `src/skm/dynamic.py`(新):`dynamic_skill_dir`、`render_source_cmd`、`generate_dynamic_skill`、`load_dynamic_skill`。
85
+ - `src/skm/detect.py`:拆出 `parse_skill_name_text(text, origin)`。
86
+ - `install.py`:提取 `_target_agents`、`_link_skills`,三种来源共用;新增 `_install_dynamic`、`_install_package` 分派;`_remove_stale_links` 与合并逻辑改用 `.source`。
87
+ - `update.py`:dynamic 条目单独分组,`_update_dynamic` 重跑、`force=True` 重新 link、清理旧路径、替换 lock 条目。
88
+ - `check_updates.py` / `list_cmd.py` / `remove.py`:识别 `source_cmd`,用 `.source`。
89
+ - `config.py`:`_raw_pkg_source_key` 加 `source_cmd` 分支(否则多个 dynamic 包 key 都是 `''`,保存时互相串掉)。
90
+ - `cli.py`:`install --cmd` 与 `_install_cmd_source`。
91
+ - 文档:`AGENTS.md`、`README.md`。
92
+
93
+ ### 实施步骤
94
+
95
+ - [x] 写 `tests/test_dynamic.py`(BDD,先失败)
96
+ - [x] types / detect / dynamic.py
97
+ - [x] install 重构 + dynamic 分支
98
+ - [x] update / check-updates / list / remove / config
99
+ - [x] cli `--cmd`
100
+ - [x] 全量测试通过
101
+ - [x] 用真实 `tinyhost skill` 隔离路径手动验收
102
+ - [x] 文档、session summary、commit
103
+
104
+ ### 测试与验证
105
+
106
+ `tests/test_dynamic.py`,命令统一用 `cat <tmp>/out.md`(`shlex.quote`),改 out.md 模拟上游变化;全程 `_cli_args(tmp_path)` 隔离。
107
+
108
+ - config:只写 source_cmd 通过;与 repo 同写、与 skills/skills_dir 同写、空命令报错
109
+ - 生成:写到 `_dynamic/<slug>-<hash>/SKILL.md`;无 frontmatter、name 非法、非零退出(带 stderr)、超时报错
110
+ - install e2e:创建链接、lock 有 source_cmd;二次 install 不重跑;失败时警告、exit 0、其他包照装、不进 lock;删包后清理链接;local source 同名覆盖
111
+ - update:内容变 → 重新生成 relink;不变 → up to date;`--all` 包含 dynamic;name 改变时旧链接删除;materialize agent 副本刷新
112
+ - list 显示 `cmd:`;remove 删链接/lock/配置;check-updates skip 提示
113
+ - 配置往返:两个 dynamic 包时 `skm install <repo>`,两个都保留
114
+ - `install --cmd`:写配置并安装;失败不写配置;已在配置中沿用 agents
115
+
116
+ 手动验收:隔离路径下用 `tinyhost skill` 走 install --cmd / list / update / check-updates / 失败路径 / remove,证据放 `tmp/2026-11-15-dynamic-skill/`。
117
+
118
+ ### 风险与待定
119
+
120
+ - 命令输出可能依赖环境变量(如 PATH),skm 被不同 shell 调用时结果可能不同;`sh -c` 继承当前环境,不做额外处理。
121
+ - repo 里 SKILL.md 的 `name` 同样没做路径校验,收尾时对照 known-issues 门槛决定是否登记。
@@ -0,0 +1,35 @@
1
+ ---
2
+ created: 2026-10-29
3
+ tags:
4
+ - release
5
+ - pypi
6
+ ---
7
+
8
+ # 发布 SKM 0.4.0
9
+
10
+ ## 概要
11
+
12
+ 按 minor version 将 `skm-cli` 从 0.3.0 升到 0.4.0,在当前 master 分支完成版本与发布准备。本版包含 `agents.override` 路径和安装模式配置、agent 环境变量解析,以及拒绝覆盖、安装目录别名、相对 override 路径和 home 路径边界的修复。
13
+
14
+ 验证:`uv run pytest -q` 全部 220 项通过(含联网测试);源码包和 wheel 构建成功,检查了版本元数据、新增 agents 模块及临时文件排除;在隔离环境安装 wheel 后运行 `skm --help` 成功。
15
+
16
+ 发布产物位于 `tmp/2026-10-29-release-0.4.0/dist/`。上传使用 `uv publish` 并明确指定本版的 wheel 和源码包;Git 使用 `v0.4.0` 标签。
17
+
18
+ ## 修改的文件
19
+
20
+ - `pyproject.toml`、`uv.lock`:版本同步至 0.4.0,依赖不变。
21
+ - `AGENTS.md`:记录版本升级、验证、构建和发布约定。
22
+
23
+ ## 注意事项
24
+
25
+ - PyPI 发布前确认线上版本为 0.3.0,且 0.4.0 尚不存在。
26
+ - 构建输出使用本次专属目录,避免默认 dist 目录中的历史产物被一起上传。
27
+ - 发布后通过 PyPI 版本接口和隔离安装复核线上产物。
28
+
29
+ ## 遗留问题
30
+
31
+ 现有已知问题继续由 [known-issues](../known-issues.md) 跟踪,本次不修改功能代码。
32
+
33
+ ## 相关文档
34
+
35
+ - [agent override 评审与修复](2026-10-29-agent-override-review-and-fixes.md):本次发布的功能和修复依据。