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.
- {skm_cli-0.3.0 → skm_cli-0.5.0}/AGENTS.md +46 -9
- skm_cli-0.5.0/PKG-INFO +321 -0
- skm_cli-0.5.0/README.md +310 -0
- skm_cli-0.5.0/kb/known-issues.md +36 -0
- skm_cli-0.5.0/kb/plans/2026-10-28-agent-override.md +346 -0
- skm_cli-0.5.0/kb/plans/2026-11-15-dynamic-skill.md +121 -0
- skm_cli-0.5.0/kb/sessions/2026-10-28-agent-override.md +50 -0
- skm_cli-0.5.0/kb/sessions/2026-10-29-agent-override-review-and-fixes.md +62 -0
- skm_cli-0.5.0/kb/sessions/2026-10-29-release-0.4.0.md +35 -0
- skm_cli-0.5.0/kb/sessions/2026-10-29-skm-ovfix-alias.md +65 -0
- skm_cli-0.5.0/kb/sessions/2026-10-29-skm-ovfix-decline.md +51 -0
- skm_cli-0.5.0/kb/sessions/2026-10-29-skm-ovfix-home.md +34 -0
- skm_cli-0.5.0/kb/sessions/2026-10-29-skm-ovfix-relpath.md +45 -0
- skm_cli-0.5.0/kb/sessions/2026-10-31-install-local-sources.md +50 -0
- skm_cli-0.5.0/kb/sessions/2026-11-15-dynamic-skill.md +50 -0
- skm_cli-0.5.0/kb/sessions/2026-11-19-install-noninteractive.md +45 -0
- skm_cli-0.5.0/kb/todo.md +5 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/pyproject.toml +1 -1
- skm_cli-0.5.0/src/skm/agents.py +30 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/cli.py +244 -57
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/check_updates.py +4 -1
- skm_cli-0.5.0/src/skm/commands/install.py +660 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/list_cmd.py +19 -18
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/remove.py +29 -2
- skm_cli-0.5.0/src/skm/commands/update.py +230 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/config.py +2 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/detect.py +7 -3
- skm_cli-0.5.0/src/skm/dynamic.py +81 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/linker.py +13 -12
- skm_cli-0.5.0/src/skm/local_sources.py +92 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/tui.py +13 -0
- skm_cli-0.5.0/src/skm/types.py +188 -0
- skm_cli-0.5.0/src/skm/utils.py +26 -0
- skm_cli-0.5.0/tests/test_agent_override.py +384 -0
- skm_cli-0.5.0/tests/test_agents.py +55 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_cli_e2e.py +1 -1
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_config.py +17 -1
- skm_cli-0.5.0/tests/test_dynamic.py +568 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_install.py +30 -11
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_linker.py +18 -17
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_list_cmd.py +6 -10
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_local_path.py +6 -5
- skm_cli-0.5.0/tests/test_local_sources.py +489 -0
- skm_cli-0.5.0/tests/test_noninteractive.py +244 -0
- skm_cli-0.5.0/tests/test_utils.py +21 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/uv.lock +1 -1
- skm_cli-0.3.0/PKG-INFO +0 -230
- skm_cli-0.3.0/README.md +0 -219
- skm_cli-0.3.0/kb/known-issues.md +0 -15
- skm_cli-0.3.0/src/skm/commands/install.py +0 -443
- skm_cli-0.3.0/src/skm/commands/update.py +0 -148
- skm_cli-0.3.0/src/skm/types.py +0 -158
- skm_cli-0.3.0/src/skm/utils.py +0 -9
- {skm_cli-0.3.0 → skm_cli-0.5.0}/.gitignore +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/draft.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/images/skm-install.png +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/notes/2026-10-23-github-pr-requirements-research.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/plans/2026-03-09-skm-skill-manager.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/plans/2026-09-04-sparse-checkout-clone.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-09-refactor-config-structure.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-add-local-path-support.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-extend-skm-install-direct-source.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-handle-existing-skill-dir-override.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-implement-skm-view-command.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-03-10-install-idempotent-sync.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/kb/sessions/2026-09-04-sparse-checkout-clone.md +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/link-skill +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/skills.example.yaml +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/__init__.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/clonefile.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/__init__.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/commands/view.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/git.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/lock.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/src/skm/py.typed +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_clonefile.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_detect.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_git.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_install_from_source.py +0 -0
- {skm_cli-0.3.0 → skm_cli-0.5.0}/tests/test_lock.py +0 -0
- {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
|
-
- **
|
|
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
|
|
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 `
|
|
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 `
|
|
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
|
-
|
|
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
|
|
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
|
+

|
|
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
|
+
```
|