skm-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{skm_cli-0.2.1 → skm_cli-0.3.0}/.gitignore

@@ -1 +1,2 @@
 .venv/
+tmp/

{skm_cli-0.2.1 → skm_cli-0.3.0}/AGENTS.md

@@ -16,8 +16,8 @@ src/skm/
 ├── types.py            # Pydantic data models + constants
 ├── config.py           # Load skills.yaml → SkmConfig
 ├── lock.py             # Read/write skills-lock.yaml
-├── detect.py           # Walk cloned repos for SKILL.md files
-├── git.py              # Clone, pull, fetch, commit SHA helpers (unified run_cmd error handling)
+├── detect.py           # Walk cloned repos for SKILL.md files; select_skill_dirs() applies the same rules to a git tree listing
+├── git.py              # Sparse clone (no-checkout + ls-tree + sparse-checkout), pull, fetch, commit SHA helpers (unified run_cmd error handling)
 ├── utils.py            # Utility functions (compact_path)
 ├── linker.py           # Symlink skills to agent dirs, resolve includes/excludes
 └── commands/
@@ -29,8 +29,8 @@ tests/
 ├── test_types.py        # Pydantic model validation
 ├── test_config.py       # Config loading, error handling
 ├── test_lock.py         # Lock file I/O
-├── test_detect.py       # Skill detection logic (local + network tests against real repos)
-├── test_git.py          # Git operations (clone, commit retrieval, clone failure handling)
+├── test_detect.py       # Skill detection logic (local + network tests against real repos); select_skill_dirs() path-list rules
+├── test_git.py          # Git operations (sparse clone command sequence, real local-repo sparse checkout, pull re-sparsing, clone failure handling)
 ├── test_linker.py       # Symlink creation, agent filtering
 ├── test_install.py      # Install command unit tests
 └── test_cli_e2e.py      # End-to-end CLI tests for all commands
@@ -45,7 +45,11 @@ tests/
 
 ## Architecture
 
-Config-driven: parse `skills.yaml` → clone repos to store → detect skills by walking for `SKILL.md` → symlink to agent dirs → write lock file.
+Config-driven: parse `skills.yaml` → sparse-clone repos to store → detect skills by walking for `SKILL.md` → symlink to agent dirs → write lock file.
+
+## Sparse Clone
+
+`clone_or_pull()` in `git.py` never checks out a whole repo. It clones with `--filter=blob:none --no-checkout`, lists HEAD's tree via `git ls-tree -r -z HEAD` (tree objects are always fetched, so this is offline), feeds the path list to `select_skill_dirs()` in `detect.py`, and runs `git sparse-checkout set --cone <dirs>` before `git checkout`. After every `git pull` the sparse set is recomputed so skills added upstream get materialized. A root-level `SKILL.md` (singleton) or a repo with no skills disables sparse checkout and checks out everything. `select_skill_dirs()` must stay in sync with `detect_skills()`; both share the rules listed under Skill Detection.
 
 Each command function (`run_install`, `run_list`, etc.) accepts explicit paths and agent dicts as parameters, making them testable with `tmp_path` fixtures without touching real filesystem locations.
 
@@ -59,7 +63,7 @@ Paths stored in `skills-lock.yaml` (e.g. `linked_to`) use `compact_path()` from
 
 ## CLI Commands
 
-- `skm install` — 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.
+- `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.
 - `skm list` — Show installed skills and their linked paths from lock file
 - `skm check-updates` — Fetch remotes, compare against locked commits, show changelog
 - `skm update <skill_name>` — Pull latest for a skill's repo, re-link, update lock
@@ -81,6 +85,9 @@ packages:
     agents:                  # optional: further filter agents for this package
       excludes:
         - standard
+  - local_path: ~/Code/devblocks
+    skills_excludes:         # optional: install all skills EXCEPT these (mutually exclusive with skills)
+      - team-squad
   - repo: https://github.com/blader/humanizer   # installs all detected skills to default agents
 ```
 
@@ -94,6 +101,8 @@ A skill is a directory containing a `SKILL.md` file with YAML frontmatter includ
 3. Otherwise → walk all subdirectories from repo root
 4. Stop descending once `SKILL.md` is found (no nested skill-in-skill)
 
+During traversal, `.git` and directories whose names start with `_` are skipped.
+
 ## Known Agents
 
 Defined in `src/skm/types.py` as `KNOWN_AGENTS`:
@@ -101,6 +110,9 @@ Defined in `src/skm/types.py` as `KNOWN_AGENTS`:
 - `claude` → `~/.claude/skills`
 - `codex` → `~/.codex/skills`
 - `openclaw` → `~/.openclaw/skills`
+- `pi` → `~/.pi/agent/skills`
+
+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.
 
 ## Testing
 

{skm_cli-0.2.1 → skm_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: skm-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Skill Manager - manage agent skills from GitHub repos
 Author-email: Reorx <novoreorx@gmail.com>
 Requires-Python: >=3.12
@@ -96,6 +96,8 @@ agents:
 
 packages:
   - repo: https://github.com/vercel-labs/agent-skills
+    clone_strategy: shallow       # optional: use git clone --filter=blob:none --depth 1
+    skills_dir: skills/.curated   # optional: search only this repo-relative directory
     skills:                  # optional: install only these skills (omit = all)
       - vercel-react-best-practices
     agents:                  # optional: further filter agents for this package
@@ -107,10 +109,23 @@ packages:
   - local_path: ~/Code/my-custom-skills         # use a local directory as package source
     skills:
       - my-skill
+
+  - local_path: ~/Code/devblocks
+    skills_excludes:         # optional: install all skills EXCEPT these (mutually exclusive with skills)
+      - team-squad
+      - team-council
 ```
 
 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`.
 
+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.
+
+`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`.
+
+`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.
+
+`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.
+
 ## Install Sync Behavior
 
 `skm install` treats `skills.yaml` as a declarative state file. Each run syncs the agent directories to match the config:
@@ -130,6 +145,8 @@ A skill is a directory containing a `SKILL.md` file with YAML frontmatter (`name
 3. Otherwise — walk all subdirectories from repo root
 4. Stop descending once `SKILL.md` is found (no nested skills)
 
+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.
+
 ## Known Agents
 
 Skills are symlinked into these directories by default:
@@ -147,12 +164,16 @@ When skm links a skill into an agent directory, it picks a strategy based on the
 
 ### 1. Symlink (default)
 
-A symbolic link from `<agent_dir>/skills/<skill_name>` → `<store>/<skill_name>`. This is the default for all agents. Changes in the store are immediately visible.
+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.
+
+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.
 
 ### 2. Hardlink
 
 When `use_hardlink: true` is set for an agent in `AGENT_OPTIONS`, skm creates hardlinks instead. Each file in the skill directory gets its own hardlink pointing to the same inode as the source. This only works when source and target are on the **same filesystem/device**.
 
+Only `openclaw` uses this, because OpenClaw skips skill symlinks whose real path is outside its skill root. Hardlinks break when an editor saves a file by replacing it, and new or dot-prefixed files are not carried over, so the copy needs another `skm install` after the source changes.
+
 ### 3. Reflink (copy-on-write)
 
 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.

{skm_cli-0.2.1 → skm_cli-0.3.0}/README.md

@@ -85,6 +85,8 @@ agents:
 
 packages:
   - repo: https://github.com/vercel-labs/agent-skills
+    clone_strategy: shallow       # optional: use git clone --filter=blob:none --depth 1
+    skills_dir: skills/.curated   # optional: search only this repo-relative directory
     skills:                  # optional: install only these skills (omit = all)
       - vercel-react-best-practices
     agents:                  # optional: further filter agents for this package
@@ -96,10 +98,23 @@ packages:
   - local_path: ~/Code/my-custom-skills         # use a local directory as package source
     skills:
       - my-skill
+
+  - local_path: ~/Code/devblocks
+    skills_excludes:         # optional: install all skills EXCEPT these (mutually exclusive with skills)
+      - team-squad
+      - team-council
 ```
 
 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`.
 
+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.
+
+`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`.
+
+`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.
+
+`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.
+
 ## Install Sync Behavior
 
 `skm install` treats `skills.yaml` as a declarative state file. Each run syncs the agent directories to match the config:
@@ -119,6 +134,8 @@ A skill is a directory containing a `SKILL.md` file with YAML frontmatter (`name
 3. Otherwise — walk all subdirectories from repo root
 4. Stop descending once `SKILL.md` is found (no nested skills)
 
+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.
+
 ## Known Agents
 
 Skills are symlinked into these directories by default:
@@ -136,12 +153,16 @@ When skm links a skill into an agent directory, it picks a strategy based on the
 
 ### 1. Symlink (default)
 
-A symbolic link from `<agent_dir>/skills/<skill_name>` → `<store>/<skill_name>`. This is the default for all agents. Changes in the store are immediately visible.
+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.
+
+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.
 
 ### 2. Hardlink
 
 When `use_hardlink: true` is set for an agent in `AGENT_OPTIONS`, skm creates hardlinks instead. Each file in the skill directory gets its own hardlink pointing to the same inode as the source. This only works when source and target are on the **same filesystem/device**.
 
+Only `openclaw` uses this, because OpenClaw skips skill symlinks whose real path is outside its skill root. Hardlinks break when an editor saves a file by replacing it, and new or dot-prefixed files are not carried over, so the copy needs another `skm install` after the source changes.
+
 ### 3. Reflink (copy-on-write)
 
 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.

skm_cli-0.3.0/kb/known-issues.md

@@ -0,0 +1,15 @@
+# Known Issues
+
+> 当前影响使用或稳定性、仍待处理的问题；解决后删除，处理结果写入 KB。
+
+## 列表：目录名称前缀相同时可能显示错误 agent
+
+- 记录：2026-10-23，见 [PR 需求调研](notes/2026-10-23-github-pr-requirements-research.md)。
+- `src/skm/commands/list_cmd.py` 的 `_agent_name_from_link` 使用字符串 `startswith` 判断归属。例如 lock 路径 `~/.agents/skills-extra/demo` 会匹配内置 `standard` 的 `~/.agents/skills`，导致列表显示错误 agent；自定义 agent 目录与另一个目录共享前缀时可触发。
+- 已通过当前代码静态确认，尚未执行独立复现测试。开放的 [PR #7](https://github.com/reorx/skm/pull/7) 提供父目录精确比较及回归测试，尚未合入。处理时应先补充失败测试，再修复判断。
+
+## openclaw：源文件被替换式保存后硬链副本变旧，install 卡在覆盖确认
+
+- 记录：2026-10-23，standard 改为软链时确认 openclaw 仍走硬链（`AGENT_OPTIONS`）。
+- 编辑器、agent 的 Edit 工具和 `sed -i` 保存时会换掉 inode，`~/.openclaw/skills` 里的副本还是旧内容，源里新增的文件和点开头的文件也不会带过去。之后 `skm install` 判定副本"不是受管副本"，逐个询问是否覆盖；非终端环境下直接报错退出。只影响启用了 openclaw 的用户，本机目前没启用。
+- 处理方向：OpenClaw 新版支持 `skills.load.allowSymlinkTargets`，配置 skm store 和 local_path 目录后也许可以改回软链，需要实测；或者把 lock 里记录过的副本直接当作受管副本刷新，前提是先确认副本里没有只存在于副本的改动。

skm_cli-0.3.0/kb/notes/2026-10-23-github-pr-requirements-research.md

@@ -0,0 +1,169 @@
+---
+created: 2026-10-23
+tags:
+  - github
+  - requirements
+  - skill-manager
+  - agent-config
+---
+
+# GitHub PR 需求意图与项目价值调研
+
+## 调研范围与结论
+
+截至 2026-10-23，`reorx/skm` 共检索到 5 个 PR：#1、#2、#3、#6 已合并，#7 仍开放。本文覆盖全部 PR，每个 PR 单独整理需求，并区分作者原始诉求、代码实际行为和本次建议。
+
+依据为 GitHub PR 正文、diff、讨论、关联 issue，以及当前代码。远端 master 为 `4a8372b80968d4d2877089abe6e94cf1f03adb94`；本地调研基线为 `514a92fd571dae967cba5f1d8763ec51819f381d`，只比远端多删除 `CLAUDE.md` 软链的提交，业务代码一致。#7 的 head 为 `3a4f024cb50160fc7e6129ea19cc2895f370b360`。
+
+| PR | 独立需求 | 状态 | 对项目的意义 | 建议 |
+|---|---|---|---|---|
+| [#1](https://github.com/reorx/skm/pull/1) | 跨平台正确读取技能文件，并避免安装仓库内部元数据 | 2026-03-15 合并 | 高：修复 Windows 安装、查看失败 | 保留；明确隐藏文件过滤边界 |
+| [#2](https://github.com/reorx/skm/pull/2) | 安装位置跟随用户的 agent 配置目录 | 2026-03-15 合并 | 高：避免安装成功但 agent 找不到技能 | 保留，纳入统一路径解析 |
+| [#3](https://github.com/reorx/skm/pull/3) | 列表正确识别缩写路径对应的 agent | 2026-03-17 合并 | 高：补齐 #2 的展示一致性 | 保留；继续修复路径前缀误判 |
+| [#6](https://github.com/reorx/skm/pull/6) | 非软链安装兼容不同文件系统，并支持更新实体内容 | 2026-03-19 合并 | 高：解决真实 Btrfs 子卷安装障碍 | 保留；区分兼容性、更新和隔离语义 |
+| [#7](https://github.com/reorx/skm/pull/7) | 在单一配置中统一 agent 定义，开放路径与安装模式覆盖 | 开放 | 高：用户可自行适配环境，无需修改源码 | 支持核心需求；先明确附带的更新语义变化 |
+
+这些需求均围绕 SKM 的核心任务：让同一批技能在不同 agent 和本机环境中可靠安装、更新、被识别。#7 的产品价值主要来自用户可以覆盖配置；单纯将常量移到另一个文件，收益有限。
+
+## PR #1：跨平台技能读取与实体安装过滤
+
+### 背景与意图
+
+作者报告 Windows 上默认文本编码造成 `UnicodeDecodeError`，以及硬链接 `.git/objects/pack` 时出现权限错误。用户需要正常安装、查看含非 ASCII 内容的技能，而不必调整系统 locale 或仓库内部权限。[原始报告与实现](https://github.com/reorx/skm/pull/1/files)
+
+### 独立需求描述
+
+技能管理器应以 UTF-8 读取 `SKILL.md`，使技能发现与内置分页查看行为不依赖操作系统默认编码。创建实体安装目录时，应排除不属于技能运行内容的仓库元数据，避免为安装技能复制 Git 内部状态。
+
+验收应覆盖：中文或特殊符号出现在技能正文时，发现和查看均成功；源目录含 `.git` 时，实体安装不包含该目录；常规脚本和资源仍完整安装。
+
+### 实现范围与价值判断
+
+PR 修改 `detect.py` 与 `commands/view.py` 的 `read_text`，显式指定 UTF-8；同时在硬链接遍历中跳过所有点号开头条目和软链接。改动很小，却解决核心流程阻断，值得保留。
+
+需要区分“排除 `.git`”与“排除所有隐藏资源”：后者是实际实现的更宽泛规则。如果某个技能依赖隐藏文件或符号链接资源，实体安装可能不完整。该规则现在仍在 `linker.py` 中；本次没有发现具体受影响技能，因此作为边界记录，不认定为已发生故障。该 PR 也没有提供完整 Windows 平台支持的证明，不能据此宣称全部命令已通过 Windows 验收。
+
+## PR #2：安装路径跟随 agent 配置目录
+
+### 背景与意图
+
+原先 agent 目录写死在源码中。用户通过环境变量改变 agent 配置根目录后，SKM 仍将技能安装到旧位置，造成两套目录不一致。[PR 正文](https://github.com/reorx/skm/pull/2)
+
+### 独立需求描述
+
+用户已经为 agent 指定配置根目录时，SKM 应将技能安装到该根目录下的 `skills` 子目录；未设置或设置为空时使用默认目录。这个解析结果应贯穿安装、更新和列表展示。
+
+此 PR 的具体映射是 `CLAUDE_CONFIG_DIR` 对应 Claude，`CODEX_HOME` 对应 Codex。这里描述的是 PR 和 SKM 当前实现，不额外推断这些产品所有版本的配置约定。
+
+验收应覆盖：默认目录不变；设置覆盖值后安装进入新目录；`~` 正确展开；lock 仍使用既有路径压缩规则；后续列表能识别安装目标。
+
+### 实现范围与价值判断
+
+`types.py` 增加 `_get_known_agents()`，应用两个环境变量覆盖。需求直接避免“装好了却不能用”，价值高，且无需用户维护两套重复配置。
+
+当前 `KNOWN_AGENTS` 在模块导入时计算，普通 CLI 进程通常足够，但同一进程内改变环境后不会自动重新解析。#7 改为命令执行过程中的统一解析，更容易保证一致性。后续若同时支持配置文件覆盖，需要明确优先级，而非在各命令中分别处理。
+
+## PR #3：列表中的 agent 归属正确且稳定
+
+### 背景与意图
+
+这是 #2 带出的配套问题：环境变量解析得到绝对目录，lock 使用 `~` 压缩路径；两种表示直接比较时不匹配。作者说“list 不显示安装的技能”，但从实现看，具体修复的是技能条目中的 agent 归属显示，技能条目本身仍从 lock 读取。[变更与测试](https://github.com/reorx/skm/pull/3/files)
+
+### 独立需求描述
+
+同一安装路径无论使用绝对形式还是 `~` 形式，列表均应显示正确的 agent 名称。路径展示的隐私压缩不应影响路径身份判断。
+
+验收应覆盖：默认目录、环境变量覆盖目录、lock 中的缩写路径都能识别；不同目录即使名称前缀相同，也不能认作同一 agent。
+
+### 实现范围与价值判断
+
+PR 在比较前也展开 lock 路径，并增加安装与列表测试。它保障“安装事实”和“用户看到的状态”一致，值得保留。
+
+但当前比较仍使用字符串 `startswith`：例如 `~/.agents/skills-extra/demo` 会被 `~/.agents/skills` 匹配，误显示为 `standard`。这是代码可直接确认的边界缺陷；#7 已提出使用安装路径父目录精确比较，并有对应测试。建议将此修复视为独立的正确性需求，优先于大型配置重构。
+
+## PR #6：跨文件系统的实体安装与刷新
+
+### 背景与意图
+
+[Issue #4](https://github.com/reorx/skm/issues/4) 给出实际使用场景：store 所在的 `~/.local/share` 与 home 位于不同 Btrfs 子卷，硬链接失败。作者同时提出两个方向：增加 reflink 回退，或允许用户覆盖安装策略。#6 处理前者，#7 延续后者。
+
+### 独立需求描述
+
+对于需要真实目录的 agent，用户应能在硬链接不可用的存储布局中安装技能。系统应自动选取可用方式，必要时普通复制，不能因为一种优化不适用就阻断安装。更新后，agent 使用的实体内容应反映新版本；无法完成的真实 I/O 故障必须暴露。
+
+验收应覆盖：同设备硬链接；跨设备时尝试 reflink；不支持 reflink 时复制；权限、磁盘故障不得误作“不支持”吞掉；更新后检查目标文件内容及删除行为，而不只检查 lock commit。
+
+### 实现范围与价值判断
+
+PR 引入 `clonefile.py`：Linux 使用 FICLONE，macOS 使用 `clonefile(2)`；`linker.py` 根据设备和能力选择硬链接、reflink 或复制；`update` 传入 `force=True` 以允许重建旧实体目录。[PR 实现](https://github.com/reorx/skm/pull/6/files)；[维护者补充 macOS 支持的说明](https://github.com/reorx/skm/pull/6#issuecomment-4087075634)。
+
+需求价值高，但应准确说明保证：跨设备并不保证 reflink 可用，普通复制才是最终兼容回退；硬链接与 reflink 也不是相同隔离模型，硬链接原地编辑会影响共享 inode 的另一端，不能描述为独立副本。
+
+刷新也有两个层次：当前 `_materialize_tree` 跳过已存在文件；但外层 `link_skill` 在发现目标与源不一致、且 `force=True` 时会删除目录重建。因此不能仅凭内层函数断言“当前所有 update 都不会更新内容”。#7 的刷新改动应结合外层分支与端到端内容断言评估。
+
+## PR #7：统一 agent 配置与用户覆盖
+
+### 背景与讨论演变
+
+[Issue #5](https://github.com/reorx/skm/issues/5) 最初希望把 `KNOWN_AGENTS`、环境变量映射、`AGENT_OPTIONS` 合并到静态配置。维护者随后明确建议复用 `skills.yaml` 的 `agents`，增加 `agents.override`，避免让用户管理第二份配置文件。[维护者意见](https://github.com/reorx/skm/pull/7#issuecomment-4087118375)
+
+最新实现已经采用该意见：内置定义保留为 Python 中的 `DEFAULT_AGENT_SPECS`，用户覆盖写在 `skills.yaml`。因此旧标题“move agent specs to bundled config file”已不准确；也不能因为 issue #5 已关闭，就判断需求已经合入。
+
+### 独立需求描述
+
+用户应能在现有配置文件中为内置 agent 指定技能目录与安装方式，无需修改 SKM 源码。安装、更新、列表必须使用同一套解析结果，同时保持现有配置兼容。
+
+```yaml
+agents:
+  default:
+    - claude
+    - standard
+  override:
+    claude:
+      path: ~/.agents/skills
+      install_mode: materialize
+```
+
+这里 `path` 是完整技能目录，环境变量值则是配置根目录，二者含义不能混淆。`materialize` 表示生成实体目录，具体采用硬链接、reflink 还是复制由系统决定。
+
+最新实现的路径优先级为：`--agents-dir` > `agents.override.<name>.path` > agent 环境变量 > 内置路径。只覆盖 `install_mode` 不会取消环境变量路径。`agents.default` 限定部署范围，包级 includes/excludes 再过滤该范围。
+
+验收应覆盖以下行为：
+
+- 旧配置继续使用现有默认目录与模式；未知 agent 或非法模式明确报错。
+- 路径覆盖、模式覆盖可以单独设置；优先级在安装、更新和列表中一致。
+- 直接安装的交互选项只包含默认启用的 agent。
+- `list` 能识别自定义安装位置；配置损坏时仍可带警告读取 lock。
+- 切换模式、迁移路径后，lock 与实际安装保持一致，不误删未管理内容。
+
+### 相对当前主分支，真正剩下什么
+
+GitHub 返回的 #7 diff 相对较旧基线包含 28 个文件。重新 fetch 后以当前 `origin/master...PR head` 比较，实际剩余 17 个文件、473 行新增、203 行删除。下表将累计 diff 中的内容与当前待合入内容分开。
+
+| 内容 | 当前主分支状态 | 评价 |
+|---|---|---|
+| `AgentSpec`、统一解析、`agents.override` | 尚无 | 核心新增，价值高 |
+| Pi 的 `PI_CODING_AGENT_DIR` 映射 | 尚无；Pi 默认目录已有 | 延续 #2 的一致性需求 |
+| 精确匹配列表路径、交互选项限制、配置损坏时列表降级 | 尚无这些改动 | 有价值的正确性与可用性补充 |
+| 实体刷新替换文件、普通文件冲突处理、旧文件保留警告 | 尚无这些改动 | 应独立审查更新语义 |
+| `skills_excludes`、`skills_dir`、`clone_strategy: shallow` | 已有 | 不应再次列为待开发 |
+| 稀疏检出与 `_` 目录过滤 | 已有 | 已实现的仓库访问与发现能力 |
+
+### 价值与取舍
+
+建议接受统一配置的产品方向。它直接回应 #4 中“让我选择安装方式”的诉求，也能让不需要实体目录的用户自行选择软链接，避免为某一 agent 的兼容问题要求所有用户接受同样策略。最新实现仅支持覆盖内置 agent，不支持注册任意新 agent；不宜将其宣传为通用插件注册机制。
+
+合入前最需要确认的是**实体更新遇到目标多余文件时如何处理**。当前主分支的测试要求上游删除的文件从实体安装中消失；#7 将该测试改成“旧文件保留，输出警告”。当目录其余内容仍被判断为受管理副本时，会走保留分支；不匹配且 force 重建时仍可能删除，因此并非所有情况下都保证保留。
+
+保留有助于避免误删用户添加的文件，但也可能让过期说明或脚本继续影响 agent；这改变了声明式同步的预期，不能当作内部重构附带接受。建议单独决定同步契约，并补充“只删除”“修改加删除”“用户添加文件”三类验收。更完整的后续方案是保存受管理文件清单或内容指纹，让删除判断基于所有权；这是本次建议，不是 PR 已提供的能力。
+
+维护者曾在 [早期 review](https://github.com/reorx/skm/pull/7#issuecomment-4242977222) 指出刷新跳过现有文件；最新 head 已改为替换现有文件，并强化更新后内容断言，不能把旧 review 原样当作未修复结论。作者的[最新回复](https://github.com/reorx/skm/pull/7#issuecomment-5548017604)报告 140 个非网络测试通过；这是作者报告，本次未执行 PR 分支测试，也未进行跨平台实机验收。
+
+## 建议的决策顺序
+
+1. 保留 #1、#2、#3、#6 的已合并能力，无需重新立项。
+2. 优先处理列表路径精确匹配等独立正确性问题，避免它们一直被大型重构阻塞。
+3. 同意 #7 的统一 agent 配置、路径和模式覆盖；将标题与说明更新为当前实际范围。
+4. 单独决定实体目录的删除与本地修改策略，再评估刷新部分是否合入。需求值得做，不代表当前整包实现已完成验收。
+
+本次仅做需求调研和代码比对，没有修改业务代码、合并 PR 或向 GitHub 发送评论。仓库没有 `kb/next-up.md`，无到期事项需要提醒。

skm_cli-0.3.0/kb/plans/2026-09-04-sparse-checkout-clone.md

@@ -0,0 +1,101 @@
+# Sparse Checkout Clone (Plan F)
+
+**Goal:** Stop materializing whole repositories in the store when only a handful of skill directories are needed. Clone without checkout, discover skill directories from the git tree, then sparse-checkout only those directories.
+
+**Background:** Benchmark on `herdrdev/herdr` (2851 files, 5 skills):
+
+| Strategy | Time | Disk |
+|---|---|---|
+| `--filter=blob:none` (current default) | 4.5s | 48M |
+| `--filter=blob:none --depth 1` (current `shallow`) | 4.9s | 46M |
+| `--no-checkout` + `ls-tree` discovery + sparse-checkout | 4.0s | 636K |
+
+`--filter=blob:none` alone barely helps: checking out HEAD still fetches every blob of the current tree. The win comes from never checking out directories that contain no skill.
+
+**Architecture:** Partial clone already fetches all tree objects, so `git ls-tree -r HEAD` works offline right after a `--no-checkout` clone. Reuse the existing detection rules (root singleton, `skills/` dir, `skills_dir`, skip `_*`, stop descending at the first `SKILL.md`) on that path list to pick the sparse set. The store stays a real git repo, so `check-updates`, `update`, `git fetch` and `git log` keep working unchanged. Re-apply the sparse set after every pull so skills added upstream get materialized.
+
+**Tech Stack:** git ≥ 2.37 (cone-mode `sparse-checkout`), Python 3.12, pytest.
+
+---
+
+## Task 1: Path-list skill discovery (TDD)
+
+**Files:**
+- Modify: `src/skm/detect.py`
+- Modify: `tests/test_detect.py`
+
+**Step 1: Write failing tests** for `select_skill_dirs(paths, skills_dir) -> list[str] | None`:
+
+- root `SKILL.md` → `None` (full checkout)
+- `skills/a/SKILL.md`, `skills/b/SKILL.md`, `other/x.py` → `['skills/a', 'skills/b']`
+- no `skills/` dir → walk from root: `foo/SKILL.md`, `bar/baz/SKILL.md` → `['bar/baz', 'foo']`
+- directory starting with `_` is skipped at every level
+- nested skill inside a skill is not listed (stop descending)
+- `skills_dir='pkg/curated'` → only dirs under it; `skills_dir` that is itself a skill → `[skills_dir]`
+- `skills_dir` with no `SKILL.md` below → `[]`
+- no `SKILL.md` anywhere → `[]`
+
+**Step 2: Implement** `select_skill_dirs` in `detect.py`, sharing the same rules as `detect_skills` / `_walk_for_skills`. Paths are repo-relative POSIX strings of blobs.
+
+**Step 3:** `uv run pytest tests/test_detect.py -v` passes.
+
+## Task 2: Sparse clone in git.py (TDD)
+
+**Files:**
+- Modify: `src/skm/git.py`
+- Modify: `tests/test_git.py`
+
+**Step 1: Write failing tests**
+
+- Update the two `fake_run_cmd` command-sequence tests: clone now emits
+  `git clone --filter=blob:none [--depth 1] --no-checkout <url> <dest>`, then `git ls-tree -r -z HEAD`, then `git sparse-checkout set --cone <dirs>` (or `git sparse-checkout disable` when no dirs / root singleton), then `git checkout`. The fake returns ls-tree output listing `skills/a/SKILL.md` so the sparse path is exercised.
+- Real local-repo test: source repo with `skills/a/SKILL.md`, `skills/b/SKILL.md`, `big/blob.bin`, `README.md`. After `clone_or_pull`: `skills/a` and `skills/b` exist, `big/` does not, `git sparse-checkout list` contains both dirs.
+- Real local-repo test: add `skills/c/SKILL.md` upstream, call `clone_or_pull` again → `skills/c` now exists in dest.
+- Real local-repo test: singleton repo (root `SKILL.md` plus `docs/x.md`) → full checkout, `docs/x.md` exists.
+- Real local-repo test: `skills_dir='pkg'` → only `pkg/*` skill dirs checked out.
+
+**Step 2: Implement**
+
+- `list_tree_files(repo_path) -> list[str]`: parse `git ls-tree -r -z HEAD`, return paths of blobs, skipping symlinks (mode `120000`) and submodules (type `commit`).
+- `apply_sparse_checkout(repo_path, skills_dir) -> list[str] | None`: `dirs = select_skill_dirs(list_tree_files(...), skills_dir)`; if `dirs` is `None` or empty → `git sparse-checkout disable`; else `git sparse-checkout set --cone <dirs>`. Returns `dirs`.
+- `clone_or_pull(repo_url, dest, clone_strategy=None, skills_dir=None)`:
+  - existing repo: `git pull --ff-only` then `apply_sparse_checkout`.
+  - new repo: clone with `--no-checkout`, `apply_sparse_checkout`, then `git checkout`.
+
+**Step 3:** `uv run pytest tests/test_git.py -v` passes.
+
+## Task 3: Thread `skills_dir` through commands
+
+**Files:**
+- Modify: `src/skm/commands/install.py` (two `clone_or_pull` call sites)
+- Modify: `src/skm/commands/update.py` (one call site)
+- Modify: `tests/test_cli_e2e.py`
+
+**Step 1: Write failing e2e tests**
+
+- `install` on a repo containing `skills/a` and an unrelated `big/` dir: store repo has `skills/a`, lacks `big/`, skill is linked, lock recorded.
+- After upstream adds `skills/b`, `update --all` materializes `skills/b` and links it.
+
+**Step 2:** Pass `skills_dir=repo_config.skills_dir` at every `clone_or_pull` call.
+
+**Step 3:** `uv run pytest -v` (full suite) passes.
+
+## Task 4: Docs
+
+**Files:**
+- Modify: `README.md` (`clone_strategy` paragraph → describe sparse clone; note that existing caches shrink on next `skm update`)
+- Modify: `AGENTS.md` (architecture line, `git.py`/`detect.py` descriptions, install command description)
+
+## Task 5: Commit
+
+Run the full suite once more, then commit with a message describing the sparse checkout clone.
+
+---
+
+## Decisions and caveats
+
+- **Existing caches are not rewritten by `install`.** `install` skips the pull for already-cloned repos, so legacy full clones only shrink on the next `update` (which pulls and re-applies the sparse set). Documented in README.
+- **Cone mode keeps top-level files of ancestor directories** (e.g. `README.md`, `skills/README.md`). This is small and keeps `detect_skills` behaviour identical: it only walks directories that exist.
+- **Skills referencing files outside their own directory** (`../../docs/x.md`) will break under sparse checkout. The `skills` CLI has the same limitation because it copies only the skill directory. `clone_strategy` is left in place; a future `full` value could opt out if this ever matters.
+- **`skills`/`skills_excludes` filters are not used to narrow the sparse set.** Skill names live in frontmatter, which needs blob content; all detected skill dirs are small anyway and the lock/stale logic expects full detection.
+- **No `--reclone` flag.** Out of scope; `rm -rf` of the store dir followed by `skm install` achieves the same.

skm_cli-0.3.0/kb/sessions/2026-09-04-sparse-checkout-clone.md

@@ -0,0 +1,53 @@
+---
+created: 2026-09-04
+tags:
+  - sparse-checkout
+  - git
+  - clone
+  - detect
+  - vercel-skills
+  - research
+---
+
+# 调研 vercel-labs/skills 的下载策略，并为 skm 实现 sparse-checkout 克隆
+
+## 概要
+
+起因是担心 skm 从大型 monorepo 安装技能时需要把整个仓库克隆下来，代价太高。先调研了 `vercel-labs/skills`（`npx skills add`）的实现：对普通仓库它同样是整仓 `git clone --depth 1` 到临时目录再复制技能目录；只有白名单 owner（vercel、vercel-labs、heygen-com、zapier/connectors）走一条不经 git 的 blob 快速路径（GitHub Trees API 列树、raw.githubusercontent.com 读 frontmatter、skills.sh 下载预打包快照），另外支持直接下载 raw SKILL.md 或 tar/zip 链接。
+
+在 `herdrdev/herdr`（2851 个文件、5 个技能）上实测发现 skm 原有的 `--filter=blob:none` 对减小体积几乎无效：checkout HEAD 时仍要拉取当前树的全部 blob，工作区照样 46MB。真正有效的是不 checkout 无关目录。于是实现了方案 F：`--filter=blob:none --no-checkout` 克隆后，用 `git ls-tree -r -z HEAD` 离线列树，按 skm 既有的技能检测规则选出技能目录，`git sparse-checkout set --cone` 后再 `git checkout`；每次 pull 后重新计算 sparse 集合。端到端验证 store 从 48MB 降到 2.9MB（加 `clone_strategy: shallow` 可再降到约 600KB），146 个测试全部通过，已提交为 `0d44a2f`。
+
+## 修改的文件
+
+- `kb/plans/2026-09-04-sparse-checkout-clone.md` — 新建。含基准数据、五个任务的拆分、设计取舍与已知限制。
+- `src/skm/detect.py` — 新增 `select_skill_dirs(paths, skills_dir)` 与 `_select_under()`，对路径列表套用与 `detect_skills` 相同的规则（根单例、`skills/` 优先、`skills_dir`、跳过 `_*` 与 `.git`、遇到 SKILL.md 停止下钻）。根单例返回 `None` 表示全量 checkout。
+- `src/skm/git.py` — `clone_or_pull` 新增 `skills_dir` 参数，克隆改为 `--no-checkout`；新增 `list_tree_files()`（解析 `ls-tree -z`，跳过符号链接与子模块）和 `apply_sparse_checkout()`（无技能或根单例时 `sparse-checkout disable`）。已有仓库在 `git pull --ff-only` 后也重新应用 sparse 集合。
+- `src/skm/commands/install.py`、`src/skm/commands/update.py` — 三处 `clone_or_pull` 调用传入 `skills_dir=repo_config.skills_dir`。
+- `tests/test_detect.py` — 新增 9 个 `select_skill_dirs` 用例。
+- `tests/test_git.py` — 重写两个命令序列用例（含根单例走 `disable` 的用例），新增 5 个真实本地仓库用例：只 checkout 技能目录、pull 后出现新技能、根单例全量、`skills_dir` 生效、旧全量克隆在 pull 后收缩。
+- `tests/test_cli_e2e.py` — 新增 `TestSparseCheckout` 三个端到端用例；`fake_clone_or_pull` 签名补上 `skills_dir`。
+- `tests/test_install.py` — `fake_clone_or_pull` 签名补上 `skills_dir`。
+- `README.md` — 重写 clone 策略段落，说明 sparse 行为、`shallow` 的新含义、旧缓存在下次 `update` 收缩。
+- `AGENTS.md` — 架构行、`detect.py`/`git.py` 描述、`skm install` 描述更新，新增 "Sparse Clone" 小节。
+
+## 注意事项
+
+- **`--filter=blob:none` 不减小工作区。** 它只延迟历史版本的 blob，checkout HEAD 仍需全部当前 blob。想省流量必须配合 sparse-checkout，这是本次最重要的认知纠正。
+- **partial clone 下 `git ls-tree` 是离线的。** blob:none 过滤的只是 blob，tree 对象总会被拉取，因此 `--no-checkout` 后立即 `ls-tree -r HEAD` 不产生网络请求，可以据此决定 sparse 集合。
+- **`select_skill_dirs()` 与 `detect_skills()` 必须保持同步。** 两者是同一套规则的两种实现（路径列表 vs 文件系统），改动检测规则时两处都要改，且 `test_detect.py` 两组用例都要更新。
+- **cone 模式会保留祖先目录的顶层文件**（如根目录的 README、`skills/README.md`），体积很小，且保证 `detect_skills` 只会遍历真实存在的目录，行为与之前一致。
+- **测试字符串里 `"\0100644"` 会被 Python 当作八进制转义 `\010`。** 构造 `ls-tree -z` 的假输出时要用 `\x00`。
+- **skills CLI 的白名单快速路径依赖 skills.sh 中心化缓存**，实测该服务对非白名单仓库也返回 200，但对 skm 来说引入第三方服务不值得；tarball 方案虽最快但会丢掉 git 仓库，`check-updates`/`update` 的增量逻辑要全部重写，也不采用。
+- **skills CLI 值得借鉴的另一点：** 它用 GitHub Trees API 做更新检查，按技能目录的 tree SHA 而非整仓 commit 判断是否有更新，上游改无关代码时不会误报。
+
+## 遗留问题
+
+- 本机 `~/.local/share/skm/skills/` 下的旧缓存不会被 `install` 收缩，需要跑一次 `skm update --all`。
+- 技能 SKILL.md 若引用自身目录之外的文件（如 `../../docs/x.md`），sparse 后会断链。skills CLI 有同样限制。若将来遇到，可给 `clone_strategy` 加 `full` 值退出 sparse。
+- `herdrdev/herdr` 在 `.agents/skills/` 下还有 3 个技能，但 skm 检测规则在存在 `skills/` 目录时只看 `skills/`，因此未发现。skills CLI 会同时扫描 `.agents/skills/`、`.claude/skills/` 等一组约定目录，可作为后续改进。
+- `check-updates` 仍按整仓 commit 判断更新，可考虑借鉴按技能目录 tree SHA 比较的做法（`git rev-parse HEAD:<dir>` 即可，无需 GitHub API）。
+- 调研用的 `tmp/vercel-skills/` 克隆仍留在工作目录（未纳入 git），不需要时可删除。
+
+## 相关文档
+
+- [Sparse Checkout Clone (Plan F)](../plans/2026-09-04-sparse-checkout-clone.md) — 本次 session 新建并按此计划实现

{skm_cli-0.2.1 → skm_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "skm-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "Skill Manager - manage agent skills from GitHub repos"
 readme = "README.md"
 authors = [