skm-cli 0.3.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 (81) hide show
  1. {skm_cli-0.3.0 → skm_cli-0.5.0}/AGENTS.md +46 -9
  2. skm_cli-0.5.0/PKG-INFO +321 -0
  3. skm_cli-0.5.0/README.md +310 -0
  4. skm_cli-0.5.0/kb/known-issues.md +36 -0
  5. skm_cli-0.5.0/kb/plans/2026-10-28-agent-override.md +346 -0
  6. skm_cli-0.5.0/kb/plans/2026-11-15-dynamic-skill.md +121 -0
  7. skm_cli-0.5.0/kb/sessions/2026-10-28-agent-override.md +50 -0
  8. skm_cli-0.5.0/kb/sessions/2026-10-29-agent-override-review-and-fixes.md +62 -0
  9. skm_cli-0.5.0/kb/sessions/2026-10-29-release-0.4.0.md +35 -0
  10. skm_cli-0.5.0/kb/sessions/2026-10-29-skm-ovfix-alias.md +65 -0
  11. skm_cli-0.5.0/kb/sessions/2026-10-29-skm-ovfix-decline.md +51 -0
  12. skm_cli-0.5.0/kb/sessions/2026-10-29-skm-ovfix-home.md +34 -0
  13. skm_cli-0.5.0/kb/sessions/2026-10-29-skm-ovfix-relpath.md +45 -0
  14. skm_cli-0.5.0/kb/sessions/2026-10-31-install-local-sources.md +50 -0
  15. skm_cli-0.5.0/kb/sessions/2026-11-15-dynamic-skill.md +50 -0
  16. skm_cli-0.5.0/kb/sessions/2026-11-19-install-noninteractive.md +45 -0
  17. skm_cli-0.5.0/kb/todo.md +5 -0
  18. {skm_cli-0.3.0 → skm_cli-0.5.0}/pyproject.toml +1 -1
  19. skm_cli-0.5.0/src/skm/agents.py +30 -0
  20. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/cli.py +244 -57
  21. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/check_updates.py +4 -1
  22. skm_cli-0.5.0/src/skm/commands/install.py +660 -0
  23. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/list_cmd.py +19 -18
  24. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/remove.py +29 -2
  25. skm_cli-0.5.0/src/skm/commands/update.py +230 -0
  26. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/config.py +2 -0
  27. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/detect.py +7 -3
  28. skm_cli-0.5.0/src/skm/dynamic.py +81 -0
  29. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/linker.py +13 -12
  30. skm_cli-0.5.0/src/skm/local_sources.py +92 -0
  31. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/tui.py +13 -0
  32. skm_cli-0.5.0/src/skm/types.py +188 -0
  33. skm_cli-0.5.0/src/skm/utils.py +26 -0
  34. skm_cli-0.5.0/tests/test_agent_override.py +384 -0
  35. skm_cli-0.5.0/tests/test_agents.py +55 -0
  36. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_cli_e2e.py +1 -1
  37. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_config.py +17 -1
  38. skm_cli-0.5.0/tests/test_dynamic.py +568 -0
  39. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_install.py +30 -11
  40. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_linker.py +18 -17
  41. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_list_cmd.py +6 -10
  42. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_local_path.py +6 -5
  43. skm_cli-0.5.0/tests/test_local_sources.py +489 -0
  44. skm_cli-0.5.0/tests/test_noninteractive.py +244 -0
  45. skm_cli-0.5.0/tests/test_utils.py +21 -0
  46. {skm_cli-0.3.0 → skm_cli-0.5.0}/uv.lock +1 -1
  47. skm_cli-0.3.0/PKG-INFO +0 -230
  48. skm_cli-0.3.0/README.md +0 -219
  49. skm_cli-0.3.0/kb/known-issues.md +0 -15
  50. skm_cli-0.3.0/src/skm/commands/install.py +0 -443
  51. skm_cli-0.3.0/src/skm/commands/update.py +0 -148
  52. skm_cli-0.3.0/src/skm/types.py +0 -158
  53. skm_cli-0.3.0/src/skm/utils.py +0 -9
  54. {skm_cli-0.3.0 → skm_cli-0.5.0}/.gitignore +0 -0
  55. {skm_cli-0.3.0 → skm_cli-0.5.0}/draft.md +0 -0
  56. {skm_cli-0.3.0 → skm_cli-0.5.0}/images/skm-install.png +0 -0
  57. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/notes/2026-10-23-github-pr-requirements-research.md +0 -0
  58. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/plans/2026-03-09-skm-skill-manager.md +0 -0
  59. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/plans/2026-09-04-sparse-checkout-clone.md +0 -0
  60. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-09-refactor-config-structure.md +0 -0
  61. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-add-local-path-support.md +0 -0
  62. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-extend-skm-install-direct-source.md +0 -0
  63. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-handle-existing-skill-dir-override.md +0 -0
  64. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-implement-skm-view-command.md +0 -0
  65. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-install-idempotent-sync.md +0 -0
  66. {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-09-04-sparse-checkout-clone.md +0 -0
  67. {skm_cli-0.3.0 → skm_cli-0.5.0}/link-skill +0 -0
  68. {skm_cli-0.3.0 → skm_cli-0.5.0}/skills.example.yaml +0 -0
  69. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/__init__.py +0 -0
  70. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/clonefile.py +0 -0
  71. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/__init__.py +0 -0
  72. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/view.py +0 -0
  73. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/git.py +0 -0
  74. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/lock.py +0 -0
  75. {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/py.typed +0 -0
  76. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_clonefile.py +0 -0
  77. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_detect.py +0 -0
  78. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_git.py +0 -0
  79. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_install_from_source.py +0 -0
  80. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_lock.py +0 -0
  81. {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_types.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
 
@@ -14,12 +14,15 @@ 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
20
21
  ├── git.py # Sparse clone (no-checkout + ls-tree + sparse-checkout), pull, fetch, commit SHA helpers (unified run_cmd error handling)
21
22
  ├── utils.py # Utility functions (compact_path)
22
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
23
26
  └── commands/
24
27
  ├── install.py # Clone repos, detect skills, link to agents, update lock
25
28
  ├── list_cmd.py # Print installed skills from lock file
@@ -33,14 +36,18 @@ tests/
33
36
  ├── test_git.py # Git operations (sparse clone command sequence, real local-repo sparse checkout, pull re-sparsing, clone failure handling)
34
37
  ├── test_linker.py # Symlink creation, agent filtering
35
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)
36
42
  └── test_cli_e2e.py # End-to-end CLI tests for all commands
37
43
  ```
38
44
 
39
45
  ## Key Paths
40
46
 
41
- - **Config:** `~/.config/skm/skills.yaml` — YAML dict with `packages` (repo list) and optional `agents.default`
47
+ - **Config:** `~/.config/skm/skills.yaml` — YAML dict with `packages` (repo list) and optional `agents.default` / `agents.override`
42
48
  - **Lock:** `~/.config/skm/skills-lock.yaml` — tracks installed skills, commits, symlink paths
43
- - **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
44
51
  - **Agent dirs:** Skills are symlinked into each agent's skill directory (e.g. `~/.claude/skills/`, `~/.codex/skills/`)
45
52
 
46
53
  ## Architecture
@@ -59,24 +66,44 @@ All git subprocess calls go through `run_cmd()` in `git.py`, which captures stdo
59
66
 
60
67
  ## Path Handling
61
68
 
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.
69
+ 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
70
 
64
71
  ## CLI Commands
65
72
 
66
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.
67
77
  - `skm list` — Show installed skills and their linked paths from lock file
68
78
  - `skm check-updates` — Fetch remotes, compare against locked commits, show changelog
69
79
  - `skm update <skill_name>` — Pull latest for a skill's repo, re-link, update lock
70
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
+
71
93
  ## Config Format (skills.yaml)
72
94
 
73
95
  Top-level YAML dict with `packages` and optional `agents`:
74
96
 
75
97
  ```yaml
76
98
  agents:
77
- default: # optional: select which KNOWN_AGENTS are active (omit = all)
99
+ default: # optional: select which BUILTIN_AGENTS are active (omit = all)
78
100
  - claude
79
101
  - standard
102
+ override:
103
+ standard:
104
+ install_mode: materialize
105
+ claude:
106
+ path: ~/custom-claude/skills
80
107
 
81
108
  packages:
82
109
  - repo: https://github.com/vercel-labs/agent-skills
@@ -89,9 +116,13 @@ packages:
89
116
  skills_excludes: # optional: install all skills EXCEPT these (mutually exclusive with skills)
90
117
  - team-squad
91
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
92
123
  ```
93
124
 
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.
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.
95
126
 
96
127
  ## Skill Detection
97
128
 
@@ -105,14 +136,16 @@ During traversal, `.git` and directories whose names start with `_` are skipped.
105
136
 
106
137
  ## Known Agents
107
138
 
108
- Defined in `src/skm/types.py` as `KNOWN_AGENTS`:
139
+ Defined in `src/skm/types.py` as `BUILTIN_AGENTS`:
109
140
  - `standard` → `~/.agents/skills`
110
141
  - `claude` → `~/.claude/skills`
111
142
  - `codex` → `~/.codex/skills`
112
143
  - `openclaw` → `~/.openclaw/skills`
113
144
  - `pi` → `~/.pi/agent/skills`
114
145
 
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.
146
+ `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.
147
+
148
+ 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
149
 
117
150
  ## Testing
118
151
 
@@ -149,7 +182,7 @@ skm --config /tmp/test.yaml \
149
182
  - `--config` — path to `skills.yaml` (default: `~/.config/skm/skills.yaml`)
150
183
  - `--lock` — path to `skills-lock.yaml` (default: `~/.config/skm/skills-lock.yaml`)
151
184
  - `--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)
185
+ - `--agents-dir` — base directory for agent installs; creates subdirs per agent name (overrides `BUILTIN_AGENTS` paths)
153
186
 
154
187
  ### E2E Test Helpers
155
188
 
@@ -185,3 +218,7 @@ uv run skm --help # run CLI
185
218
  ```
186
219
 
187
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.
skm_cli-0.5.0/PKG-INFO ADDED
@@ -0,0 +1,321 @@
1
+ Metadata-Version: 2.5
2
+ Name: skm-cli
3
+ Version: 0.5.0
4
+ Summary: Skill Manager - manage agent skills from GitHub repos
5
+ Author-email: Reorx <novoreorx@gmail.com>
6
+ Requires-Python: >=3.12
7
+ Requires-Dist: click>=8.1
8
+ Requires-Dist: pydantic>=2.0
9
+ Requires-Dist: ruamel-yaml>=0.18
10
+ Description-Content-Type: text/markdown
11
+
12
+ # SKM - Skill Manager
13
+
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
+
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
+
18
+ ![skm install](images/skm-install.png)
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ uv tool install skm-cli
24
+ ```
25
+
26
+ Or install from source:
27
+
28
+ ```bash
29
+ uv tool install git+https://github.com/reorx/skm
30
+ ```
31
+
32
+ ## Quick Start
33
+
34
+ 1. Create `~/.config/skm/skills.yaml`:
35
+
36
+ ```yaml
37
+ packages:
38
+ - repo: https://github.com/vercel-labs/agent-skills
39
+ skills:
40
+ - vercel-react-best-practices
41
+ - vercel-react-native-skills
42
+ - repo: https://github.com/blader/humanizer
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)
45
+ ```
46
+
47
+ 2. Run install (`skm i` for short):
48
+
49
+ ```bash
50
+ skm install
51
+ ```
52
+
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.).
54
+
55
+ ### Install from a source directly
56
+
57
+ You can also install skills directly from a repo URL or local path — no need to edit `skills.yaml` first:
58
+
59
+ ```bash
60
+ # Install from a GitHub repo (interactive skill & agent selection)
61
+ skm install https://github.com/vercel-labs/agent-skills
62
+
63
+ # Install a specific skill by name
64
+ skm install https://github.com/vercel-labs/agent-skills vercel-react-best-practices
65
+
66
+ # Install from a local directory
67
+ skm install ~/Code/my-custom-skills
68
+
69
+ # Install the skill a CLI prints to stdout (see Dynamic skills below)
70
+ skm install --cmd "tinyhost skill"
71
+
72
+ # Skip interactive prompts with --agents-includes / --agents-excludes
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
77
+ ```
78
+
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.
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
+
144
+ ## Commands
145
+
146
+ | Command | Description |
147
+ |---|---|
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). |
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`. |
152
+ | `skm list` | Show installed skills and their linked paths. |
153
+ | `skm list --all` | Show all skills across all agent directories, marking which are managed by skm. |
154
+ | `skm view <source>` | Browse and preview skills from a repo URL or local path without installing. |
155
+ | `skm edit` | Open `skills.yaml` in `$EDITOR` (falls back to system default). Shows diff after editing. |
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). |
158
+
159
+ ## Config Format
160
+
161
+ `~/.config/skm/skills.yaml`:
162
+
163
+ ```yaml
164
+ agents:
165
+ default: # optional: select which agents are active (omit = all)
166
+ - claude
167
+ - standard
168
+ override: # optional: customize built-in agents
169
+ standard:
170
+ install_mode: materialize # symlink or materialize
171
+ claude:
172
+ path: ~/custom-claude/skills # complete skill directory
173
+
174
+ packages:
175
+ - repo: https://github.com/vercel-labs/agent-skills
176
+ clone_strategy: shallow # optional: use git clone --filter=blob:none --depth 1
177
+ skills_dir: skills/.curated # optional: search only this repo-relative directory
178
+ skills: # optional: install only these skills (omit = all)
179
+ - vercel-react-best-practices
180
+ agents: # optional: further filter agents for this package
181
+ excludes:
182
+ - standard
183
+
184
+ - repo: https://github.com/blader/humanizer # installs all detected skills to default agents
185
+
186
+ - local_path: ~/Code/my-custom-skills # use a local directory as package source
187
+ skills:
188
+ - my-skill
189
+
190
+ - local_path: ~/Code/devblocks
191
+ skills_excludes: # optional: install all skills EXCEPT these (mutually exclusive with skills)
192
+ - team-squad
193
+ - team-council
194
+
195
+ - source_cmd: tinyhost skill # dynamic skill: the command's stdout is the SKILL.md
196
+ ```
197
+
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).
199
+
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.
201
+
202
+ `clone_strategy: shallow` is optional for repo packages. When set, the first clone additionally passes `--depth 1`; omitted or other values keep the full history (blobs are still fetched lazily). Existing cached repos are reused and pulled, so changing this option does not re-clone an already-present repo. Caches created before sparse checkout was introduced shrink on their next `skm update`.
203
+
204
+ `skills_dir` is optional and must be a relative path inside the package. When set, skm searches only that directory for `SKILL.md` files instead of using the default detection order.
205
+
206
+ `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.
207
+
208
+ `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`.
209
+
210
+ `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.
211
+
212
+ ## Install Sync Behavior
213
+
214
+ `skm install` treats `skills.yaml` plus the entries in `local_sources/` as declarative state. Each run syncs the agent directories to match them:
215
+
216
+ - **New skills** are linked to agent directories.
217
+ - **Removed skills** (dropped from a package's `skills:` list, entire package removed, or local source link deleted) have their links deleted.
218
+ - **Agent config changes** (e.g. adding `excludes: [openclaw]`) remove links from excluded agents while keeping links in others.
219
+
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`.
221
+
222
+ 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.
223
+
224
+ 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.
225
+
226
+ ## Skill Detection
227
+
228
+ A skill is a directory containing a `SKILL.md` file with YAML frontmatter (`name` field required). Detection order:
229
+
230
+ 1. Root `SKILL.md` — the repo itself is a singleton skill
231
+ 2. `./skills/` subdirectory exists — scan its children
232
+ 3. Otherwise — walk all subdirectories from repo root
233
+ 4. Stop descending once `SKILL.md` is found (no nested skills)
234
+
235
+ If a package sets `skills_dir`, this default order is bypassed and only that directory is scanned. If `skills_dir` itself contains `SKILL.md`, it is treated as a singleton skill.
236
+
237
+ ## Known Agents
238
+
239
+ | Agent | Default skill directory | Config-root environment variable | Default mode |
240
+ |---|---|---|---|
241
+ | `standard` | `~/.agents/skills/` | — | `symlink` |
242
+ | `claude` | `~/.claude/skills/` | `CLAUDE_CONFIG_DIR` | `symlink` |
243
+ | `codex` | `~/.codex/skills/` | `CODEX_HOME` | `symlink` |
244
+ | `openclaw` | `~/.openclaw/skills/` | — | `materialize` |
245
+ | `pi` | `~/.pi/agent/skills/` | `PI_CODING_AGENT_DIR` | `symlink` |
246
+
247
+ 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.
248
+
249
+ `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`).
250
+
251
+ ## Copy Strategy
252
+
253
+ When skm links a skill into an agent directory, it picks a strategy based on the agent config and filesystem:
254
+
255
+ ### 1. Symlink (default)
256
+
257
+ A symbolic link from `<agent_dir>/skills/<skill_name>` → `<store>/<skill_name>`. This is the default for all agents except `openclaw`. Changes in the store are immediately visible.
258
+
259
+ If the agent dir holds a copy that an older skm version materialized (every file identical to the source or a hardlink of it), `skm install` replaces it with a symlink without asking. A copy whose content differs from the source still prompts before it is overwritten.
260
+
261
+ ### 2. Hardlink
262
+
263
+ 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**.
264
+
265
+ 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.
266
+
267
+ ### 3. Reflink (copy-on-write)
268
+
269
+ When hardlinks can't be used (source and target on **different devices**), skm attempts a reflink/COW clone. This creates an independent copy that shares physical disk blocks with the source until either side is modified — fast and space-efficient.
270
+
271
+ The reflink backend is platform-specific:
272
+
273
+ | Platform | Mechanism | Supported filesystems |
274
+ |---|---|---|
275
+ | **Linux** | `FICLONE` ioctl (`fcntl.ioctl`) | Btrfs, XFS, OCFS2, and others with reflink support |
276
+ | **macOS** | `clonefile(2)` syscall (via `ctypes`) | APFS (default since macOS 10.13) |
277
+
278
+ ### 4. Plain copy (fallback)
279
+
280
+ If reflink is not available (unsupported filesystem, non-Unix platform, etc.), skm falls back to a plain `shutil.copy2` — a full byte copy with metadata preserved.
281
+
282
+ ### Selection flow
283
+
284
+ ```
285
+ install_mode: materialize?
286
+ ├── No → symlink
287
+ └── Yes → same device?
288
+ ├── Yes → hardlink
289
+ └── No → reflink supported?
290
+ ├── Yes → reflink (COW clone)
291
+ └── No → plain copy
292
+ ```
293
+
294
+ The reflink implementation is isolated in `src/skm/clonefile.py` with dedicated tests in `tests/test_clonefile.py`.
295
+
296
+ ## CLI Path Overrides
297
+
298
+ Override default paths for testing or custom setups:
299
+
300
+ ```bash
301
+ skm --config /tmp/test.yaml \
302
+ --store /tmp/store \
303
+ --lock /tmp/lock.yaml \
304
+ --agents-dir /tmp/agents \
305
+ install
306
+ ```
307
+
308
+ ## Key Paths
309
+
310
+ - **Config:** `~/.config/skm/skills.yaml`
311
+ - **Lock:** `~/.config/skm/skills-lock.yaml`
312
+ - **Local sources:** `~/.config/skm/local_sources/` (next to `skills.yaml`, self-gitignored)
313
+ - **Store:** `~/.local/share/skm/skills/`
314
+
315
+ ## Development
316
+
317
+ ```bash
318
+ uv sync
319
+ uv run pytest -v # run tests
320
+ uv run skm --help # run CLI
321
+ ```