diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 958f3d0..796ee33 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,6 +9,8 @@ see [README.md](README.md) and the agent skill under
- Go 1.26.6 or later, and `git` on `PATH`.
- Run `make check` before opening a pull request; CI enforces the same gate.
+- Changes reach `main` only through pull requests: branch protection requires
+ the CI checks to pass before a merge can land.
## The gate
@@ -50,10 +52,10 @@ sees them:
at its root, because `upgrade` locates the binary by base name.
Because the archives are not built until the release run, the check that catches
-a platform break before the tag is the ordinary one: land the change on `main`,
-wait for CI to go green, and only then push the tag. The release workflow
-re-runs every gate before publishing, so a failure there leaves a tag that has to
-be deleted or moved.
+a platform break before the tag is the ordinary one: merge the change through a
+pull request, wait for CI to go green on `main`, and only then push the tag. The
+release workflow re-runs every gate before publishing, so a failure there leaves
+a tag that has to be deleted or moved.
## User-facing text
diff --git a/README.md b/README.md
index d15d127..0e8139a 100644
--- a/README.md
+++ b/README.md
@@ -2,107 +2,79 @@
English | [简体中文](README_CN.md)
-A skill dependency manager for agent projects, in the spirit of Go modules:
-**declare what the project needs in `SKILL.mod`, pin the exact content in
-`SKILL.lock`, and let `skillmod sync` make every machine identical.**
+skillmod manages Agent Skills the way Go modules manage dependencies. You
+write down what a project needs in `SKILL.mod`, skillmod pins the exact
+content in `SKILL.lock`, and `skillmod sync` makes every machine agree.
-AGENTS.md tells an agent *how to behave*; `SKILL.mod` declares *which
-capabilities it needs*.
+AGENTS.md tells an agent how to behave. `SKILL.mod` says which skills it
+needs to behave that way.
## What it does
```mermaid
flowchart LR
- mod["SKILL.mod
declare"] --> lock["SKILL.lock
pin content"]
- lock --> sync["skillmod sync
reconcile"]
+ mod["SKILL.mod
what you need"] --> lock["SKILL.lock
exact content"]
+ lock --> sync["skillmod sync
make it so"]
sync --> inst["installed skills
.agents/skills"]
inst --> share["skillmod share
.claude .codex ..."]
inst -.-> verify["skillmod verify
CI gate"]
```
-- **Declare** the skills a project needs in a reviewable `SKILL.mod`.
-- **Sync** every machine into byte-identical agreement with the declaration —
- idempotent, and never overwriting local edits.
-- **Verify** that installed content still matches the lock; a drift fails the
- build.
-- **Share** installed skills with any agent through links in `./skills`.
-- **Update** to the newest immutable version of a skill — no registry required;
- publishing a skill is tagging a repository you already own.
+- **Declare** the skills a project needs in `SKILL.mod`, a small file you
+ review and commit.
+- **Sync** every machine to that declaration. Running it twice changes
+ nothing the second time, and it never throws away work you did locally.
+- **Verify** that what is installed is still what the lock says. A drift
+ exits non-zero, so `verify` drops straight into CI.
+- **Share** installed skills with other agents through links, so `.claude`,
+ `.codex`, and friends can use one installed set.
+- **Update** a skill to its newest version. There is no registry to run:
+ publishing a skill means tagging a repository you already own.
+
+The problem it solves: skills shape what an agent does, but managing them by
+hand leaves no record of what is installed, and copying them around is how
+two machines end up behaving differently. skillmod keeps the declaration,
+the exact content, and the installed copies in one place, and tells you when
+they stop agreeing.
## When you need it
-One skill on one machine needs none of this; the declaration pays for itself
-as soon as any of the following holds:
+One skill on one laptop needs none of this. It starts paying off as soon as
+any of these is true:
-- **More than one machine** works with the project — a teammate's checkout, a
- CI job, your second laptop — and all of them should install the same skills,
- byte for byte.
-- **More than one consumer** trusts the declaration — CI must prove the
- installed skills are exactly what was declared, so an edited or tampered
- skill fails the build.
-- **More than one agent** runs on one machine — `.claude`, `.codex`,
- workbuddy, ... share one installed set, each with its own links.
+- **More than one machine** works on the project — a teammate's checkout, a
+ CI job, your second laptop — and all of them should end up with the same
+ skills.
+- **Something has to prove it** — CI checks that the installed skills are the
+ declared ones, so an edited or tampered skill fails the build.
+- **More than one agent** runs on one machine and should share one installed
+ set, each with its own links.
| When you want to | Use |
| --- | --- |
| Bring an existing project or machine under management | `init` |
| Add a skill from any Git repository | `get` |
-| Make every machine identical to the declaration | `sync` |
+| Make every machine agree with the declaration | `sync` |
| Fail the build when an installed skill drifted | `verify` |
| Point other agents at installed skills | `share` |
-| Explain where a skill came from and what state it is in | `why` |
-| Move to the newest version, or back out cleanly | `update` / `remove` |
-
-## Why this exists
-
-Skills — packaged instructions and scripts — shape what an agent does, but
-managing them is stuck in a pre-dependency-manager era. Manual copies leave no
-record of what was installed. Git submodules make every consumer clone a whole
-repository and run Git to obtain a folder of Markdown. Platform marketplaces
-install into machine-local state, so a teammate's agent, a CI job, and your
-laptop drift apart. The symptoms are always the same: agents behave
-differently on different machines, "which version was in use" has no answer,
-and an edited or tampered skill goes unnoticed.
-
-skillmod applies the Go module model: declarations in `SKILL.mod`, content
-addressed by dirhash in `SKILL.lock`, idempotent reconciliation through
-`skillmod sync`. There is no registry to run — publishing a skill means
-creating a tag in a repository you already own.
-
-## What you get
-
-- **Every machine gets the same skills, byte for byte.**
-- **"Which version was in use" has an answer** — the lock records the requested
- version, the resolved commit, and the content hash.
-- **Edits and tampering are caught** — `verify` exits non-zero on drift, which
- is what makes it usable as a CI gate.
-- **Local work is never silently overwritten** — a modified installation is
- kept and reported with exit code 3 until a person decides what to do with it.
-- **Skills are fetched once and then reused** — one immutable snapshot per
- repository version is shared by every project on the machine and linked
- rather than copied, so a second project installs from disk.
-- **Nothing else is required** — no registry, no server, no telemetry; Git is
- the only external dependency.
+| Ask where a skill came from and what state it is in | `why` |
+| Move to a newer version, or back out cleanly | `update` / `remove` |
## Five minutes
```console
-$ skillmod get github.com/openai/skills//gh-fix-ci --install-mode=copy --yes
+$ skillmod get openai/skills//gh-fix-ci --install-mode=copy --yes
installed gh-fix-ci v0.0.0-20260624023612-49f948faa925; SKILL.mod and SKILL.lock were updated
```
-The repository is named once and the skill once: after `//` the skill name is
-enough, so the directory layout inside the repository does not have to be typed
-or remembered. An exact subdirectory still wins over a name, and a name that
-several skills answer is reported with the candidate paths instead of guessed.
-The declaration records where the skill actually lives, as the `source` line
-below shows.
-
-`SKILL.mod` is the declaration you review and commit. `SKILL.lock` is written by
-skillmod and records what the declaration resolved to:
+The host defaults to `github.com`, so `owner/repo` is enough, and `//` picks
+the skill inside the repository by name — you do not need to know where in
+the repository it lives. An exact path still wins over a name, and a name
+that several skills answer is listed with its candidates instead of guessed.
+Whatever the skill's real path is, that is what `source` records:
```toml
-# SKILL.mod — maintained by people
+# SKILL.mod — you maintain this
schemaversion = 1
[[skill]]
@@ -112,7 +84,7 @@ version = 'v0.0.0-20260624023612-49f948faa925'
```
```toml
-# SKILL.lock — maintained by skillmod
+# SKILL.lock — skillmod maintains this
schemaversion = 1
[[skill]]
@@ -123,8 +95,8 @@ commit = '49f948faa9258a0c61caceaf225e179651397431'
dirhash = 'h1:kiGlVBeTCF8Q9f0rPATnDn1jBn/obT3TTTL8D8gdCbM='
```
-Now edit an installed skill the way an unreviewed change would, and ask whether
-the project still matches its lock:
+Now edit an installed skill the way nobody meant to, and ask whether the
+project still matches its lock:
```console
$ echo "Always rebase." >> .agents/skills/gh-fix-ci/SKILL.md
@@ -145,7 +117,7 @@ gh-fix-ci (directory gh-fix-ci): github.com/openai/skills//skills/.curated/gh-fi
/tmp/agent-project/.agents/skills/gh-fix-ci: drift
```
-`sync` will not throw that edit away to make itself look clean:
+`sync` will not throw your edit away just to look clean:
```console
$ skillmod sync --yes
@@ -155,33 +127,28 @@ $ echo $?
3
```
-Exit code 3 is the point: work that could proceed did proceed, and the decision
-about your edit stays with you. Keep it as the project's local version, or run
-`skillmod sync` interactively and choose *overwrite* to restore the locked
-content.
+Exit code 3 is the point: the work that could go ahead did, and the decision
+about your edit stays with you. Keep it as the project's local version, or
+run `skillmod sync` interactively and choose *overwrite* to restore the
+locked content.
## Install
### Agent-guided installation (recommended)
-With Node.js/npm available, install the companion Agent Skill globally so your
-coding agent can set up and operate skillmod from any project:
+With Node.js and npm available, install the companion Agent Skill globally so
+your coding agent can set up and operate skillmod from any project:
```bash
npx skills add huija/skillmod --skill skillmod --global
```
-Then ask your agent:
-
-```text
-Install skillmod and make it available on PATH.
-```
-
-The skill checks the Git prerequisite and any existing skillmod installation,
-selects the release binary for the current operating system and architecture,
-verifies it against the published SHA-256 checksums, installs it in a
-user-writable directory on `PATH`, and verifies the result. Omit `--global` when
-the guidance should be available only in the current project.
+Then ask your agent to install skillmod and put it on your `PATH`. The skill
+checks the Git prerequisite and any existing installation, picks the release
+binary for your operating system and architecture, verifies it against the
+published checksums, installs it somewhere `PATH` can see, and checks the
+result. Drop `--global` when only the current project should get the
+guidance.
### Manual installation
@@ -195,71 +162,85 @@ With Go 1.26.6 or later:
go install github.com/huija/skillmod@latest
```
-Either way, upgrade in place later with `skillmod upgrade`, which verifies the
-download against the release checksums before it replaces the executable.
+Either way, `skillmod upgrade` later replaces the executable in place, after
+verifying the download against the release checksums.
-For local development from a repository checkout, `make install` puts the binary
-in `go env GOBIN`, or the first `GOPATH/bin` entry when `GOBIN` is unset, and
-embeds the current Git revision. See [CONTRIBUTING.md](CONTRIBUTING.md).
+For local development, `make install` builds the binary into `go env GOBIN`
+(or the first `GOPATH/bin` entry) and embeds the current Git revision; see
+[CONTRIBUTING.md](CONTRIBUTING.md).
## Prerequisites
-skillmod invokes the system `git` executable to fetch sources, so Git must be
-installed and on `PATH` (on Windows, install
-[Git for Windows](https://gitforwindows.org/); it is not preinstalled). SSH
-remotes additionally require `ssh` on `PATH`.
+skillmod shells out to `git` to fetch skills, so Git must be installed and on
+`PATH` (on Windows, install [Git for Windows](https://gitforwindows.org/) —
+it does not come with the system). SSH remotes also need `ssh` on `PATH`.
## Everyday commands
| Command | What it does |
| --- | --- |
-| `init` | Adopt skills that already exist on disk into `SKILL.mod` and `SKILL.lock` |
+| `init` | Adopt the skills that already exist on disk into `SKILL.mod` and `SKILL.lock` |
| `get ` | Add a skill and install it |
-| `sync` | Reconcile installations with the lock; idempotent, and never overwrites local edits |
+| `sync` | Bring installations in line with the lock; safe to run any number of times, and never overwrites local edits |
| `share` | Link installed skills into agent directories such as `.claude` or `.codex`; see [Share with agents](#share-with-agents) |
| `list` | Show every declaration, its version, and its installation status |
| `why ` | Explain one entry: source, resolved version, commit, dirhash, and per-target status |
-| `update [selector]` | Move entries to the newest immutable version — the highest tag wins and only tagless repositories track HEAD; refuses a silent downgrade of tag locks |
+| `update [selector]` | Move entries to the newest immutable version — the highest tag wins, and only a tagless repository tracks HEAD |
| `verify` | Check installed content against the lock; the CI gate |
| `remove [selector]` | Delete declarations and clean managed installations; with `--agent`, unlink only those agents and keep the skills |
| `prune` | Drop stale installations and lock records left behind by hand edits |
| `upgrade` | Replace the running executable with a published release, verified against its checksums |
-`skillmod --global init` declares the skills the user already has in
-`~/.agents/skills/`; `skillmod init` declares the project's own. The two
-adoptions are independent steps in either order, and the two manifests stay
-independent, so a command reaches the machine only when it carries
-`--global`;
-[use-cases.md](skills/skillmod/references/use-cases.md) walks through both
-scopes.
-
-Every command accepts `--json` (`-j`) for machine-readable output and `--global`
-(`-g`) to operate on user-wide skills instead of the current project; mutations
-accept `--dry-run` (`-n`) and `--yes` (`-y`). `get` also accepts `--alias`
-(`-a`), `init` accepts `--force` (`-f`), `sync` accepts `--check` (`-c`) and
-`--relink` (`-r`), `share` accepts `--skill` (`-s`), `--agent` (`-a`), and
-`--remove` (`-r`), `remove` accepts `--skill` (`-s`) and `--agent` (`-a`), and `upgrade` accepts
-`--check` (`-c`) and `--tag` (`-t`).
-
-`get`, `remove`, and `share` accept `--all`, which states the whole set instead
-of asking for it: every skill the repository publishes, every declared entry,
-and every installed skill respectively. `--yes` is the other half of that pair —
-it answers the confirmations that follow a selection and never decides what the
-selection is. `--all`, `--install-mode`, `--allow-downgrade`, and
-`--on-conflict` deliberately have no shorthand: the obvious letters are
-ambiguous or already taken, and the long forms read better.
-
-Command help, summaries, prompts, and errors follow `SKILLMOD_LANG` when it is
-set and the system locale otherwise; JSON field names and action identifiers are
-never translated.
+`skillmod --global init` adopts the skills the user already has in
+`~/.agents/skills/`; `skillmod init` adopts the project's own. The two scopes
+are independent — separate manifests, either order — so a command reaches
+the machine only when it carries `--global`.
+
+Every command accepts `--json` (`-j`) and `--global` (`-g`). Mutations accept
+`--dry-run` (`-n`) and `--yes` (`-y`). `get` also accepts `--alias` (`-a`),
+`init` accepts `--force` (`-f`), `sync` accepts `--check` (`-c`),
+`--relink` (`-r`), and `--adopt`, `share` accepts `--skill` (`-s`),
+`--agent` (`-a`), and `--remove` (`-r`), `remove` accepts `--skill` (`-s`)
+and `--agent` (`-a`), and `upgrade` accepts `--check` (`-c`) and `--tag`
+(`-t`).
+
+`--json` writes one machine-readable document to stdout and nothing else,
+including when the command fails — a failed run carries an `error` field and
+still exits with the same code. Human output disappears in that mode, so
+scripts never have to tell the two apart. `--adopt` on `sync` takes stock of
+skills that were added outside skillmod — by `npx`, by a copy, by hand — and
+declares them as local entries with their current content as the baseline;
+your files are never rewritten. A plain `sync` only names them and points at
+the flag.
+
+`get`, `remove`, and `share` accept `--all`, which states the whole set
+instead of asking for it: every skill the repository publishes, every
+declared entry — or every entry a repository selector names — and every
+installed skill respectively. `--yes` is the other
+half of that pair — it answers the confirmations that follow a selection and
+never decides what the selection is. `--all`, `--install-mode`,
+`--allow-downgrade`, `--on-conflict`, and `--adopt` deliberately have no
+shorthand: the obvious letters are ambiguous or already taken, and the long
+forms read better.
+
+Both `get` and `remove` take a repository instead of a name. `get
+owner/repo//name` installs one skill; `remove owner/repo` lists the skills
+declared from that repository and lets you pick which ones go, exactly like
+`get` lists the skills a repository publishes. Adding `--all` takes them all
+without a terminal, which is how a script says "everything this repository
+brought in".
+
+Command help, prompts, summaries, and errors follow `SKILLMOD_LANG` when it
+is set and the system locale otherwise. JSON field names and action
+identifiers are never translated.
## Share with agents
An agent is named by one directory segment and reads its skills from
`./skills`, so any agent works — well-known ones like `.claude` and
-`.codex` and any other single-segment name alike. Each skill records the agents
-it is linked to on its own entry in `SKILL.mod`, and `sync` recreates the
-links on every machine:
+`.codex` and any other single-segment name alike. Each skill records the
+agents it is linked to on its own entry in `SKILL.mod`, and `sync` recreates
+the links on every machine:
```console
$ skillmod share --all --agent claude --agent workbuddy --yes
@@ -270,8 +251,8 @@ $ skillmod share --all --agent claude --agent workbuddy --yes
## Where the details live
-Rather than grow this README into a manual, the rules live with the Agent Skill
-that operates skillmod. Both people and agents can read them:
+This README stays a front door. The rules live with the Agent Skill that
+operates skillmod, and both people and agents can read them:
| Read | For |
| --- | --- |
@@ -286,9 +267,9 @@ that operates skillmod. Both people and agents can read them:
## Current limitations
- No registry service; a skill is a Git repository, and publishing is tagging.
-- No transitive dependencies and no version-constraint solving. Declarations are
- flat, one entry per skill.
-- No skill-content security scanning or telemetry.
+- No transitive dependencies and no version-constraint solving. Declarations
+ are flat, one entry per skill.
+- No skill-content security scanning and no telemetry.
## License
diff --git a/README_CN.md b/README_CN.md
index 67ecd96..e6da466 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -2,71 +2,67 @@
[English](README.md) | 简体中文
-面向 agent 项目的 skill 依赖管理器,设计血统来自 go mod:
-**在 `SKILL.mod` 里声明项目需要什么,用 `SKILL.lock` 锁定内容,再由 `skillmod sync` 让每台机器完全一致。**
+skillmod 用 go mod 的方式管理 Agent Skill:在 `SKILL.mod` 里写下项目需要什么,
+skillmod 把确切的内容锁进 `SKILL.lock`,再由 `skillmod sync` 让每台机器保持一致。
-与 AGENTS.md 的关系:AGENTS.md 告诉 agent *怎么行为*,`SKILL.mod` 声明 agent *需要什么能力*。
+AGENTS.md 告诉 agent 该怎么做事;`SKILL.mod` 说明它做事需要哪些技能。
## 它做什么
```mermaid
flowchart LR
- mod["SKILL.mod
声明"] --> lock["SKILL.lock
锁定内容"]
+ mod["SKILL.mod
声明需要什么"] --> lock["SKILL.lock
锁定确切内容"]
lock --> sync["skillmod sync
对齐安装"]
sync --> inst["已安装技能
.agents/skills"]
inst --> share["skillmod share
.claude .codex ..."]
inst -.-> verify["skillmod verify
CI 关卡"]
```
-- **声明(Declare)**:在可评审的 `SKILL.mod` 里列出项目需要的技能。
-- **对齐(Sync)**:让每台机器与声明逐字节一致——幂等执行,且绝不覆盖本地修改。
-- **校验(Verify)**:检查已安装内容是否仍与锁文件一致;有漂移就让构建失败。
-- **分发(Share)**:通过 `.<名字>/skills` 里的链接,把已安装技能交给任意 agent。
-- **更新(Update)**:升级到技能最新的不可变版本——无需 registry;发布一个技能就是给自己的仓库打个 tag。
+- **声明**:把项目需要的技能写进 `SKILL.mod`,一个小文件,评审后提交。
+- **对齐**:`sync` 让每台机器符合这份声明。重复执行不会改变任何东西,
+ 本地做过的修改也不会被它丢掉。
+- **校验**:`verify` 检查已安装内容是否还和锁文件一致。有漂移就以非零码
+ 退出,可以直接挂进 CI。
+- **分享**:通过链接把已安装的技能交给其他 agent,`.claude`、`.codex`
+ 都能共用同一套安装。
+- **更新**:`update` 把技能升级到最新版本。没有需要维护的 registry——
+ 发布一个技能,就是给自己的仓库打个 tag。
+
+它解决的问题是:技能决定 agent 的行为,但手工管理留不下"装了什么"的
+记录,靠拷贝分发,两台机器迟早行为不一致。skillmod 把声明、确切内容和
+已安装的副本放在一处,它们不再一致时会告诉你。
## 什么时候需要它
-单机单技能并不需要它;以下任一情况成立,这份声明就开始回本:
+一台机器、一个技能,用不上它。只要下面有一条成立,它就值回价钱:
-- **不止一台机器**会用到这个项目——同事的检出、CI 任务、你的第二台笔记本——它们都应装出逐字节相同的技能。
-- **不止一个消费方**依赖这份声明——CI 必须证明已安装技能与声明的完全一致,被改过或篡改的技能会让构建失败。
-- **不止一个 agent**运行在同一台机器上——`.claude`、`.codex`、workbuddy……共用一套安装,各自持有自己的链接。
+- **不止一台机器**在做这个项目——同事的检出、CI、你的第二台笔记本——
+ 它们最后应该拿到同一套技能。
+- **需要有人证明这件事**——CI 检查已安装技能就是声明的那批,被改过、
+ 被篡改的技能会让构建失败。
+- **一台机器上跑着多个 agent**,它们共用一套安装,各自持有自己的链接。
| 你想做的事 | 用 |
| --- | --- |
| 把现有项目或机器纳入管理 | `init` |
| 从任意 Git 仓库添加一个技能 | `get` |
-| 让每台机器与声明完全一致 | `sync` |
-| 技能有漂移时让构建失败 | `verify` |
+| 让每台机器符合声明 | `sync` |
+| 技能漂移时让构建失败 | `verify` |
| 把已安装技能交给其他 agent | `share` |
-| 说明一个技能从哪来、现在什么状态 | `why` |
-| 升级到最新版本,或干净地退出 | `update` / `remove` |
-
-## 为什么需要它
-
-skill(指令 + 脚本的打包单元)决定 agent 的行为,但它的管理停留在前依赖管理时代。手工拷贝留不下"装了什么"的记录;git submodule 让每个使用方都要克隆整仓、用 git 才能拿到一个 Markdown 目录;各平台市场把技能装进机器本地状态,于是同事的 agent、CI 和你自己的笔记本会悄悄分叉。症状是相同的:同团队不同机器行为不一致、"当时用的是哪个版本"回答不了、内容被改过或篡改也无法察觉。
-
-skillmod 用 go mod 的同构方案解决:`SKILL.mod` 声明 + `SKILL.lock`(dirhash 内容寻址)锁定 + `skillmod sync` 幂等对齐。没有需要运维的 registry——发布一个 skill 就是在自己的仓库里打个 tag。
-
-## 你能得到什么
-
-- **每台机器拿到逐字节相同的技能。**
-- **"当时用的是哪个版本"有答案**——锁文件记录请求的版本、解析出的 commit 和内容哈希。
-- **改动与篡改会被发现**——`verify` 在漂移时以非零码退出,因此可以直接当作 CI 关卡。
-- **本地修改不会被静默覆盖**——被改过的安装会保留下来并以退出码 3 报告,把决定权交回给人。
-- **技能只取一次,之后复用**——同一仓库版本的不可变快照在整机共享,安装用链接而不是拷贝,第二个项目直接从磁盘安装。
-- **不需要额外基础设施**——无 registry、无服务端、无遥测,外部依赖只有 Git。
+| 查一个技能从哪来、现在什么状态 | `why` |
+| 升级到新版本,或干净地退出 | `update` / `remove` |
## 五分钟
```console
-$ skillmod get github.com/openai/skills//gh-fix-ci --install-mode=copy --yes
+$ skillmod get openai/skills//gh-fix-ci --install-mode=copy --yes
已安装 gh-fix-ci v0.0.0-20260624023612-49f948faa925,SKILL.mod 与 SKILL.lock 已更新
```
-仓库只写一次,技能名只写一次:`//` 后面直接用技能名即可,不需要记住或输入仓库内部的目录结构。精确存在的子目录仍然优先;同名技能有多个候选时,skillmod 会列出候选路径让用户选择,而不是自己猜。声明里记录的是技能真实所在的路径,也就是下面 `source` 那一行。
-
-`SKILL.mod` 是人维护、需要提交的声明;`SKILL.lock` 由 skillmod 写入,记录声明解析出的结果:
+主机名默认是 `github.com`,所以写 `owner/repo` 就够了;`//` 后面写技能名
+就能选中仓库里的技能,不需要知道它在仓库的哪个目录。确实存在的目录优先
+于名字;有多个技能同名时报出候选列表,不让它猜。无论技能实际在哪,
+`source` 记下来的都是真实路径:
```toml
# SKILL.mod —— 人维护
@@ -90,7 +86,8 @@ commit = '49f948faa9258a0c61caceaf225e179651397431'
dirhash = 'h1:kiGlVBeTCF8Q9f0rPATnDn1jBn/obT3TTTL8D8gdCbM='
```
-现在像"一次没人审查的修改"那样改动已安装的技能,再问项目是否仍与锁文件一致:
+现在改一下已安装的技能——就像一次没人审批的修改那样——再问项目是否还和
+锁文件一致:
```console
$ echo "先 rebase。" >> .agents/skills/gh-fix-ci/SKILL.md
@@ -101,7 +98,7 @@ $ echo $?
2
```
-`why` 解释这个条目的来源,以及它哪里不对:
+`why` 说明这个条目从哪来、哪里不对:
```console
$ skillmod why gh-fix-ci
@@ -111,7 +108,7 @@ gh-fix-ci(目录 gh-fix-ci):github.com/openai/skills//skills/.curated/gh-f
/tmp/agent-project/.agents/skills/gh-fix-ci:drift
```
-`sync` 不会为了让报告好看而丢掉这次修改:
+`sync` 不会为了报告好看丢掉这次修改:
```console
$ skillmod sync --yes
@@ -121,43 +118,50 @@ $ echo $?
3
```
-退出码 3 正是关键:能独立完成的工作已经完成,而关于这次修改的决定留给你。你可以把它当作项目的本地版本保留,也可以交互式运行 `skillmod sync` 并选择 *overwrite* 恢复锁定内容。
+退出码 3 正是关键:能独立完成的工作已经完成,这次修改怎么处置留给你。
+可以把它当作项目的本地版本留着,也可以交互式运行 `skillmod sync`,选择
+*overwrite* 恢复锁定的内容。
## 安装
### 使用 Agent 引导安装(推荐)
-准备好 Node.js/npm 后,全局安装仓库内附带的 Agent Skill,让编码 Agent 可以在任意项目中安装和使用 skillmod:
+准备好 Node.js 和 npm 后,全局安装仓库内附带的 Agent Skill,编码 Agent
+就能在任意项目里安装和使用 skillmod:
```bash
npx skills add huija/skillmod --skill skillmod --global
```
-然后告诉 Agent:
-
-```text
-安装 skillmod,并确保它可以从 PATH 调用。
-```
-
-该 Skill 会检查 Git 前置条件和已有的 skillmod 安装,识别当前操作系统与架构,选择对应的 Release Binary,使用发布的 SHA-256 校验和进行验证,将可执行文件安装到 `PATH` 中用户可写的目录,并验证安装结果。如果只希望当前项目使用这份引导,请省略 `--global`。
+然后让 Agent 把 skillmod 装好并加进 `PATH`。这个 Skill 会检查 Git 前置
+条件和已有的安装,识别当前操作系统与架构,选择对应的 Release 二进制,
+按发布的校验和验证后装进 `PATH` 能访问的目录,并验证安装结果。只希望
+当前项目用上这份引导时,去掉 `--global`。
### 手动安装
-不使用 Go 时,从 [GitHub Releases](https://github.com/huija/skillmod/releases) 下载对应平台的压缩包和 `checksums.txt`,校验压缩包后解压,并将 `skillmod` 放入 `PATH`。
+不用 Go 的话,从 [GitHub Releases](https://github.com/huija/skillmod/releases)
+下载对应平台的压缩包和 `checksums.txt`,校验后解压,把 `skillmod` 放进
+`PATH`。
-使用 Go 1.26.6 或更高版本:
+用 Go 1.26.6 或更高版本时:
```bash
go install github.com/huija/skillmod@latest
```
-无论用哪种方式安装,之后都可以用 `skillmod upgrade` 原地升级:它会先按发布校验和验证下载内容,再替换可执行文件。
+两种方式之后都可以用 `skillmod upgrade` 原地升级:先按发布校验和验证
+下载内容,再替换可执行文件。
-从仓库源码本地开发时,`make install` 会把二进制装到 `go env GOBIN`;未设置 `GOBIN` 时用第一个 `GOPATH/bin`,并写入当前 Git revision。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+本地开发时,`make install` 把二进制装到 `go env GOBIN`(未设置时用第一个
+`GOPATH/bin`),并写入当前 Git revision;详见
+[CONTRIBUTING.md](CONTRIBUTING.md)。
## 前置条件
-skillmod 通过系统 `git` 可执行文件获取源码,因此必须安装 Git 并加入 `PATH`(Windows 请安装 [Git for Windows](https://gitforwindows.org/),系统默认不带);SSH 远程地址还需要 `PATH` 中有 `ssh`。
+skillmod 通过系统的 `git` 获取技能,所以必须安装 Git 并加入 `PATH`
+(Windows 请安装 [Git for Windows](https://gitforwindows.org/),系统默认
+不带);SSH 远程地址还需要 `PATH` 里有 `ssh`。
## 常用命令
@@ -165,37 +169,67 @@ skillmod 通过系统 `git` 可执行文件获取源码,因此必须安装 Git
| --- | --- |
| `init` | 把磁盘上已有的技能登记进 `SKILL.mod` 和 `SKILL.lock` |
| `get <地址>` | 添加并安装一个技能 |
-| `sync` | 按锁文件对齐安装,幂等,且不会覆盖本地修改 |
+| `sync` | 按锁文件对齐安装;可以反复执行,且不会覆盖本地修改 |
| `share` | 把已安装技能链接到 agent 目录(如 `.claude`、`.codex`);见[分享给 agent](#分享给-agent) |
| `list` | 列出全部声明、版本和安装状态 |
| `why <选择器>` | 说明单个条目:来源、解析版本、commit、dirhash 和各目标状态 |
-| `update [选择器]` | 把条目更新到最新的不可变版本——最高标签优先,仅无标签仓库跟随 HEAD;拒绝标签锁的静默降级 |
+| `update [选择器]` | 把条目更新到最新的不可变版本——最高 tag 优先,只有无 tag 的仓库跟随 HEAD |
| `verify` | 校验已安装内容与锁文件是否一致,即 CI 关卡 |
-| `remove [选择器]` | 删除声明和内容未改动的受管安装;带 `--agent` 时仅解除这些 agent 的分享,保留技能 |
+| `remove [选择器]` | 删除声明和内容未改动的受管安装;带 `--agent` 时只解除这些 agent 的链接,保留技能 |
| `prune` | 清理手工编辑后残留的过期安装和锁记录 |
| `upgrade` | 用已发布的版本替换当前可执行文件,替换前按发布校验和验证 |
-`skillmod --global init` 登记用户在 `~/.agents/skills/` 里已有的技能;`skillmod init` 登记项目自身的技能。两次纳管相互独立、先后随意;两份清单也相互独立,因此只有带 `--global` 的命令才作用于机器级;两个作用域的完整流程见 [use-cases.md](skills/skillmod/references/use-cases.md)。
-
-所有命令都支持 `--json`(`-j`,机器可读输出)和 `--global`(`-g`,作用于用户级技能而非当前项目),写操作支持 `--dry-run`(`-n`)和 `--yes`(`-y`)。`get` 还支持 `--alias`(`-a`),`init` 支持 `--force`(`-f`),`sync` 支持 `--check`(`-c`)和 `--relink`(`-r`),`share` 支持 `--skill`(`-s`)、`--agent`(`-a`)和 `--remove`(`-r`),`remove` 支持 `--skill`(`-s`)和 `--agent`(`-a`),`upgrade` 支持 `--check`(`-c`)和 `--tag`(`-t`)。
-
-`get`、`remove` 和 `share` 支持 `--all`,用于直接指认整批目标而不进入询问:分别是仓库发布的全部技能、全部已声明条目、全部已安装技能。`--yes` 是这条分工的另一半——它只回答选择之后的确认,从不用来决定选择什么。`--all`、`--install-mode`、`--allow-downgrade` 与 `--on-conflict` 刻意不设短写:显而易见的字母会产生歧义或已被占用,且长写更易读。
-
-命令帮助、摘要、交互提示和错误信息优先采用 `SKILLMOD_LANG`,未设置时跟随系统 locale;JSON 的字段名和 action 标识不会翻译。
+`skillmod --global init` 登记用户在 `~/.agents/skills/` 里已有的技能;
+`skillmod init` 登记项目自身的技能。两个作用域相互独立——各自的清单,
+先后随意——所以只有带 `--global` 的命令才作用于整台机器。
+
+所有命令都支持 `--json`(`-j`)和 `--global`(`-g`);写操作支持
+`--dry-run`(`-n`)和 `--yes`(`-y`)。`get` 还支持 `--alias`(`-a`),
+`init` 支持 `--force`(`-f`),`sync` 支持 `--check`(`-c`)、
+`--relink`(`-r`)和 `--adopt`,`share` 支持 `--skill`(`-s`)、
+`--agent`(`-a`)和 `--remove`(`-r`),`remove` 支持 `--skill`(`-s`)
+和 `--agent`(`-a`),`upgrade` 支持 `--check`(`-c`)和 `--tag`(`-t`)。
+
+`--json` 只在 stdout 写一份机器可读的文档,其他什么都没有;命令失败时
+也一样——失败的那份带 `error` 字段,退出码不变。这个模式下不再输出人读的
+内容,脚本不必去分辨两种格式。`sync` 的 `--adopt` 处理 skillmod 之外新增的
+技能——npx 装的、拷贝来的、手动放的——把它们登记为本地条目,并用当前内容
+作为基线;文件本身一个字节都不会改。普通 `sync` 只提醒你有这些技能,并
+指出这个开关。
+
+`get`、`remove` 和 `share` 支持 `--all`,直接指认整批目标而不进入询问:
+分别是仓库发布的全部技能、全部已声明条目(传仓库时则是该仓库声明的全部
+条目)、全部已安装技能。`--yes` 是这条分工的另一半——它只回答选择之后的
+确认,从不用来决定选择什么。`--all`、`--install-mode`、
+`--allow-downgrade`、`--on-conflict` 和 `--adopt` 刻意不设短写:显而易见
+的字母会产生歧义或已被占用,且长写更易读。
+
+`get` 和 `remove` 都可以直接传仓库。`get owner/repo//name` 安装一个技能;
+`remove owner/repo` 列出这个仓库声明过的技能,让你像 `get` 选技能一样
+挑出要删的那些;加上 `--all` 则一次删光,无需终端,这是脚本表达"这个
+仓库带来的全部技能"的方式。
+
+命令帮助、交互提示、摘要和错误信息优先采用 `SKILLMOD_LANG`,未设置时跟随
+系统 locale;JSON 的字段名和 action 标识不会翻译。
## 分享给 agent
-agent 用一个目录段命名,并从 `.<名字>/skills` 读取技能,因此任意 agent 都可用——`.claude`、`.codex` 这样的知名名字和其他任意单段名字一视同仁。每个技能在自己的 `SKILL.mod` 条目上记录链接到的 agent 名,由 `sync` 在每台机器上重建链接:
+agent 用一个目录段命名,从 `.<名字>/skills` 读取技能,所以任意 agent 都能
+用——`.claude`、`.codex` 这样的知名名字和其他任意单段名字一视同仁。每个
+技能在自己的 `SKILL.mod` 条目上记录链接到哪些 agent,由 `sync` 在每台机器
+上重建链接:
```console
$ skillmod share --all --agent claude --agent workbuddy --yes
```
-`share --remove --agent <名称>` 解除分享并保留技能;`remove --agent <名称>` 只解除一个 agent 的链接,不影响其他 agent。
+`share --remove --agent <名称>` 解除分享并保留技能;
+`remove --agent <名称>` 只解除一个 agent 的链接,不影响其他 agent。
## 详细文档在哪
-这份 README 不再扩写成手册:具体规则放在操作 skillmod 的那个 Agent Skill 里,人和 agent 都可以读。**这些参考文档目前只有英文版。**
+这份 README 只当前门。具体规则放在操作 skillmod 的那个 Agent Skill 里,
+人和 agent 都可以读:
| 阅读 | 内容 |
| --- | --- |
diff --git a/docs_test.go b/docs_test.go
index 3e6f835..a9ce56f 100644
--- a/docs_test.go
+++ b/docs_test.go
@@ -31,11 +31,11 @@ var (
string(engine.CommandWhy),
}
documentedEntryActions = []string{
- engine.ActionConflict, engine.ActionDrift, engine.ActionInstall, engine.ActionInstalled,
- engine.ActionKeep, engine.ActionLocal, engine.ActionLocalDrift, engine.ActionMatched,
- engine.ActionMissing, engine.ActionPartial, engine.ActionPrune, engine.ActionRemove,
- engine.ActionSkip, engine.ActionStale, engine.ActionUnlocked, engine.ActionUnresolved,
- engine.ActionUnverifiable, engine.ActionUpdate,
+ engine.ActionAdopt, engine.ActionConflict, engine.ActionDrift, engine.ActionInstall,
+ engine.ActionInstalled, engine.ActionKeep, engine.ActionLocal, engine.ActionLocalDrift,
+ engine.ActionMatched, engine.ActionMissing, engine.ActionPartial, engine.ActionPrune,
+ engine.ActionRemove, engine.ActionSkip, engine.ActionStale, engine.ActionUnlocked,
+ engine.ActionUnresolved, engine.ActionUnverifiable, engine.ActionUpdate,
}
documentedTargetActions = []string{
engine.ActionDrift, engine.ActionInstall, engine.ActionInstalled, engine.ActionKeep,
diff --git a/internal/address/address.go b/internal/address/address.go
index 328a1ac..fe897b3 100644
--- a/internal/address/address.go
+++ b/internal/address/address.go
@@ -20,6 +20,10 @@ type Address struct {
Repo string // normalized Git address; bare paths include an https:// prefix
Subdir string // subdirectory within the repository; empty means the repository root
Ref string // explicit version reference; empty asks package resolve for the latest version
+ // Completed records that a bare owner/repo input was extended with the
+ // default host. The fetch failure of such an address names a URL the raw
+ // input never contained, so callers surface the resolution alongside it.
+ Completed bool
}
// String returns the canonical address.
@@ -37,6 +41,9 @@ func (a *Address) String() string {
// scpLike matches git@host:path addresses, where @ is not a version separator.
var scpLike = regexp.MustCompile(`^[^/@\s:]+@[^/@\s:]+:`)
+// defaultGitHubHost is the host a bare owner/repo path is resolved against.
+const defaultGitHubHost = "github.com"
+
// Parse validates and normalizes an address without accessing the network.
// Branch names are rejected later by package resolve using ls-remote data rather than string heuristics.
func Parse(raw string) (*Address, error) {
@@ -65,7 +72,7 @@ func Parse(raw string) (*Address, error) {
if strings.ContainsAny(repo, " \t") {
return nil, fmt.Errorf(i18n.Text("address.repository_whitespace"), repoaddr.Redact(repo))
}
- repo = normalizeRepo(repo)
+ repo, completed := normalizeRepo(repo)
repo, err = repoaddr.PersistedTransport(repo)
if err != nil {
return nil, err
@@ -76,7 +83,7 @@ func Parse(raw string) (*Address, error) {
return nil, err
}
}
- return &Address{Repo: repo, Subdir: subdir, Ref: ref}, nil
+ return &Address{Repo: repo, Subdir: subdir, Ref: ref, Completed: completed}, nil
}
// splitRef splits at the final @ that acts as a version separator. Explicit
@@ -122,11 +129,27 @@ func splitSubdir(s string) (repo, subdir string, err error) {
}
// normalizeRepo adds https:// to bare paths and preserves full URLs and scp-like addresses.
-func normalizeRepo(repo string) string {
+// A bare owner/repo path defaults to github.com, because that is where skill
+// repositories overwhelmingly live; a first segment that already carries a dot
+// is a host, and one that is empty, "." or ".." reads as a filesystem path.
+// Neither of those two takes the github.com default, though both still come
+// back with the https:// prefix that every bare path gains.
+// The second result reports whether that default was applied.
+func normalizeRepo(repo string) (string, bool) {
if strings.Contains(repo, "://") || scpLike.MatchString(repo) {
- return repo
+ return repo, false
+ }
+ if first, _, found := strings.Cut(repo, "/"); found {
+ switch {
+ case first == "" || first == "." || first == "..":
+ // A filesystem path, absolute or relative.
+ case strings.ContainsAny(first, ".:"):
+ // A host, possibly with a port, or a Windows drive letter.
+ default:
+ return "https://" + defaultGitHubHost + "/" + repo, true
+ }
}
- return "https://" + repo
+ return "https://" + repo, false
}
// ManifestSource returns the address form recorded in SKILL.mod and SKILL.lock.
diff --git a/internal/address/address_test.go b/internal/address/address_test.go
index 61eb640..546a97f 100644
--- a/internal/address/address_test.go
+++ b/internal/address/address_test.go
@@ -25,6 +25,18 @@ func TestParse(t *testing.T) {
{"bare repository with subdirectory", "github.com/a/b//sub", &Address{Repo: "https://github.com/a/b", Subdir: "sub"}, ""},
{"bare repository with subdirectory and version", "github.com/a/b//sub@v1.2.0", &Address{Repo: "https://github.com/a/b", Subdir: "sub", Ref: "v1.2.0"}, ""},
{"bare repository with version", "github.com/a/b@v1.2.0", &Address{Repo: "https://github.com/a/b", Ref: "v1.2.0"}, ""},
+ // A bare owner/repo path defaults to github.com, and the parse result
+ // records that the host was added, so a failed fetch can name it.
+ {"owner/repo defaults to github", "openai/skills", &Address{Repo: "https://github.com/openai/skills", Completed: true}, ""},
+ {"owner/repo with subdirectory", "openai/skills//gh-fix-ci", &Address{Repo: "https://github.com/openai/skills", Subdir: "gh-fix-ci", Completed: true}, ""},
+ {"owner/repo with version", "openai/skills@v1.0.0", &Address{Repo: "https://github.com/openai/skills", Ref: "v1.0.0", Completed: true}, ""},
+ // Any other first segment is a host, not an owner.
+ {"host with port", "localhost:8080/a/b", &Address{Repo: "https://localhost:8080/a/b"}, ""},
+ // A first segment that reads as a path is not an owner, so it is left
+ // alone rather than completed with a host that cannot exist.
+ {"relative current directory", "./a/b", &Address{Repo: "https://./a/b"}, ""},
+ {"relative parent directory", "../a/b", &Address{Repo: "https://../a/b"}, ""},
+ {"windows drive letter", "C:/x/y", &Address{Repo: "https://C:/x/y"}, ""},
// Preserve a complete URL.
{"https", "https://github.com/a/b", &Address{Repo: "https://github.com/a/b"}, ""},
{"https with subdirectory", "https://github.com/a/b//sub/dir@v2.0.0", &Address{Repo: "https://github.com/a/b", Subdir: "sub/dir", Ref: "v2.0.0"}, ""},
@@ -122,6 +134,8 @@ func TestManifestSource_DropsImpliedHTTPSAndKeepsExplicitTransports(t *testing.T
}{
{"bare path is already canonical", "github.com/a/b", "github.com/a/b"},
{"https prefix is not recorded", "https://github.com/a/b", "github.com/a/b"},
+ {"owner/repo records the default host", "openai/skills", "github.com/openai/skills"},
+ {"owner/repo with subdirectory", "openai/skills//gh-fix-ci", "github.com/openai/skills//gh-fix-ci"},
{"uppercase https prefix is not recorded", "HTTPS://github.com/a/b", "github.com/a/b"},
{"https with subdirectory", "https://github.com/a/b//sub/dir", "github.com/a/b//sub/dir"},
{"non-default port survives", "https://github.com:8443/a/b", "github.com:8443/a/b"},
diff --git a/internal/cli/get.go b/internal/cli/get.go
index 4da776c..5a0d185 100644
--- a/internal/cli/get.go
+++ b/internal/cli/get.go
@@ -28,7 +28,7 @@ func newGetCmd(options *rootOptions) *cobra.Command {
rep, err := eng.Get(cmd.Context(), args[0], alias, options.newIO(cmd), engine.GetOptions{
All: all, DryRun: options.dryRun,
})
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
cmd.Flags().StringVarP(&alias, "alias", "a", "", i18n.Text("cli.get.flag_alias"))
diff --git a/internal/cli/global_test.go b/internal/cli/global_test.go
index da91a4e..b5b3452 100644
--- a/internal/cli/global_test.go
+++ b/internal/cli/global_test.go
@@ -5,11 +5,14 @@
package cli
import (
+ "bytes"
+ "encoding/json"
"io"
"os"
"path/filepath"
"testing"
+ "github.com/huija/skillmod/internal/engine"
"github.com/huija/skillmod/internal/modfile"
)
@@ -87,3 +90,51 @@ func TestInstallModeOverrideAndRelinkFlags(t *testing.T) {
t.Error("sync accepted --check and --relink together")
}
}
+
+// TestSyncAdoptFlagWiring pins the flag end to end: sync --adopt declares a
+// locally added skill, and --check refuses the combination instead of
+// silently ignoring it.
+func TestSyncAdoptFlagWiring(t *testing.T) {
+ project, _ := isolateCLI(t)
+ // An empty declaration, so the skill on disk is genuinely undeclared when
+ // sync runs.
+ if err := modfile.SaveState(project,
+ &modfile.Mod{SchemaVersion: modfile.SchemaVersion},
+ &modfile.Lock{SchemaVersion: modfile.SchemaVersion}); err != nil {
+ t.Fatal(err)
+ }
+ writeInstalledSkill(t, project, "hello")
+ cmd := NewRootCmd()
+ cmd.SetOut(io.Discard)
+ cmd.SetErr(io.Discard)
+ cmd.SetArgs([]string{"sync", "--check", "--adopt", "--yes"})
+ if err := cmd.Execute(); err == nil {
+ t.Error("sync accepted --check with --adopt")
+ }
+
+ cmd = NewRootCmd()
+ var out bytes.Buffer
+ cmd.SetOut(&out)
+ cmd.SetErr(io.Discard)
+ cmd.SetArgs([]string{"--json", "sync", "--adopt", "--yes"})
+ if err := cmd.Execute(); err != nil {
+ t.Fatalf("Execute(sync --adopt --yes) = %v", err)
+ }
+ var rep engine.Report
+ if err := json.Unmarshal(out.Bytes(), &rep); err != nil {
+ t.Fatalf("sync --adopt --json output = %q: %v", out.String(), err)
+ }
+ if len(rep.Entries) != 1 || rep.Entries[0].Action != engine.ActionAdopt {
+ t.Fatalf("sync --adopt report = %+v, want one adopted local entry", rep.Entries)
+ }
+ m, err := modfile.LoadMod(project)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(m.Skills) != 1 || !m.Skills[0].Local {
+ t.Errorf("declarations after sync --adopt = %+v, want one local entry", m.Skills)
+ }
+ if _, err := os.Stat(filepath.Join(project, ".agents", "skills", "hello", "SKILL.md")); err != nil {
+ t.Errorf("adopted skill lost its content: %v", err)
+ }
+}
diff --git a/internal/cli/init.go b/internal/cli/init.go
index f25f3a1..bef5c4a 100644
--- a/internal/cli/init.go
+++ b/internal/cli/init.go
@@ -24,7 +24,7 @@ func newInitCmd(options *rootOptions) *cobra.Command {
return err
}
rep, err := eng.Init(cmd.Context(), force, options.newIO(cmd), options.mutationOptions())
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
cmd.Flags().BoolVarP(&force, "force", "f", false, i18n.Text("cli.init.flag_force"))
diff --git a/internal/cli/list.go b/internal/cli/list.go
index eeb363a..0105093 100644
--- a/internal/cli/list.go
+++ b/internal/cli/list.go
@@ -22,7 +22,7 @@ func newListCmd(options *rootOptions) *cobra.Command {
return err
}
rep, err := eng.List(cmd.Context(), options.newIO(cmd))
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
}
diff --git a/internal/cli/prune.go b/internal/cli/prune.go
index d1040c2..c3b312b 100644
--- a/internal/cli/prune.go
+++ b/internal/cli/prune.go
@@ -22,7 +22,7 @@ func newPruneCmd(options *rootOptions) *cobra.Command {
return err
}
rep, err := eng.Prune(cmd.Context(), options.newIO(cmd), options.mutationOptions())
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
}
diff --git a/internal/cli/remove.go b/internal/cli/remove.go
index 38befe0..95038f9 100644
--- a/internal/cli/remove.go
+++ b/internal/cli/remove.go
@@ -38,7 +38,7 @@ func newRemoveCmd(options *rootOptions) *cobra.Command {
rep, err := eng.Remove(cmd.Context(), names, options.newIO(cmd), engine.RemoveOptions{
All: all, DryRun: options.dryRun, Agents: targets,
})
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
cmd.Flags().BoolVar(&all, "all", false, i18n.Text("cli.remove.flag_all"))
diff --git a/internal/cli/root.go b/internal/cli/root.go
index 22e3a18..1c2a3bd 100644
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -10,6 +10,7 @@ import (
"encoding/json"
"errors"
"fmt"
+ "io"
"os"
"path/filepath"
@@ -48,6 +49,14 @@ type rootOptions struct {
// NewRootCmd assembles the root command and all subcommands.
func NewRootCmd() *cobra.Command {
+ root, _ := newRootCmd()
+ return root
+}
+
+// newRootCmd assembles the command tree and returns the flag state it owns, so
+// the entry point can tell a --json run from a plain one when a handler fails
+// before it reaches output.
+func newRootCmd() (*cobra.Command, *rootOptions) {
options := &rootOptions{}
root := &cobra.Command{
Use: "skillmod",
@@ -56,6 +65,12 @@ func NewRootCmd() *cobra.Command {
Long: i18n.Text("cli.root.long"),
SilenceUsage: true,
SilenceErrors: true,
+ // Cobra parses the flags and resolves the subcommand before this runs,
+ // so recording the command here is what separates a failure inside a
+ // handler from one raised while parsing flags.
+ PersistentPreRun: func(cmd *cobra.Command, _ []string) {
+ handlerCmd = cmd
+ },
}
// The persistent flags that appear on ordinary commands carry a one-letter
// shorthand. --install-mode deliberately has none: "m" collides with the
@@ -81,24 +96,62 @@ func NewRootCmd() *cobra.Command {
newVerifyCmd(options),
newUpgradeCmd(options),
)
- return root
+ return root, options
}
// Execute runs the root command and maps errors to exit codes.
func Execute() int {
- if err := NewRootCmd().Execute(); err != nil {
+ root, options := newRootCmd()
+ return execute(root, options)
+}
+
+// execute runs one command tree. It is separate from Execute so a test can
+// point the tree at its own buffer and still exercise the failure paths.
+func execute(root *cobra.Command, options *rootOptions) int {
+ jsonEmitted = false
+ handlerCmd = nil
+ if err := root.Execute(); err != nil {
code := exitCode(err)
// Drift and partial completion are expected operational outcomes. Their
- // commands already emitted a human summary (or a JSON report), so only
- // unexpected failures need an additional stderr diagnostic here.
- if code == ExitError {
- fmt.Fprintln(os.Stderr, err)
+ // commands already emitted a report — a JSON document under --json, a
+ // human summary otherwise — so only unexpected failures need an
+ // additional stderr diagnostic here.
+ if code == ExitError && !jsonEmitted {
+ // A handler that returns before reaching output — newEngine
+ // failing is the case — still owes --json its single document, so
+ // the same shape is written from here. A flag error reaches no
+ // handler and keeps the plain stderr text its contract documents.
+ if options.json && handlerCmd != nil {
+ if writeErr := options.output(handlerCmd, nil, err); writeErr != nil {
+ fmt.Fprintln(os.Stderr, writeErr)
+ }
+ }
+ if !jsonEmitted {
+ fmt.Fprintln(os.Stderr, err)
+ }
}
return code
}
return ExitOK
}
+// jsonEmitted records whether the current run already wrote its JSON document
+// to stdout. It is reset per Execute call and set by output; a flag-parse or
+// argument error, which no command handler reaches, stays plain text on
+// stderr because no document was written.
+//
+// Known limitation: this is package-level state, so concurrent Execute calls
+// in one process would race on it. The binary calls Execute exactly once per
+// process, which is the only supported pattern; threading the flag through
+// RunE's error return would couple every command to it for no gain.
+var jsonEmitted bool
+
+// handlerCmd records the command cobra actually reached, which separates a
+// failure raised inside a command handler from one cobra raised while parsing
+// flags. Only the former owes --json a document. It is reset per Execute call
+// and carries the same single-call limitation as jsonEmitted.
+var handlerCmd *cobra.Command
+
func exitCode(err error) int {
var outputErr *outputError
if errors.As(err, &outputErr) {
@@ -155,24 +208,26 @@ func (options *rootOptions) newEngine() (*engine.Engine, error) {
}
// newIO configures I/O channels from global flags and terminal state.
-// In --json mode stdout must carry only the machine-readable report, so
-// human-readable engine summaries are routed to stderr.
+// In --json mode stdout carries only the machine-readable report, so every
+// human-readable channel is closed: engine summaries go nowhere and the
+// animated progress has no writer. Prompts still reach the terminal through
+// stderr, because a person who asked for JSON in a terminal still has to
+// answer them.
func (options *rootOptions) newIO(cmd *cobra.Command) engine.IO {
- out := cmd.OutOrStdout()
- if options.json {
- out = cmd.ErrOrStderr()
- }
- io := engine.IO{
- Out: out,
+ channels := engine.IO{
+ Out: cmd.OutOrStdout(),
Yes: options.yes,
}
+ if options.json {
+ channels.Out = io.Discard
+ }
if isTerminal(os.Stdin) {
- io.Confirm = ui.Interactive(os.Stdin, cmd.ErrOrStderr())
+ channels.Confirm = ui.Interactive(os.Stdin, cmd.ErrOrStderr())
}
- if isTerminal(os.Stderr) {
- io.Progress = ui.AnimatedProgress(cmd.ErrOrStderr())
+ if !options.json && isTerminal(os.Stderr) {
+ channels.Progress = ui.AnimatedProgress(cmd.ErrOrStderr())
}
- return io
+ return channels
}
func (options *rootOptions) mutationOptions() engine.MutationOptions {
@@ -184,19 +239,28 @@ func isTerminal(f *os.File) bool {
return term.IsTerminal(int(f.Fd()))
}
-// output renders structured JSON for --json; otherwise the engine has already printed a summary.
-func (options *rootOptions) output(cmd *cobra.Command, rep *engine.Report) error {
- if !options.json || rep == nil {
+// output renders structured JSON for --json; otherwise the engine has already
+// printed a human summary. A failing run still emits exactly one document: the
+// report describes whatever completed, and the error names why the command
+// stopped, so a job that parses --json never faces an empty stdout.
+func (options *rootOptions) output(cmd *cobra.Command, rep *engine.Report, err error) error {
+ if !options.json || rep == nil && err == nil {
return nil
}
- data, err := json.MarshalIndent(rep, "", " ")
- if err != nil {
- return &outputError{err: err}
+ if rep == nil {
+ rep = &engine.Report{Action: engine.Command(cmd.Name())}
}
- _, err = fmt.Fprintln(cmd.OutOrStdout(), string(data))
if err != nil {
- return &outputError{err: err}
+ rep.Error = err.Error()
+ }
+ data, marshalErr := json.MarshalIndent(rep, "", " ")
+ if marshalErr != nil {
+ return &outputError{err: marshalErr}
+ }
+ if _, writeErr := fmt.Fprintln(cmd.OutOrStdout(), string(data)); writeErr != nil {
+ return &outputError{err: writeErr}
}
+ jsonEmitted = true
return nil
}
diff --git a/internal/cli/root_test.go b/internal/cli/root_test.go
index 5435900..809db53 100644
--- a/internal/cli/root_test.go
+++ b/internal/cli/root_test.go
@@ -102,8 +102,11 @@ func TestNewEngineAndIO(t *testing.T) {
}
options.json = true
got = options.newIO(cmd)
- if got.Out != &stderr {
- t.Fatalf("--json must route engine summaries to stderr; newIO = %+v", got)
+ if got.Out != io.Discard {
+ t.Fatalf("--json must discard engine summaries; newIO.Out = %+v", got.Out)
+ }
+ if got.Progress != nil {
+ t.Fatal("--json must not attach an interactive progress writer")
}
}
@@ -113,7 +116,7 @@ func TestOutputJSON(t *testing.T) {
var out bytes.Buffer
cmd.SetOut(&out)
rep := &engine.Report{Action: engine.CommandVerify, Entries: []engine.EntryReport{{Name: "demo", Action: engine.ActionInstalled}}}
- if err := options.output(cmd, rep); err != nil {
+ if err := options.output(cmd, rep, nil); err != nil {
t.Fatal(err)
}
var got engine.Report
@@ -126,15 +129,72 @@ func TestOutputJSON(t *testing.T) {
out.Reset()
options.json = false
- if err := options.output(cmd, rep); err != nil || out.Len() != 0 {
+ if err := options.output(cmd, rep, nil); err != nil || out.Len() != 0 {
t.Fatalf("plain output = %q, err = %v", out.String(), err)
}
options.json = true
- if err := options.output(cmd, nil); err != nil || out.Len() != 0 {
+ if err := options.output(cmd, nil, nil); err != nil || out.Len() != 0 {
t.Fatalf("nil report output = %q, err = %v", out.String(), err)
}
}
+// TestOutputJSONOnError pins the contract that makes --json usable in
+// automation: a failing run still writes exactly one document, naming the
+// failure, and the human error stays off stdout.
+func TestOutputJSONOnError(t *testing.T) {
+ options := &rootOptions{json: true}
+ root := NewRootCmd()
+ verify, _, err := root.Find([]string{"verify"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ var out bytes.Buffer
+ verify.SetOut(&out)
+
+ failure := errors.New("no SKILL.mod found")
+ // jsonEmitted is the signal execute reads to decide whether a stderr
+ // diagnostic is still owed, and execute is what resets it. Both directions
+ // are asserted from a known starting state, so neither depends on which
+ // test happened to run first.
+ jsonEmitted = false
+ options.json = false
+ if err := options.output(verify, nil, failure); err != nil {
+ t.Fatal(err)
+ }
+ if jsonEmitted {
+ t.Fatal("a plain run recorded that it emitted a JSON document")
+ }
+
+ options.json = true
+ if err := options.output(verify, nil, failure); err != nil {
+ t.Fatal(err)
+ }
+ var got engine.Report
+ if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+ t.Fatalf("error output is not JSON: %v\n%s", err, out.String())
+ }
+ if got.Action != engine.CommandVerify || got.Error != failure.Error() {
+ t.Fatalf("error report = %+v, want action %q and error %q", got, engine.CommandVerify, failure.Error())
+ }
+ if !jsonEmitted {
+ t.Fatal("output did not record that it emitted a document")
+ }
+
+ // A report that completed alongside an error keeps its entries and carries
+ // the reason the command failed.
+ out.Reset()
+ rep := &engine.Report{Action: engine.CommandSync, Entries: []engine.EntryReport{{Name: "demo", Action: engine.ActionInstall}}}
+ if err := options.output(verify, rep, &engine.PartialError{Report: rep}); err != nil {
+ t.Fatal(err)
+ }
+ if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+ t.Fatalf("partial output is not JSON: %v\n%s", err, out.String())
+ }
+ if len(got.Entries) != 1 || got.Error == "" {
+ t.Fatalf("partial report = %+v, want the entries and the error", got)
+ }
+}
+
func TestJSONCommandsReturnOutputErrors(t *testing.T) {
project, _ := isolateCLI(t)
if err := modfile.SaveMod(project, &modfile.Mod{SchemaVersion: modfile.SchemaVersion}); err != nil {
@@ -157,6 +217,78 @@ func TestJSONCommandsReturnOutputErrors(t *testing.T) {
}
}
+// TestJSONFallbackDocumentForHandlerFailures pins the other half of the
+// single-document contract: a handler that fails before reaching output — an
+// unknown --install-mode is the reachable case, because its validation lives
+// in newEngine rather than in a cobra flag — still writes the document, while
+// a flag error, which reaches no handler at all, keeps its plain stderr text.
+func TestJSONFallbackDocumentForHandlerFailures(t *testing.T) {
+ project, _ := isolateCLI(t)
+ if err := modfile.SaveState(project,
+ &modfile.Mod{SchemaVersion: modfile.SchemaVersion},
+ &modfile.Lock{SchemaVersion: modfile.SchemaVersion}); err != nil {
+ t.Fatal(err)
+ }
+
+ run := func(args ...string) (code int, stdout, stderr string) {
+ t.Helper()
+ cmd, options := newRootCmd()
+ var out, errOut bytes.Buffer
+ cmd.SetOut(&out)
+ cmd.SetErr(&errOut)
+ cmd.SetArgs(args)
+ return execute(cmd, options), out.String(), errOut.String()
+ }
+
+ code, stdout, stderr := run("--json", "--install-mode", "bogus", "list")
+ if code != ExitError {
+ t.Fatalf("handler failure exit code = %d, want %d", code, ExitError)
+ }
+ var rep struct {
+ Action string `json:"action"`
+ Entries []any `json:"entries"`
+ Error string `json:"error"`
+ }
+ if err := json.Unmarshal([]byte(stdout), &rep); err != nil {
+ t.Fatalf("stdout is not exactly one JSON document: %v\n%s", err, stdout)
+ }
+ if rep.Action != "list" || rep.Error == "" {
+ t.Errorf("document = %+v, want the list action and the failure named", rep)
+ }
+ if rep.Entries == nil {
+ t.Errorf("document = %s, want an entries array", stdout)
+ }
+ if stderr != "" {
+ t.Errorf("stderr = %q, want the document to carry the failure", stderr)
+ }
+
+ // A flag error never reaches a handler, so it stays plain text with an
+ // empty stdout — the contract the document explicitly exempts. The
+ // diagnostic goes to the process's stderr, so it is captured there rather
+ // than from the cobra buffer.
+ oldStderr := os.Stderr
+ pipe, write, pipeErr := os.Pipe()
+ if pipeErr != nil {
+ t.Fatal(pipeErr)
+ }
+ os.Stderr = write
+ code, stdout, _ = run("--json", "--no-such-flag", "list")
+ os.Stderr = oldStderr
+ if closeErr := write.Close(); closeErr != nil {
+ t.Fatal(closeErr)
+ }
+ diagnostic, readErr := io.ReadAll(pipe)
+ if readErr != nil {
+ t.Fatal(readErr)
+ }
+ if code != ExitError || stdout != "" {
+ t.Errorf("flag error: code = %d, stdout = %q, want a plain failure", code, stdout)
+ }
+ if !strings.Contains(string(diagnostic), "no-such-flag") {
+ t.Errorf("flag error stderr = %q, want the flag named", diagnostic)
+ }
+}
+
func TestRootCommandsDoNotShareFlagState(t *testing.T) {
project, _ := isolateCLI(t)
if err := modfile.SaveState(project,
@@ -212,6 +344,7 @@ func TestFlagsCarryShorthands(t *testing.T) {
"allow-downgrade": "it overrides a safety check",
"all": "the letter is taken by --agent, and the long form reads better",
"on-conflict": "the policy names are long; a letter would hide the meaning",
+ "adopt": "it is typed rarely, and a letter would not say what it adopts",
}
root := NewRootCmd()
check := func(cmd *cobra.Command) {
diff --git a/internal/cli/share.go b/internal/cli/share.go
index 8741fb6..c602c59 100644
--- a/internal/cli/share.go
+++ b/internal/cli/share.go
@@ -53,7 +53,7 @@ func newShareCmd(options *rootOptions) *cobra.Command {
share.Remove, share.Agents = targets, nil
}
rep, err := eng.Share(cmd.Context(), share, options.newIO(cmd), options.mutationOptions())
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
cmd.Flags().StringArrayVarP(&skills, "skill", "s", nil, i18n.Text("cli.share.flag_skill"))
diff --git a/internal/cli/sync.go b/internal/cli/sync.go
index bd5b366..ad108cc 100644
--- a/internal/cli/sync.go
+++ b/internal/cli/sync.go
@@ -13,7 +13,7 @@ import (
)
func newSyncCmd(options *rootOptions) *cobra.Command {
- var check, relink bool
+ var check, relink, adopt bool
cmd := &cobra.Command{
Use: "sync",
Short: i18n.Text("cli.sync.short"),
@@ -25,13 +25,14 @@ func newSyncCmd(options *rootOptions) *cobra.Command {
return err
}
rep, err := eng.Sync(cmd.Context(), engine.SyncOptions{
- CheckOnly: check, Relink: relink, DryRun: options.dryRun,
+ CheckOnly: check, Relink: relink, Adopt: adopt, DryRun: options.dryRun,
}, options.newIO(cmd))
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
cmd.Flags().BoolVarP(&check, "check", "c", false, i18n.Text("cli.sync.flag_check"))
cmd.Flags().BoolVarP(&relink, "relink", "r", false, i18n.Text("cli.sync.flag_relink"))
+ cmd.Flags().BoolVar(&adopt, "adopt", false, i18n.Text("cli.sync.flag_adopt"))
cmd.MarkFlagsMutuallyExclusive("check", "relink")
return cmd
}
diff --git a/internal/cli/update.go b/internal/cli/update.go
index f8daa57..9cd38e7 100644
--- a/internal/cli/update.go
+++ b/internal/cli/update.go
@@ -26,7 +26,7 @@ func newUpdateCmd(options *rootOptions) *cobra.Command {
rep, err := eng.Update(cmd.Context(), args, engine.UpdateOptions{
AllowDowngrade: allowDowngrade, DryRun: options.dryRun,
}, options.newIO(cmd))
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
// --allow-downgrade deliberately has no shorthand: it overrides a safety
diff --git a/internal/cli/upgrade.go b/internal/cli/upgrade.go
index 9e02d34..0c3cafe 100644
--- a/internal/cli/upgrade.go
+++ b/internal/cli/upgrade.go
@@ -58,9 +58,9 @@ func (options *rootOptions) upgrade(cmd *cobra.Command, tag string, check bool)
// is skipped on failure, where Execute reports the error instead.
rep := upgradeReport(result, target, options.dryRun, err != nil)
if err != nil {
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
}
- return errors.Join(options.output(cmd, rep), reportUpgrade(rep, io, result, options.dryRun))
+ return errors.Join(options.output(cmd, rep, nil), reportUpgrade(rep, io, result, options.dryRun))
}
// upgradeReport renders one upgrade attempt as a report entry. The action
diff --git a/internal/cli/verify.go b/internal/cli/verify.go
index 5d87d15..a36d02c 100644
--- a/internal/cli/verify.go
+++ b/internal/cli/verify.go
@@ -23,7 +23,7 @@ func newVerifyCmd(options *rootOptions) *cobra.Command {
return err
}
rep, err := eng.Verify(cmd.Context(), options.newIO(cmd))
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
}
diff --git a/internal/cli/why.go b/internal/cli/why.go
index 2b5b912..0966040 100644
--- a/internal/cli/why.go
+++ b/internal/cli/why.go
@@ -22,7 +22,7 @@ func newWhyCmd(options *rootOptions) *cobra.Command {
return err
}
rep, err := eng.Why(cmd.Context(), args[0], options.newIO(cmd))
- return errors.Join(err, options.output(cmd, rep))
+ return errors.Join(err, options.output(cmd, rep, err))
},
}
}
diff --git a/internal/engine/adopt.go b/internal/engine/adopt.go
new file mode 100644
index 0000000..1765b76
--- /dev/null
+++ b/internal/engine/adopt.go
@@ -0,0 +1,185 @@
+// Copyright 2026 huija
+//
+// SPDX-License-Identifier: MIT
+
+package engine
+
+import (
+ "errors"
+ "fmt"
+ "io/fs"
+ "os"
+ "path/filepath"
+
+ "github.com/huija/skillmod/internal/dirhash"
+ "github.com/huija/skillmod/internal/fsutil"
+ "github.com/huija/skillmod/internal/i18n"
+ "github.com/huija/skillmod/internal/modfile"
+ "github.com/huija/skillmod/internal/source"
+)
+
+// adoptCandidate is one skill directory in the installation directory that
+// neither SKILL.mod nor SKILL.lock knows about.
+type adoptCandidate struct {
+ dirName string // directory name, which becomes the installation directory
+ name string // frontmatter name, or the directory name when it is unreadable
+ dir string
+ hash string // baseline dirhash recorded in the lock
+ note string // extra provenance to report with the entry
+}
+
+// reconcileUndeclaredSkills takes stock of the skill directories that exist on
+// disk but in neither SKILL.mod nor SKILL.lock — the skills another tool such
+// as npx, or a manual copy, put there. With adopt set, each one becomes a
+// local declaration, which is what init does for a machine's existing skills.
+// Content is never written: an adopted skill keeps exactly the files it has,
+// and its lock record is the hash of those files, so a later edit shows up as
+// local drift instead of being silently reset. Without adopt the scan only
+// leaves a hint naming the flag, so the feature is discoverable from the
+// command that would otherwise ignore those skills. A dry run plans the
+// adoption but never asks: printing the plan must not block on a prompt, so
+// every candidate is listed as pending and the notes say how a real run
+// proceeds.
+func (e *Engine) reconcileUndeclaredSkills(adopt, dryRun bool, m, newMod *modfile.Mod, lock, newLock *modfile.Lock, io IO, rep *Report) (int, error) {
+ candidates, skipped, err := e.undeclaredSkillDirs(m, lock)
+ if err != nil {
+ return 0, err
+ }
+ rep.Notes = append(rep.Notes, skipped...)
+ if len(candidates) == 0 {
+ return 0, nil
+ }
+ if !adopt {
+ hint := i18n.Format("engine.sync.undeclared_skills_found", len(candidates))
+ if writeErr := io.printf("%s", hint); writeErr != nil {
+ return 0, writeErr
+ }
+ rep.Notes = append(rep.Notes, hint)
+ return 0, nil
+ }
+ if !dryRun && !io.Yes {
+ // The confirmation per skill is the one init asks, for the same reason:
+ // provenance is being recorded, and a run with no channel to ask
+ // through is told how to state the intent instead of guessing it.
+ if io.Confirm == nil {
+ return 0, fmt.Errorf("%s", i18n.Format("engine.sync.adopt_needs_confirmation", len(candidates)))
+ }
+ var kept []adoptCandidate
+ for _, candidate := range candidates {
+ confirmed, confirmErr := io.Confirm.Confirm(i18n.Format("engine.sync.adopt_confirm", candidate.name, candidate.dir))
+ if confirmErr != nil {
+ return 0, confirmErr
+ }
+ if confirmed {
+ kept = append(kept, candidate)
+ }
+ }
+ if len(kept) == 0 {
+ return 0, fmt.Errorf("%s", i18n.Text("engine.sync.no_skills_adopted"))
+ }
+ candidates = kept
+ }
+
+ adopted := 0
+ for _, candidate := range candidates {
+ alias := ""
+ if candidate.dirName != candidate.name {
+ alias = candidate.dirName
+ }
+ newMod.Skills = append(newMod.Skills, modfile.ModSkill{Name: candidate.name, Alias: alias, Local: true})
+ upsertLock(newLock, modfile.LockSkill{Name: candidate.name, Dirhash: candidate.hash, Dir: alias})
+ note := i18n.Text("engine.sync.adopted_local_entry")
+ if dryRun {
+ note = i18n.Text("engine.sync.adopt_dry_run_entry")
+ }
+ // The action names the adoption rather than the steady state the entry
+ // reaches afterwards: a report says what this run did, the next sync
+ // sees an ordinary local entry, and a --json consumer can tell a
+ // planned adoption from an existing local entry inside one document —
+ // which reading the note would have required.
+ entry := EntryReport{Name: candidate.name, Directory: candidate.dirName, Action: ActionAdopt, Note: note}
+ entry.Note = appendNote(entry.Note, candidate.note)
+ rep.Entries = append(rep.Entries, entry)
+ if err := io.printf(" %s: %s", candidate.name, entry.Note); err != nil {
+ return adopted, err
+ }
+ adopted++
+ }
+ if dryRun && !io.Yes {
+ // A dry run lists every candidate without asking, so the notes must
+ // say how the real run turns the plan into declarations.
+ rep.Notes = append(rep.Notes, i18n.Text("engine.sync.adopt_dry_run_confirm"))
+ }
+ return adopted, nil
+}
+
+// undeclaredSkillDirs scans the installation directory for skill directories
+// that neither the declaration nor the lock records. Unreadable directories,
+// and directories whose name cannot be an installation directory, are reported
+// as skipped notes instead of failing the whole sync, which keeps one broken
+// skill from blocking every other entry.
+func (e *Engine) undeclaredSkillDirs(m *modfile.Mod, lock *modfile.Lock) (candidates []adoptCandidate, skipped []string, err error) {
+ base := e.skillsDir()
+ dents, readErr := os.ReadDir(base)
+ if errors.Is(readErr, fs.ErrNotExist) {
+ return nil, nil, nil
+ }
+ if readErr != nil {
+ return nil, nil, readErr
+ }
+ declared := make(map[string]bool, len(m.Skills))
+ for _, skill := range m.Skills {
+ declared[fsutil.FoldKey(skill.DirName())] = true
+ }
+ locked := make(map[string]bool, len(lock.Skills))
+ for _, lk := range lock.Skills {
+ locked[fsutil.FoldKey(lk.InstallDir())] = true
+ }
+ folded := make(map[string]string, len(dents))
+ for _, dent := range dents {
+ dir := filepath.Join(base, dent.Name())
+ // os.Stat follows a symlinked skill directory the way init does, so a
+ // link that points at real content is adopted rather than skipped.
+ st, statErr := os.Stat(dir)
+ if statErr != nil || !st.IsDir() {
+ continue
+ }
+ if !hasSkillManifest(dir) {
+ continue
+ }
+ key := fsutil.FoldKey(dent.Name())
+ if declared[key] || locked[key] {
+ continue // Managed already, by a declaration or a stale lock record.
+ }
+ if previous, duplicate := folded[key]; duplicate {
+ // Two directories that differ only in letter case map to one
+ // installation directory on Windows and macOS; adopting both would
+ // write a declaration no other machine can materialize.
+ return nil, nil, fmt.Errorf(i18n.Text("engine.sync.adopt_case_collision"), previous, dent.Name())
+ }
+ folded[key] = dent.Name()
+
+ candidate := adoptCandidate{dirName: dent.Name(), dir: dir}
+ name, nameErr := source.SkillNameFromDir(dir)
+ switch {
+ case nameErr == nil:
+ candidate.name = name
+ case fsutil.ValidName(dent.Name()) == nil:
+ // An unreadable SKILL.md is still adopted under the directory name,
+ // which is the only identity the filesystem guarantees.
+ candidate.name = dent.Name()
+ candidate.note = i18n.Text("engine.init.failed_parse_skill_md")
+ default:
+ skipped = append(skipped, i18n.Format("engine.sync.adopt_skipped", dir, nameErr))
+ continue
+ }
+ hash, hashErr := dirhash.HashDir(dir)
+ if hashErr != nil {
+ skipped = append(skipped, i18n.Format("engine.sync.adopt_skipped", dir, hashErr))
+ continue
+ }
+ candidate.hash = hash
+ candidates = append(candidates, candidate)
+ }
+ return candidates, skipped, nil
+}
diff --git a/internal/engine/engine.go b/internal/engine/engine.go
index 1521a86..f9cb9fc 100644
--- a/internal/engine/engine.go
+++ b/internal/engine/engine.go
@@ -149,6 +149,16 @@ func (e *Engine) saveState(m *modfile.Mod, lock *modfile.Lock) error {
func (e *Engine) loadMod() (*modfile.Mod, error) {
m, err := modfile.LoadMod(e.manifestRoot())
if os.IsNotExist(err) {
+ // The advice differs by scope because the recovery paths differ. A
+ // project without a manifest usually means the user is standing in
+ // the wrong directory — most often $HOME, whose installation
+ // directories are the global scope's — so the project message offers
+ // --global as the likely intent before suggesting init. The global
+ // scope has exactly one recovery path, spelled with the same flag
+ // that selects it.
+ if e.ManifestRoot != "" {
+ return nil, fmt.Errorf("%s", i18n.Text("engine.skill_mod_found_advice_global"))
+ }
return nil, fmt.Errorf("%s", i18n.Text("engine.skill_mod_found_advice"))
}
return m, err
@@ -611,8 +621,8 @@ func (e *Engine) resolveAndFetch(ctx context.Context, repo, subdir, ref string,
// ls-remote returns repository-wide refs. If another subdirectory already queried the same repository,
// an exact tag can reuse that snapshot, while latest and update still force a remote refresh.
if !resolve.IsPseudoVersion(ref) {
- if cachedRefs, ok, _ := e.Store.GetRepoRefs(repo); ok {
- cachedRes, resolveErr := resolve.Resolve(resolve.Request{Repo: repo, Subdir: subdir, Ref: ref}, cachedRefs)
+ if cached, ok, _ := e.Store.GetRepoRefs(repo); ok {
+ cachedRes, resolveErr := resolve.Resolve(resolve.Request{Repo: repo, Subdir: subdir, Ref: ref}, cached.Refs)
// For a monorepo, trust only the highest-priority /[ match.
// A cached root-tag match may be stale if the remote later added a more specific subdirectory tag.
cacheHit := resolveErr == nil && cachedRes.Kind == resolve.KindTag &&
diff --git a/internal/engine/engine_internal_test.go b/internal/engine/engine_internal_test.go
index d557cba..184aa7d 100644
--- a/internal/engine/engine_internal_test.go
+++ b/internal/engine/engine_internal_test.go
@@ -6,7 +6,11 @@ package engine
import (
"bytes"
+ "context"
+ "encoding/json"
"errors"
+ "io"
+ "io/fs"
"os"
"path/filepath"
"runtime"
@@ -15,10 +19,14 @@ import (
"testing"
"time"
+ "github.com/huija/skillmod/internal/address"
+ "github.com/huija/skillmod/internal/config"
"github.com/huija/skillmod/internal/dirhash"
+ "github.com/huija/skillmod/internal/install"
"github.com/huija/skillmod/internal/modfile"
"github.com/huija/skillmod/internal/source"
"github.com/huija/skillmod/internal/store"
+ "github.com/huija/skillmod/internal/testutil"
)
func TestIOPrintfPropagatesWriteError(t *testing.T) {
@@ -252,6 +260,45 @@ func TestCandidateAddress(t *testing.T) {
}
}
+// TestShortAddressResolutionHint covers the hint that names the default host a
+// short address was completed to. It exists because a failed fetch names a URL
+// the user never typed, which is indistinguishable from "the repository moved"
+// unless the resolution is stated. A completed address states it; an address
+// that was never completed has nothing to add and returns nil.
+func TestShortAddressResolutionHint(t *testing.T) {
+ short, err := address.Parse("acme/skills")
+ if err != nil {
+ t.Fatalf("Parse(\"acme/skills\"): %v", err)
+ }
+ if !short.Completed || short.Repo != "https://github.com/acme/skills" {
+ t.Fatalf("Parse = %+v, want the github.com completion recorded", short)
+ }
+ hint := shortAddressResolutionHint(short)
+ if hint == nil {
+ t.Fatal("hint = nil, want the resolution named")
+ }
+ if !strings.Contains(hint.Error(), "github.com/acme/skills") ||
+ !strings.Contains(hint.Error(), "file://") {
+ t.Errorf("hint = %q, want the resolved host and the local-path remedy", hint)
+ }
+
+ // An address the user spelled out needs no hint, including one that went
+ // through the same completion path and was then written in full.
+ for _, raw := range []string{
+ "github.com/acme/skills",
+ "https://github.com/acme/skills",
+ "file:///tmp/acme/skills",
+ } {
+ full, parseErr := address.Parse(raw)
+ if parseErr != nil {
+ t.Fatalf("Parse(%q): %v", raw, parseErr)
+ }
+ if hint := shortAddressResolutionHint(full); hint != nil {
+ t.Errorf("hint(%q) = %q, want nil", raw, hint)
+ }
+ }
+}
+
func TestCandidateDisplaySubdirs(t *testing.T) {
root := t.TempDir()
if err := os.Mkdir(filepath.Join(root, "occupied"), 0o755); err != nil {
@@ -673,3 +720,110 @@ func TestSaveState_RecordsCanonicalSource(t *testing.T) {
}
}
}
+
+// TestListAnswersFromAFreshRefsCacheAndRefreshWhenAgedOut covers both halves of
+// the freshness window. A cache younger than refsCacheMaxAge keeps list local,
+// so a tag published after the install is not noticed yet; the same cache aged
+// out is refreshed over the network, so the tag then produces the upgrade notice.
+// Asserting the two halves on one cache is what distinguishes "read the cache"
+// from "never looks upstream", which is why both live here rather than in
+// engine_test.
+func TestListAnswersFromAFreshRefsCacheAndRefreshWhenAgedOut(t *testing.T) {
+ original := refsCacheMaxAge
+ refsCacheMaxAge = 0
+ t.Cleanup(func() { refsCacheMaxAge = original })
+
+ r := testutil.NewRepo(t)
+ r.WriteSkill("", "hello")
+ r.CommitAll("v1")
+ r.Tag("v1.0.0")
+ r.Finish()
+
+ root := t.TempDir()
+ s := store.New(t.TempDir())
+ eng := &Engine{
+ Root: root,
+ Source: &source.Source{VCSRoot: s.VCSRoot()},
+ Store: s,
+ Config: &config.Config{InstallMode: install.Copy},
+ }
+ if _, err := eng.Get(context.Background(), r.URL+"@v1.0.0", "", IO{Out: io.Discard, Yes: true}); err != nil {
+ t.Fatalf("Get(%q): %v", r.URL+"@v1.0.0", err)
+ }
+
+ r.Write("v2.md", "x\n")
+ r.CommitAll("v2")
+ r.Evolve("v2.0.0", false)
+
+ rep, err := eng.List(context.Background(), IO{Out: io.Discard, Yes: true})
+ if err != nil {
+ t.Fatalf("List(): %v", err)
+ }
+ if len(rep.Entries) != 1 || !strings.Contains(rep.Entries[0].Note, "upgrade available") {
+ t.Fatalf("List entries = %+v, want the upgrade notice after an aged-out cache", rep.Entries)
+ }
+
+ // A snapshot written before the fetch time existed carries none, and an
+ // unknown age must read as stale: treating it as fresh would answer a
+ // repeated list from a snapshot that could be any age. The file is located
+ // by glob so the store keeps deciding where it lives.
+ r.Write("v3.md", "x\n")
+ r.CommitAll("v3")
+ r.Evolve("v3.0.0", false)
+ legacy, err := stripRefsFetchedAt(s)
+ if err != nil {
+ t.Fatalf("strip fetchedAt: %v", err)
+ }
+ rep, err = eng.List(context.Background(), IO{Out: io.Discard, Yes: true})
+ if err != nil {
+ t.Fatalf("List(): %v", err)
+ }
+ if len(rep.Entries) != 1 || !strings.Contains(rep.Entries[0].Note, "v3.0.0") {
+ t.Fatalf("List entries = %+v, want the tag a cache with no fetch time still reports", rep.Entries)
+ }
+ if _, err := os.Stat(filepath.Join(legacy)); err != nil {
+ t.Errorf("refs cache after a refreshed list: %v", err)
+ }
+}
+
+// stripRefsFetchedAt rewrites every cached ls-remote snapshot in the store as a
+// version written before the fetch time was recorded, and returns the path it
+// rewrote. It finds the caches by name, which is the store's business, and only
+// edits what it finds.
+func stripRefsFetchedAt(s *store.Store) (string, error) {
+ var matches []string
+ err := filepath.WalkDir(s.CacheRoot(), func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if !d.IsDir() && d.Name() == "refs.json" {
+ matches = append(matches, path)
+ }
+ return nil
+ })
+ if err != nil {
+ return "", err
+ }
+ if len(matches) == 0 {
+ return "", errors.New("no cached ls-remote snapshot to rewrite")
+ }
+ for _, path := range matches {
+ var rec map[string]json.RawMessage
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return "", err
+ }
+ if err := json.Unmarshal(data, &rec); err != nil {
+ return "", err
+ }
+ delete(rec, "fetchedAt")
+ out, err := json.Marshal(rec)
+ if err != nil {
+ return "", err
+ }
+ if err := os.WriteFile(path, out, 0o600); err != nil {
+ return "", err
+ }
+ }
+ return matches[0], nil
+}
diff --git a/internal/engine/engine_test.go b/internal/engine/engine_test.go
index 1e0a973..5265d1b 100644
--- a/internal/engine/engine_test.go
+++ b/internal/engine/engine_test.go
@@ -22,6 +22,7 @@ import (
"github.com/huija/skillmod/internal/config"
"github.com/huija/skillmod/internal/dirhash"
"github.com/huija/skillmod/internal/engine"
+ "github.com/huija/skillmod/internal/i18n"
"github.com/huija/skillmod/internal/install"
"github.com/huija/skillmod/internal/modfile"
"github.com/huija/skillmod/internal/resolve"
@@ -442,6 +443,215 @@ func TestGet_AllInstallsAllDiscoveredNestedSkills(t *testing.T) {
}
}
+// A repository without a skills/ collection publishes its skills directly in
+// the root, or inside an agent skills directory such as .agents/skills; both
+// layouts are discovered so only conventional repositories need a typed path.
+func TestGet_DiscoversSkillsOutsideTheSkillsCollection(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.Write("README.md", "flat layout\n")
+ r.WriteSkill("cool-skill", "cool-skill")
+ r.WriteSkill("other-skill", "other-skill")
+ r.WriteSkill(".agents/skills/wrapped", "wrapped")
+ r.CommitAll("flat and agent layouts")
+ r.Tag("v1.0.0")
+ r.Finish()
+
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil {
+ t.Fatalf("Get flat layout with --all: %v", err)
+ }
+ mod, err := modfile.LoadMod(root)
+ if err != nil {
+ t.Fatal(err)
+ }
+ byName := map[string]modfile.ModSkill{}
+ for _, skill := range mod.Skills {
+ byName[skill.Name] = skill
+ }
+ for _, name := range []string{"cool-skill", "other-skill", "wrapped"} {
+ if _, ok := byName[name]; !ok {
+ t.Fatalf("skill %q was not discovered: %+v", name, mod.Skills)
+ }
+ }
+ if byName["cool-skill"].Source != r.URL+"//cool-skill" {
+ t.Errorf("root-level source = %q, want %q", byName["cool-skill"].Source, r.URL+"//cool-skill")
+ }
+ if byName["wrapped"].Source != r.URL+"//.agents/skills/wrapped" {
+ t.Errorf("agent-directory source = %q, want %q", byName["wrapped"].Source, r.URL+"//.agents/skills/wrapped")
+ }
+
+ // The name shorthand resolves a discovered skill wherever it lives, and an
+ // exact subdirectory still wins over name matching.
+ root2 := t.TempDir()
+ eng2 := newEngine(t, root2, t.TempDir())
+ if _, err := eng2.Get(ctx, r.URL+"//wrapped@v1.0.0", "", testIO()); err != nil {
+ t.Fatalf("Get discovered skill by name: %v", err)
+ }
+ lock := loadLockSkill(t, root2, "wrapped")
+ if lock.Source != r.URL+"//.agents/skills/wrapped" {
+ t.Errorf("name-shorthand lock source = %q, want %q", lock.Source, r.URL+"//.agents/skills/wrapped")
+ }
+ if _, err := os.Stat(filepath.Join(installedDir(root2, "wrapped"), "SKILL.md")); err != nil {
+ t.Fatalf("wrapped was not installed: %v", err)
+ }
+}
+
+// One skill under an agent directory needs no selection even though the
+// repository has no conventional layout at all.
+func TestGet_AgentDirectoryRepositoryInstallsWithoutPrompting(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.Write("README.md", "single wrapped skill\n")
+ r.WriteSkill(".agent/skills/only", "only")
+ r.CommitAll("agent layout")
+ r.Tag("v1.0.0")
+ r.Finish()
+
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO()); err != nil {
+ t.Fatalf("Get single wrapped skill: %v", err)
+ }
+ if _, err := os.Stat(filepath.Join(installedDir(root, "only"), "SKILL.md")); err != nil {
+ t.Fatal("only was not installed")
+ }
+}
+
+// TestGet_KeepsOneCandidateWhenAnAgentDirectoryMirrorsTheCollection covers a
+// repository that publishes the same skills twice, once under skills/ and again
+// under an agent directory such as .openclaw/skills or .claude/skills. Both
+// would install into one directory under one name, so discovery keeps the copy
+// from the layout a reader looks at first and offers the skill once.
+func TestGet_KeepsOneCandidateWhenAnAgentDirectoryMirrorsTheCollection(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.Write("README.md", "mirrored collection\n")
+ for _, name := range []string{"ponytail", "ponytail-review"} {
+ r.WriteSkill("skills/"+name, name)
+ r.WriteSkill(".openclaw/skills/"+name, name)
+ }
+ r.CommitAll("mirror the collection under an agent directory")
+ r.Tag("v1.0.0")
+ r.Finish()
+
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil {
+ t.Fatalf("Get mirrored collection with --all: %v", err)
+ }
+ mod, err := modfile.LoadMod(root)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(mod.Skills) != 2 {
+ t.Fatalf("declarations = %+v, want one entry per skill, not one per copy", mod.Skills)
+ }
+ for _, skill := range mod.Skills {
+ if !strings.HasPrefix(skill.Source, r.URL+"//skills/") {
+ t.Errorf("%s source = %q, want the conventional skills/ copy", skill.Name, skill.Source)
+ }
+ }
+ // The name shorthand resolves to the same copy, and a single skill from the
+ // mirrored repository needs no selection at all.
+ root2 := t.TempDir()
+ eng2 := newEngine(t, root2, t.TempDir())
+ if _, err := eng2.Get(ctx, r.URL+"//ponytail-review@v1.0.0", "", testIO()); err != nil {
+ t.Fatalf("Get mirrored skill by name: %v", err)
+ }
+ if lock := loadLockSkill(t, root2, "ponytail-review"); lock.Source != r.URL+"//skills/ponytail-review" {
+ t.Errorf("name-shorthand source = %q, want the conventional skills/ copy", lock.Source)
+ }
+}
+
+// TestGet_KeepsTheRootLevelCopyOverAnAgentDirectory covers the second step of
+// the ranking: a skill a repository leaves in a root directory outranks the same
+// skill in an agent mirror, because the root directory is the repository's own
+// layout and the agent directory is a copy kept for one agent.
+func TestGet_KeepsTheRootLevelCopyOverAnAgentDirectory(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.Write("README.md", "root copy beats agent copy\n")
+ r.WriteSkill("ponytail", "ponytail")
+ r.WriteSkill(".claude/skills/ponytail", "ponytail")
+ r.CommitAll("root copy alongside an agent copy")
+ r.Tag("v1.0.0")
+ r.Finish()
+
+ // The agent copy alone still installs, which is what makes the ranking
+ // meaningful rather than a rule that only fires on the conventional layout.
+ solo := testutil.NewRepo(t)
+ solo.Write("README.md", "agent only\n")
+ solo.WriteSkill(".claude/skills/wrapped", "wrapped")
+ solo.CommitAll("agent only")
+ solo.Tag("v1.0.0")
+ solo.Finish()
+
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO()); err != nil {
+ t.Fatalf("Get repository with a root copy and an agent copy: %v", err)
+ }
+ mod, err := modfile.LoadMod(root)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(mod.Skills) != 1 || mod.Skills[0].Source != r.URL+"//ponytail" {
+ t.Fatalf("declarations = %+v, want the root-level copy once", mod.Skills)
+ }
+ if _, err := eng.Get(ctx, solo.URL+"@v1.0.0", "", testIO()); err != nil {
+ t.Fatal("only skill published under an agent directory")
+ }
+}
+
+// TestGet_KeepsTheCollectionCopyOverEverythingElse covers the top of the
+// ranking: a skill under skills/ is the one a repository publishes as its own,
+// so it wins over a copy in a root directory and over an agent mirror alike.
+func TestGet_KeepsTheCollectionCopyOverEverythingElse(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.Write("README.md", "the same skill in three places\n")
+ r.WriteSkill("skills/ponytail", "ponytail")
+ r.WriteSkill("ponytail", "ponytail")
+ r.WriteSkill(".openclaw/skills/ponytail", "ponytail")
+ r.CommitAll("one skill, three roots")
+ r.Tag("v1.0.0")
+ r.Finish()
+
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ // Discovery with no subdirectory: the ranking decides, because all three
+ // copies were found rather than typed as a path.
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO()); err != nil {
+ t.Fatalf("Get repository with one skill in three roots: %v", err)
+ }
+ mod, err := modfile.LoadMod(root)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(mod.Skills) != 1 || mod.Skills[0].Source != r.URL+"//skills/ponytail" {
+ t.Fatalf("declarations = %+v, want the conventional skills/ copy", mod.Skills)
+ }
+}
+
+// TestGet_TwoAgentDirectoriesAreNotRankedAgainstEachOther keeps the ambiguity a
+// repository creates when two agent directories hold the same skill and neither
+// outranks the other. Picking one silently would install a copy the caller never
+// chose, so the run reports both paths the way it does for any other ambiguity.
+func TestGet_TwoAgentDirectoriesAreNotRankedAgainstEachOther(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.Write("README.md", "two agent directories, one skill\n")
+ r.WriteSkill(".claude/skills/ponytail", "ponytail")
+ r.WriteSkill(".codex/skills/ponytail", "ponytail")
+ r.CommitAll("mirror for two agents")
+ r.Tag("v1.0.0")
+ r.Finish()
+
+ eng := newEngine(t, t.TempDir(), t.TempDir())
+ _, err := eng.Get(ctx, r.URL+"//ponytail@v1.0.0", "", testIO())
+ if err == nil || !strings.Contains(err.Error(), "multiple subdirectories") ||
+ !strings.Contains(err.Error(), ".claude/skills/ponytail") ||
+ !strings.Contains(err.Error(), ".codex/skills/ponytail") {
+ t.Errorf("Get(ambiguous agent mirrors) error = %v, want both paths named", err)
+ }
+}
+
type getSkillChooser struct {
choices []int
calls int
@@ -810,7 +1020,9 @@ func TestGet_ExplicitLocalRepoVersionWinsOverNewSubdirTag(t *testing.T) {
root := t.TempDir()
eng := newEngine(t, root, t.TempDir())
- if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO()); err != nil {
+ // The repository publishes the root skill and beta as root-level skills, so
+ // the first get states the whole set instead of guessing one of them.
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil {
t.Fatal(err)
}
@@ -1333,6 +1545,67 @@ func readFileString(t *testing.T, path string) string {
return string(data)
}
+// Regression: the empty-candidate path used to report that it had generated an
+// empty manifest and then fall into the shared non-interactive confirmation
+// gate, which returned before the write phase. The report described a write
+// that never happened, and a non-interactive environment could not get past the
+// prompt it could not answer. An empty run has nothing to confirm, so it must
+// reach the write phase and keep the promise its own note made.
+func TestInit_EmptyRunKeepsTheManifestItReports(t *testing.T) {
+ t.Setenv(i18n.Env, "en")
+ // Confirm is nil and Yes is false: the shape a script or CI run sees.
+ unattended := engine.IO{Out: io.Discard}
+
+ t.Run("writes the reported empty manifest", func(t *testing.T) {
+ root := t.TempDir()
+ rep, err := newEngine(t, root, t.TempDir()).Init(ctx, false, unattended)
+ if err != nil {
+ t.Fatalf("an empty init should not require confirmation: %v", err)
+ }
+ if len(rep.Entries) != 0 {
+ t.Errorf("entries = %d, want 0", len(rep.Entries))
+ }
+ if note := strings.Join(rep.Notes, "\n"); !strings.Contains(note, "generated an empty manifest") {
+ t.Errorf("notes = %q, want the manifest already reported as generated", note)
+ }
+ if _, err := os.Stat(filepath.Join(root, modfile.ModFileName)); err != nil {
+ t.Errorf("the reported manifest was not written: %v", err)
+ }
+ })
+
+ t.Run("dry run promises instead of claiming", func(t *testing.T) {
+ root := t.TempDir()
+ rep, err := newEngine(t, root, t.TempDir()).Init(ctx, false, unattended, engine.MutationOptions{DryRun: true})
+ if err != nil {
+ t.Fatalf("init --dry-run: %v", err)
+ }
+ if note := strings.Join(rep.Notes, "\n"); !strings.Contains(note, "will generate an empty manifest") {
+ t.Errorf("notes = %q, want the future tense for a run that writes nothing", note)
+ }
+ if _, err := os.Stat(filepath.Join(root, modfile.ModFileName)); !os.IsNotExist(err) {
+ t.Errorf("dry-run wrote SKILL.mod: %v", err)
+ }
+ })
+
+ // Widening the gate must stay scoped to an empty run: a run with a candidate
+ // still has something to confirm, and silently accepting it would install a
+ // skill the user never approved.
+ t.Run("a run with candidates still requires confirmation", func(t *testing.T) {
+ root := t.TempDir()
+ dir := installedDir(root, "local-skill")
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ body := "---\nname: local-skill\ndescription: local\n---\n# local\n"
+ if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte(body), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := newEngine(t, root, t.TempDir()).Init(ctx, false, unattended); err == nil {
+ t.Error("a run with candidates should still require confirmation")
+ }
+ })
+}
+
func TestInit_ScansTheManagedDirectory(t *testing.T) {
root := t.TempDir()
dir := filepath.Join(install.SkillsDir(root), "local-skill")
@@ -2021,6 +2294,183 @@ func TestRemoveWithoutNamesNeedsASelection(t *testing.T) {
assertStateDirs(t, root, "alpha")
}
+// TestRemoveAcceptsARepositorySelector covers remove's repository form: a
+// repository that declares one skill needs no choice, several entries from one
+// repository are offered interactively exactly like get's chooser, and a
+// repository nothing comes from is reported instead of ignored.
+func TestRemoveAcceptsARepositorySelector(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.WriteSkill("skills/alpha", "alpha")
+ r.WriteSkill("skills/beta", "beta")
+ r.CommitAll("collection")
+ r.Tag("v1.0.0")
+ r.Finish()
+ other := newHelloRepo(t)
+
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil {
+ t.Fatalf("Get collection: %v", err)
+ }
+ if _, err := eng.Get(ctx, other.URL+"@v1.0.0", "", testIO()); err != nil {
+ t.Fatalf("Get hello: %v", err)
+ }
+
+ // A single-entry repository removes without asking.
+ rep, err := eng.Remove(ctx, []string{other.URL}, testIO())
+ if err != nil {
+ t.Fatalf("Remove(single-entry repository): %v", err)
+ }
+ if len(rep.Entries) != 1 || rep.Entries[0].Name != "hello" {
+ t.Fatalf("Remove report = %+v, want only hello", rep.Entries)
+ }
+
+ // Several entries from one repository: the caller picks which.
+ chooser := &shareChooser{selections: [][]int{{1}}}
+ rep, err = eng.Remove(ctx, []string{r.URL}, engine.IO{Out: io.Discard, Confirm: chooser})
+ if err != nil {
+ t.Fatalf("Remove(repository with several entries): %v", err)
+ }
+ if chooser.calls != 1 {
+ t.Fatalf("selector calls = %d, want one repository selection", chooser.calls)
+ }
+ if len(rep.Entries) != 1 || rep.Entries[0].Name != "beta" {
+ t.Fatalf("Remove report = %+v, want only the picked beta", rep.Entries)
+ }
+ if _, err := os.Stat(installedDir(root, "beta")); !os.IsNotExist(err) {
+ t.Errorf("picked installation error = %v, want not exist", err)
+ }
+ if _, err := os.Stat(installedDir(root, "alpha")); err != nil {
+ t.Errorf("unpicked installation = %v, want kept", err)
+ }
+
+ // A repository nothing comes from is reported rather than silently ignored.
+ if _, err := eng.Remove(ctx, []string{"github.com/acme/other"}, testIO()); err == nil ||
+ !strings.Contains(err.Error(), "github.com/acme/other") {
+ t.Errorf("Remove(unknown repository) error = %v, want the repository named", err)
+ }
+}
+
+// TestRemoveRepositorySelectorWithoutAChannelListsCandidates refuses to guess
+// between several entries from one repository when there is no terminal to ask
+// through, and lists them the way get lists multiple skills.
+func TestRemoveRepositorySelectorWithoutAChannelListsCandidates(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.WriteSkill("skills/alpha", "alpha")
+ r.WriteSkill("skills/beta", "beta")
+ r.CommitAll("collection")
+ r.Tag("v1.0.0")
+ r.Finish()
+
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil {
+ t.Fatalf("Get collection: %v", err)
+ }
+ _, err := eng.Remove(ctx, []string{r.URL}, testIO())
+ if err == nil {
+ t.Fatal("Remove(repository) without a channel succeeded, want a candidate listing")
+ }
+ for _, want := range []string{"alpha", "beta"} {
+ if !strings.Contains(err.Error(), want) {
+ t.Errorf("Remove error = %v, want %q listed", err, want)
+ }
+ }
+ assertStateDirs(t, root, "alpha", "beta")
+}
+
+// TestRemoveRepositorySelectorWithAllTakesEveryEntry pins the non-interactive
+// way to say "everything this repository brought in". --all expands a
+// repository selector, so a run with no terminal deletes the whole set instead
+// of stopping to list candidates, and entries from other repositories stay.
+func TestRemoveRepositorySelectorWithAllTakesEveryEntry(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.WriteSkill("skills/alpha", "alpha")
+ r.WriteSkill("skills/beta", "beta")
+ r.CommitAll("collection")
+ r.Tag("v1.0.0")
+ r.Finish()
+ other := newHelloRepo(t)
+
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil {
+ t.Fatalf("Get collection: %v", err)
+ }
+ if _, err := eng.Get(ctx, other.URL+"@v1.0.0", "", testIO()); err != nil {
+ t.Fatalf("Get hello: %v", err)
+ }
+
+ rep, err := eng.Remove(ctx, []string{r.URL}, testIO(), engine.RemoveOptions{All: true})
+ if err != nil {
+ t.Fatalf("Remove(repository, all): %v", err)
+ }
+ if len(rep.Entries) != 2 {
+ t.Fatalf("Remove report = %+v, want both collection entries", rep.Entries)
+ }
+ assertStateDirs(t, root, "hello")
+
+ // --all states the set, so naming a skill alongside it is still refused
+ // rather than silently widened to the whole declaration.
+ if _, err := eng.Remove(ctx, []string{"hello"}, testIO(), engine.RemoveOptions{All: true}); err == nil ||
+ !strings.Contains(err.Error(), "--all") {
+ t.Errorf("Remove(name, all) error = %v, want the combination refused", err)
+ }
+ assertStateDirs(t, root, "hello")
+}
+
+// TestRemoveAgentWithAllAndARepositorySelector pins the --agent path's
+// repository form. --all expands a repository selector there exactly as it does
+// for a removal, so one non-interactive command unshares everything that
+// repository declared; the expansion happens before the delegation to share,
+// which is why share does not see a set stated twice and refuse it.
+func TestRemoveAgentWithAllAndARepositorySelector(t *testing.T) {
+ r := testutil.NewRepo(t)
+ r.WriteSkill("skills/alpha", "alpha")
+ r.WriteSkill("skills/beta", "beta")
+ r.CommitAll("collection")
+ r.Tag("v1.0.0")
+ r.Finish()
+ other := newHelloRepo(t)
+
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil {
+ t.Fatalf("Get collection: %v", err)
+ }
+ if _, err := eng.Get(ctx, other.URL+"@v1.0.0", "", testIO()); err != nil {
+ t.Fatalf("Get hello: %v", err)
+ }
+ for _, name := range []string{"alpha", "beta", "hello"} {
+ if _, err := eng.Share(ctx, engine.ShareOptions{Skills: []string{name}, Agents: []string{"claude"}}, testIO()); err != nil {
+ t.Fatalf("Share(%s): %v", name, err)
+ }
+ }
+
+ rep, err := eng.Remove(ctx, []string{r.URL}, testIO(), engine.RemoveOptions{All: true, Agents: []string{"claude"}})
+ if err != nil {
+ t.Fatalf("Remove(repository, all, --agent claude): %v", err)
+ }
+ if len(rep.Entries) != 2 {
+ t.Fatalf("Remove report = %+v, want both collection entries", rep.Entries)
+ }
+ for _, name := range []string{"alpha", "beta"} {
+ if got := agentsOf(loadMod(t, root), name); len(got) != 0 {
+ t.Errorf("%s agents after unsharing the repository = %v, want none", name, got)
+ }
+ if _, err := os.Stat(filepath.Join(agentSkillsDir(root, "claude"), name)); !os.IsNotExist(err) {
+ t.Errorf("%s claude link = %v, want not exist", name, err)
+ }
+ }
+ // hello came from another repository, so it is left linked, and the managed
+ // copies stay either way: --agent only stops the sharing.
+ if got := agentsOf(loadMod(t, root), "hello"); len(got) != 1 || got[0] != "claude" {
+ t.Errorf("hello agents = %v, want [claude]", got)
+ }
+ assertStateDirs(t, root, "alpha", "beta", "hello")
+}
+
+// TestRemoveKeepsModifiedInstallationAndReportsPartial covers the partial path.
func TestRemoveKeepsModifiedInstallationAndReportsPartial(t *testing.T) {
r := newHelloRepo(t)
root := t.TempDir()
@@ -2301,7 +2751,10 @@ func TestList(t *testing.T) {
if len(rep.Entries) != 1 || rep.Entries[0].Action != "installed" {
t.Errorf("list = %+v", rep.Entries)
}
- // A new upstream version produces an upgrade notice.
+ // A repeated list answers from the reference snapshot the install wrote, so
+ // a new upstream tag is not noticed until that snapshot ages out; the aged-out
+ // half of the contract is asserted in TestListAnswersFromAFreshRefsCache,
+ // which can age the window and TestList cannot. update refreshes on demand.
r.Write("v2.md", "x\n")
r.CommitAll("v2")
r.Evolve("v2.0.0", false)
@@ -2309,8 +2762,8 @@ func TestList(t *testing.T) {
if err != nil {
t.Fatal(err)
}
- if !strings.Contains(rep.Entries[0].Note, "upgrade available → ") {
- t.Errorf("list did not report an available upgrade: %+v", rep.Entries[0])
+ if strings.Contains(rep.Entries[0].Note, "upgrade available") {
+ t.Errorf("list refreshed a cache that is still fresh: %+v", rep.Entries[0])
}
}
@@ -2524,3 +2977,325 @@ func TestWhyReportsImmutableProvenanceAndTargetResults(t *testing.T) {
t.Error("Why(missing) succeeded")
}
}
+
+// TestSyncAdoptsLocallyAddedSkills covers the sync form of init's local
+// adoption: a skill another tool or a manual copy left in the installation
+// directory becomes a local declaration with its content untouched, and a
+// second run is a no-op rather than a re-adoption.
+func TestSyncAdoptsLocallyAddedSkills(t *testing.T) {
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Init(ctx, false, testIO()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+ writeLocalSkill(t, root, "added-later", "echo hi\n")
+
+ rep, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO())
+ if err != nil {
+ t.Fatalf("Sync(adopt): %v", err)
+ }
+ var adopted *engine.EntryReport
+ for i := range rep.Entries {
+ if rep.Entries[i].Name == "added-later" {
+ adopted = &rep.Entries[i]
+ }
+ }
+ if adopted == nil || adopted.Action != engine.ActionAdopt || !strings.Contains(adopted.Note, "adopted") {
+ t.Fatalf("Sync(adopt) report = %+v, want an adopted local entry", rep.Entries)
+ }
+ m := loadMod(t, root)
+ if len(m.Skills) != 1 || !m.Skills[0].Local || m.Skills[0].Name != "added-later" {
+ t.Fatalf("declarations after adoption = %+v, want one local entry", m.Skills)
+ }
+ lk := loadLockSkill(t, root, "added-later")
+ if lk.Source != "" || lk.Dirhash == "" {
+ t.Fatalf("lock after adoption = %+v, want a local baseline with a dirhash", lk)
+ }
+ // The adopted content is exactly what was on disk.
+ if got := readFileString(t, filepath.Join(installedDir(root, "added-later"), "run.sh")); got != "echo hi\n" {
+ t.Errorf("adopted run.sh = %q, want the local content preserved", got)
+ }
+
+ // A second run adopts nothing new and reports the local entry as consistent.
+ rep, err = eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO())
+ if err != nil {
+ t.Fatalf("second Sync(adopt): %v", err)
+ }
+ for _, entry := range rep.Entries {
+ if entry.Name == "added-later" && strings.Contains(entry.Note, "adopted as") {
+ t.Errorf("second run re-adopted: %+v", entry)
+ }
+ }
+}
+
+// TestSyncAdoptRecordsTheDirectoryAsAlias covers a directory whose frontmatter
+// name is not its own directory name, which is what a skill installed under a
+// local name looks like. The declaration keeps the published name and records
+// the directory as the alias, which is the only identity the filesystem offers.
+func TestSyncAdoptRecordsTheDirectoryAsAlias(t *testing.T) {
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Init(ctx, false, testIO()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+ dir := filepath.Join(root, ".agents", "skills", "vendored-copy")
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(filepath.Join(dir, "SKILL.md"),
+ []byte("---\nname: published-name\ndescription: test skill\n---\n# x\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+
+ if _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()); err != nil {
+ t.Fatalf("Sync(adopt): %v", err)
+ }
+ m := loadMod(t, root)
+ if len(m.Skills) != 1 {
+ t.Fatalf("declarations after adoption = %+v, want one entry", m.Skills)
+ }
+ if m.Skills[0].Name != "published-name" || m.Skills[0].Alias != "vendored-copy" {
+ t.Errorf("declaration = %+v, want the published name with the directory as alias", m.Skills[0])
+ }
+ // The installation directory stays the one on disk, so the entry resolves
+ // back to the files it came from.
+ if got := m.Skills[0].DirName(); got != "vendored-copy" {
+ t.Errorf("DirName() = %q, want the directory it was found in", got)
+ }
+ if _, err := os.Stat(filepath.Join(installedDir(root, "vendored-copy"), "SKILL.md")); err != nil {
+ t.Errorf("installation = %v, want kept under its own directory", err)
+ }
+}
+
+// TestSyncWithoutAdoptOnlyNamesUndeclaredSkills keeps a plain sync from
+// changing the declaration while still telling the user the flag exists.
+func TestSyncWithoutAdoptOnlyNamesUndeclaredSkills(t *testing.T) {
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Init(ctx, false, testIO()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+ writeLocalSkill(t, root, "added-later", "")
+
+ var out bytes.Buffer
+ rep, err := eng.Sync(ctx, engine.SyncOptions{}, engine.IO{Out: &out, Yes: true})
+ if err != nil {
+ t.Fatalf("Sync: %v", err)
+ }
+ if len(loadMod(t, root).Skills) != 0 {
+ t.Errorf("declarations after a plain sync = %+v, want none", loadMod(t, root).Skills)
+ }
+ joined := strings.Join(rep.Notes, "\n") + out.String()
+ if !strings.Contains(joined, "--adopt") {
+ t.Errorf("plain sync output = %q, want the --adopt hint", joined)
+ }
+}
+
+// TestSyncAdoptNeedsAChannelOrYes refuses to record provenance on a real run
+// that can neither ask nor state the intent. A dry run is exempt: it only
+// prints the plan, so it never needs an answer
+// (TestSyncAdoptDryRunPlansWithoutAsking).
+func TestSyncAdoptNeedsAChannelOrYes(t *testing.T) {
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Init(ctx, false, testIO()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+ writeLocalSkill(t, root, "added-later", "")
+ if _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, engine.IO{Out: io.Discard}); err == nil {
+ t.Fatal("Sync(adopt) without a channel succeeded, want a diagnostic")
+ }
+ if len(loadMod(t, root).Skills) != 0 {
+ t.Errorf("declarations after a refused adoption = %+v, want none", loadMod(t, root).Skills)
+ }
+}
+
+// TestSyncAdoptCheckIsRefused: --check only verifies, so the adoption flag has
+// nothing to act on and saying so beats silently ignoring it.
+func TestSyncAdoptCheckIsRefused(t *testing.T) {
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Init(ctx, false, testIO()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+ if _, err := eng.Sync(ctx, engine.SyncOptions{CheckOnly: true, Adopt: true}, testIO()); err == nil {
+ t.Fatal("Sync(--check --adopt) succeeded, want a refusal")
+ }
+}
+
+// dryRunAskRecorder fails a dry run that consults the confirmation channel:
+// printing a plan must never wait on input.
+type dryRunAskRecorder struct{ asked bool }
+
+func (r *dryRunAskRecorder) Confirm(string) (bool, error) {
+ r.asked = true
+ return false, nil
+}
+
+func (*dryRunAskRecorder) Choose(string, []string) (int, error) { return 0, nil }
+
+// TestSyncAdoptDryRunPlansWithoutAsking keeps a dry run from blocking on the
+// adoption prompt: the plan lists every candidate as pending, the manifests
+// stay untouched, the confirmation channel is never consulted, and a run
+// without any channel still prints the plan instead of refusing.
+func TestSyncAdoptDryRunPlansWithoutAsking(t *testing.T) {
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Init(ctx, false, testIO()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+ writeLocalSkill(t, root, "added-later", "echo hi\n")
+
+ ask := &dryRunAskRecorder{}
+ rep, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true, DryRun: true}, engine.IO{Out: io.Discard, Confirm: ask})
+ if err != nil {
+ t.Fatalf("Sync(adopt, dry-run): %v", err)
+ }
+ if ask.asked {
+ t.Error("dry run consulted the confirmation channel")
+ }
+ if skills := loadMod(t, root).Skills; len(skills) != 0 {
+ t.Errorf("declarations after a dry run = %+v, want none", skills)
+ }
+ var planned *engine.EntryReport
+ for i := range rep.Entries {
+ if rep.Entries[i].Name == "added-later" {
+ planned = &rep.Entries[i]
+ }
+ }
+ // The plan carries the adoption action, so a --json consumer can tell a
+ // pending adoption from an existing local entry in the same document
+ // without parsing the note.
+ if planned == nil || planned.Action != engine.ActionAdopt || !strings.Contains(planned.Note, "will be adopted") {
+ t.Fatalf("dry-run report = %+v, want a pending adoption entry", rep.Entries)
+ }
+ if notes := strings.Join(rep.Notes, "\n"); !strings.Contains(notes, "--yes") {
+ t.Errorf("dry-run notes = %q, want the real-run hint", notes)
+ }
+
+ // Without any channel the dry run still succeeds: refusing to ask is a
+ // real-run refusal, not a plan-time one.
+ rep, err = eng.Sync(ctx, engine.SyncOptions{Adopt: true, DryRun: true}, engine.IO{Out: io.Discard})
+ if err != nil {
+ t.Fatalf("Sync(adopt, dry-run) without a channel: %v", err)
+ }
+ if skills := loadMod(t, root).Skills; len(skills) != 0 {
+ t.Errorf("declarations after a channel-less dry run = %+v, want none", skills)
+ }
+ if len(rep.Entries) == 0 {
+ t.Error("channel-less dry run produced no planned entries")
+ }
+}
+
+// TestSyncAdoptRejectsCaseCollidingDirectories keeps the portability guard init
+// applies: two directories that differ only in letter case map to one
+// installation directory on Windows and macOS, so adopting both would write a
+// declaration no other machine can materialize. The run is refused before
+// either declaration is written, and the message says how to get past it.
+func TestSyncAdoptRejectsCaseCollidingDirectories(t *testing.T) {
+ root := t.TempDir()
+ if caseInsensitiveFS(root) {
+ t.Skip("requires a case-sensitive filesystem")
+ }
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Init(ctx, false, testIO()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+ for _, dirName := range []string{"Demo", "demo"} {
+ writeLocalSkill(t, root, dirName, "echo hi\n")
+ }
+
+ _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO())
+ if err == nil {
+ t.Fatal("Sync(adopt) accepted installation directories that collide when case is folded")
+ }
+ for _, want := range []string{"Demo", "demo", "rename"} {
+ if !strings.Contains(err.Error(), want) {
+ t.Errorf("Sync error = %v, want %q named", err, want)
+ }
+ }
+ if skills := loadMod(t, root).Skills; len(skills) != 0 {
+ t.Errorf("declarations after a refused adoption = %+v, want none", skills)
+ }
+}
+
+// TestSyncSummaryNamesLocalDrift keeps the human summary from claiming "no
+// changes" on a run whose most important fact is a detected and preserved
+// local edit; the detail stays in the report, the summary must name it.
+func TestSyncSummaryNamesLocalDrift(t *testing.T) {
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Init(ctx, false, testIO()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+ writeLocalSkill(t, root, "added-later", "echo hi\n")
+ if _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()); err != nil {
+ t.Fatalf("Sync(adopt): %v", err)
+ }
+
+ // Edit the adopted skill behind sync's back, then run a plain sync.
+ skillMd := filepath.Join(installedDir(root, "added-later"), "SKILL.md")
+ if err := os.WriteFile(skillMd, []byte("---\nname: added-later\ndescription: edited\n---\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ var out bytes.Buffer
+ rep, err := eng.Sync(ctx, engine.SyncOptions{}, engine.IO{Out: &out, Yes: true})
+ if err != nil {
+ t.Fatalf("Sync: %v", err)
+ }
+ drifted := false
+ for _, entry := range rep.Entries {
+ if entry.Action == engine.ActionLocalDrift {
+ drifted = true
+ }
+ }
+ if !drifted {
+ t.Fatalf("Sync report = %+v, want a local-drift entry", rep.Entries)
+ }
+ joined := strings.Join(rep.Notes, "\n") + out.String()
+ if !strings.Contains(joined, "differ from their lock records") {
+ t.Errorf("sync summary = %q, want the local-drift line", joined)
+ }
+ if strings.Contains(joined, "no changes") {
+ t.Errorf("sync summary = %q, must not claim no changes while local edits exist", joined)
+ }
+
+ // The drifted lock record is untouched: sync informs, it does not re-baseline.
+ if lk := loadLockSkill(t, root, "added-later"); lk.Dirhash == "" {
+ t.Errorf("lock after a drifted sync = %+v, want the original baseline kept", lk)
+ }
+}
+
+// TestSyncAdoptLeavesStaleLockRecordsForPrune: a directory a lock record still
+// occupies is not local content to adopt, it is a stale declaration's remains.
+func TestSyncAdoptLeavesStaleLockRecordsForPrune(t *testing.T) {
+ root := t.TempDir()
+ eng := newEngine(t, root, t.TempDir())
+ if _, err := eng.Init(ctx, false, testIO()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+ writeLocalSkill(t, root, "declared", "")
+ if _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()); err != nil {
+ t.Fatalf("Sync(adopt): %v", err)
+ }
+ // Hand-edit the declaration away, exactly the state prune exists for.
+ m := loadMod(t, root)
+ m.Skills = nil
+ if err := modfile.SaveMod(root, m); err != nil {
+ t.Fatal(err)
+ }
+ writeLocalSkill(t, root, "brand-new", "")
+
+ rep, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO())
+ if err != nil {
+ t.Fatalf("Sync(adopt) with a stale record: %v", err)
+ }
+ for _, entry := range rep.Entries {
+ if entry.Name == "declared" && strings.Contains(entry.Note, "adopted as") {
+ t.Errorf("stale lock record was adopted: %+v", entry)
+ }
+ }
+ if got := loadMod(t, root).Skills; len(got) != 1 || got[0].Name != "brand-new" {
+ t.Errorf("declarations = %+v, want only brand-new adopted", got)
+ }
+}
diff --git a/internal/engine/get.go b/internal/engine/get.go
index 8dd8e7c..76ed328 100644
--- a/internal/engine/get.go
+++ b/internal/engine/get.go
@@ -11,6 +11,7 @@ import (
"io/fs"
"os"
"path/filepath"
+ "sort"
"strings"
"github.com/huija/skillmod/internal/address"
@@ -73,6 +74,9 @@ func (e *Engine) Get(ctx context.Context, rawAddr, alias string, io IO, options
resolved, err := e.resolveGetSkills(ctx, addr, io, run.All)
if err != nil {
+ if hint := shortAddressResolutionHint(addr); hint != nil {
+ err = errors.Join(err, hint)
+ }
return nil, err
}
if alias != "" && len(resolved) != 1 {
@@ -232,6 +236,19 @@ func (e *Engine) Get(ctx context.Context, rawAddr, alias string, io IO, options
return rep, partialError(rep, conflicts, skip)
}
+// shortAddressResolutionHint names the default host a bare owner/repo was
+// extended with, for the run whose fetch then failed. The failure names a URL
+// the raw input never contained, so a user who meant a local path needs the
+// resolution stated. The normalized address is echoed rather than the raw
+// input, which Redact would replace with a placeholder. An address that was
+// never completed has nothing to state and returns nil.
+func shortAddressResolutionHint(addr *address.Address) error {
+ if !addr.Completed {
+ return nil
+ }
+ return fmt.Errorf("%s", i18n.Format("engine.get.short_address_resolved", addr.Repo))
+}
+
func printGetDryRunReport(rep *Report, io IO) error {
for _, entry := range rep.Entries {
if err := io.printf(i18n.Text("engine.get.dry_run_entry"), entry.Name, entry.Version, entry.Action); err != nil {
@@ -397,6 +414,30 @@ type skillCandidate struct {
subdir string
name string
description string
+ origin candidateOrigin
+}
+
+// candidateOrigin ranks the root a candidate was found under. A repository can
+// publish the same skill under more than one conventional root — skills/ and an
+// agent mirror such as .openclaw/skills is the common case — and the two would
+// install into the same directory under the same name, so discovery keeps one of
+// them. The ranking is the one a reader of the repository expects: the
+// conventional skills/ collection, then a root-level directory, then the
+// agent-specific collections, which are mirrors maintained for one agent rather
+// than the repository's own layout.
+type candidateOrigin int
+
+const (
+ originRepositoryRoot candidateOrigin = iota // the repository itself is one skill
+ originCollection
+ originRootDirectory
+ originAgentCollection
+)
+
+// takesPrecedenceOver reports whether this root outranks another, so the copy
+// a repository keeps is the one from the layout a reader looks at first.
+func (o candidateOrigin) takesPrecedenceOver(other candidateOrigin) bool {
+ return o < other
}
// chooseSkillCandidates lets an interactive caller choose one or more skills.
@@ -508,9 +549,32 @@ func candidateDisplaySubdirs(root string, candidates []skillCandidate) []string
return displaySubdirs
}
+// skillCandidates discovers the skills a repository publishes. Discovery order
+// is the repository root itself (a standalone skill), the conventional skills/
+// collection, any agent-named hidden collection such as .agents/skills or
+// .claude/skills, and the root-level directories as well. Those four are always
+// scanned, in that order, because a repository that publishes a collection can
+// still leave a skill sitting in another root directory, and a skill nobody
+// asked for is what discovery is for; duplicates are collapsed. An explicit
+// subdirectory always wins over discovery, so a repository only has to look
+// conventional to users who never type a path.
func skillCandidates(root string) ([]skillCandidate, error) {
var candidates []skillCandidate
- addCandidate := func(dir, subdir string) error {
+ // A skill name is the identity an installation directory and a //name address
+ // both use, so the same skill published under two roots cannot both be
+ // offered: they would install into one place under one name. The key pairs
+ // the folded name with the root it was found under, because two skills that
+ // share a name inside one collection are two skills, not a duplicate — they
+ // stay to be reported as the ambiguity they are. The map holds the position
+ // of the copy currently kept, so a copy from a higher-precedence root
+ // replaces it where the first one stood.
+ byName := map[string]int{}
+ seenSubdir := map[string]bool{}
+ addCandidate := func(dir, subdir string, origin candidateOrigin) error {
+ if seenSubdir[subdir] {
+ return nil
+ }
+ seenSubdir[subdir] = true
if !hasSkillManifest(dir) {
return nil
}
@@ -521,33 +585,107 @@ func skillCandidates(root string) ([]skillCandidate, error) {
if err != nil {
return err
}
- candidates = append(candidates, skillCandidate{subdir: subdir, name: metadata.Name, description: metadata.Description})
+ key := fsutil.FoldKey(metadata.Name)
+ if at, duplicate := byName[key]; duplicate {
+ switch {
+ case origin.takesPrecedenceOver(candidates[at].origin):
+ // A copy from the higher-precedence root replaces the one kept,
+ // in the position that one had taken.
+ candidates[at] = skillCandidate{subdir: subdir, name: metadata.Name, description: metadata.Description, origin: origin}
+ case candidates[at].origin != origin:
+ // The kept copy's root outranks this one, so this copy is the
+ // duplicate and is dropped.
+ default:
+ // Neither outranks: the same name inside one collection, or two
+ // agent mirrors nobody ranks. Two skills rather than a duplicate,
+ // so both stay to be reported as the ambiguity they are.
+ candidates = append(candidates, skillCandidate{subdir: subdir, name: metadata.Name, description: metadata.Description, origin: origin})
+ }
+ return nil
+ }
+ byName[key] = len(candidates)
+ candidates = append(candidates, skillCandidate{subdir: subdir, name: metadata.Name, description: metadata.Description, origin: origin})
return nil
}
- if err := addCandidate(root, ""); err != nil {
+ if err := addCandidate(root, "", originRepositoryRoot); err != nil {
return nil, err
}
-
- skillsRoot := filepath.Join(root, "skills")
- _, err := os.Stat(skillsRoot)
- if os.IsNotExist(err) {
- return candidates, nil
+ for _, collection := range collectionRoots(root) {
+ if err := walkCollection(root, collection.dir, collection.origin, addCandidate); err != nil {
+ return nil, err
+ }
}
+ entries, err := os.ReadDir(root)
if err != nil {
return nil, err
}
- err = filepath.WalkDir(skillsRoot, func(path string, d fs.DirEntry, walkErr error) error {
+ for _, entry := range entries {
+ if !entry.IsDir() {
+ continue
+ }
+ if err := addCandidate(filepath.Join(root, entry.Name()), entry.Name(), originRootDirectory); err != nil {
+ return nil, err
+ }
+ }
+ return candidates, nil
+}
+
+// collectionDirName is the directory name a skill collection is published
+// under, both bare (skills/) and inside an agent directory (.agents/skills).
+const collectionDirName = "skills"
+
+// collectionRoot is one directory a collection is published under, with the
+// origin its skills carry.
+type collectionRoot struct {
+ dir string
+ origin candidateOrigin
+}
+
+// collectionRoots lists the collection directories a repository may publish
+// under, in discovery order: the conventional skills/ directory and every
+// hidden agent-named directory that holds one, such as .agents/skills,
+// .claude/skills, or .agent/skills. A directory under a hidden one is a mirror
+// kept for a single agent, so its skills carry the lower origin and lose to a
+// same-named skill in the conventional collection.
+func collectionRoots(root string) []collectionRoot {
+ var roots []collectionRoot
+ for _, pattern := range []string{
+ filepath.Join(root, collectionDirName),
+ filepath.Join(root, ".*", collectionDirName),
+ } {
+ matches, err := filepath.Glob(pattern)
+ if err != nil {
+ continue // A malformed pattern is a programming error, not user input.
+ }
+ sort.Strings(matches)
+ for _, match := range matches {
+ origin := originCollection
+ if strings.HasPrefix(filepath.Base(filepath.Dir(match)), ".") {
+ origin = originAgentCollection
+ }
+ roots = append(roots, collectionRoot{dir: match, origin: origin})
+ }
+ }
+ return roots
+}
+
+// walkCollection adds every skill under one collection directory at any depth,
+// stopping at a directory that is itself a skill. The origin every candidate
+// carries is the one the collection itself has, so a skill inside an agent
+// directory never outranks the same skill under skills/.
+func walkCollection(root, collection string, origin candidateOrigin, addCandidate func(dir, subdir string, origin candidateOrigin) error) error {
+ return filepath.WalkDir(collection, func(path string, d fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
- if !d.IsDir() || path == skillsRoot {
+ if !d.IsDir() || path == collection {
return nil
}
rel, err := filepath.Rel(root, path)
if err != nil {
return err
}
- if err := addCandidate(path, filepath.ToSlash(rel)); err != nil {
+ if err := addCandidate(path, filepath.ToSlash(rel), origin); err != nil {
return err
}
if hasSkillManifest(path) {
@@ -555,10 +693,6 @@ func skillCandidates(root string) ([]skillCandidate, error) {
}
return nil
})
- if err != nil {
- return nil, err
- }
- return candidates, nil
}
func hasSkillManifest(dir string) bool {
diff --git a/internal/engine/init.go b/internal/engine/init.go
index 6807607..13932a5 100644
--- a/internal/engine/init.go
+++ b/internal/engine/init.go
@@ -327,7 +327,13 @@ func (e *Engine) Init(ctx context.Context, force bool, io IO, options ...Mutatio
}
if len(rep.Entries) == 0 {
- rep.Notes = append(rep.Notes, i18n.Text("engine.init.skills_found_generated_empty"))
+ // State the tense the run can keep: the manifest is written below, and
+ // a dry run never writes one.
+ note := i18n.Text("engine.init.skills_found_generated_empty")
+ if run.DryRun {
+ note = i18n.Text("engine.init.skills_found_will_generate_empty")
+ }
+ rep.Notes = append(rep.Notes, note)
}
if unresolved > 0 {
rep.Notes = append(rep.Notes, i18n.Format("engine.init.unresolved_sources", unresolved))
@@ -358,7 +364,11 @@ func (e *Engine) Init(ctx context.Context, force bool, io IO, options ...Mutatio
}
// Confirm each entry individually so users can reject uncertain provenance.
- if !io.Yes && io.Confirm == nil {
+ // An empty run has nothing to reject, so the gate stays open: a run that
+ // found no skill must still write the empty manifest it reported above,
+ // rather than stop at a prompt a non-interactive environment cannot
+ // answer.
+ if len(m.Skills) > 0 && !io.Yes && io.Confirm == nil {
rep.Notes = append(rep.Notes, i18n.Text("engine.init.confirmed_non_interactive"))
return rep, fmt.Errorf("%s", i18n.Text("engine.init.init_requires_confirmation"))
}
diff --git a/internal/engine/list.go b/internal/engine/list.go
index 627c384..14ecb43 100644
--- a/internal/engine/list.go
+++ b/internal/engine/list.go
@@ -9,11 +9,20 @@ import (
"time"
"github.com/huija/skillmod/internal/i18n"
+ repoaddr "github.com/huija/skillmod/internal/repo"
"github.com/huija/skillmod/internal/resolve"
)
+// refsCacheMaxAge is how long a cached ls-remote snapshot stays fresh for
+// list's upgrade detection. list is a read-only inspection command: within
+// this window it answers from the local cache, and skillmod update is the
+// command that deliberately contacts the remote. It is a variable so tests can
+// age a cache without waiting.
+var refsCacheMaxAge = 15 * time.Minute
+
// List implements skillmod list by reporting every declared entry as installed, missing, drifted, or upgradable.
-// It is read-only. Upgrade detection calls ls-remote once per unique repository and skips failures.
+// It is read-only. Upgrade detection calls ls-remote once per unique repository whose cached reference
+// snapshot has gone stale, and skips failures.
func (e *Engine) List(ctx context.Context, io IO) (*Report, error) {
unlock, err := e.lockState()
if err != nil {
@@ -29,21 +38,36 @@ func (e *Engine) List(ctx context.Context, io IO) (*Report, error) {
return nil, err
}
- // Call ls-remote once per unique repository on a best-effort basis.
+ // Call ls-remote once per unique repository on a best-effort basis, and
+ // only for repositories whose cached reference snapshot is older than the
+ // freshness window: a warm cache makes repeated list runs local-only, and
+ // update remains the command that deliberately refreshes.
type latestKey struct{ repo, subdir string }
latestCache := map[latestKey]string{}
memo := newOperationMemo(nil)
- var repositories []string
+ queried := map[string]bool{}
+ var stale []string
for _, skill := range m.Skills {
if skill.Local || findLock(lock, skill) == nil || resolve.IsPseudoVersion(skill.Version) {
continue
}
repo, _, err := splitSource(skill.Source)
- if err == nil {
- repositories = append(repositories, repo)
+ if err != nil {
+ continue
+ }
+ identity := repoaddr.Identity(repo)
+ if queried[identity] {
+ continue
+ }
+ queried[identity] = true
+ cached, ok, cacheErr := e.Store.GetRepoRefs(repo)
+ if cacheErr == nil && ok && time.Since(cached.FetchedAt) < refsCacheMaxAge {
+ memo.refs[identity] = refsResult{refs: cached.Refs}
+ continue
}
+ stale = append(stale, repo) // Absent, unreadable, or aged out: refresh it.
}
- e.loadRefsBestEffort(ctx, repositories, memo, 10*time.Second)
+ e.loadRefsBestEffort(ctx, stale, memo, 10*time.Second)
rep := &Report{Action: CommandList}
for _, sk := range m.Skills {
diff --git a/internal/engine/manifest_advice_test.go b/internal/engine/manifest_advice_test.go
new file mode 100644
index 0000000..3cb3070
--- /dev/null
+++ b/internal/engine/manifest_advice_test.go
@@ -0,0 +1,45 @@
+// Copyright 2026 huija
+//
+// SPDX-License-Identifier: MIT
+
+package engine_test
+
+import (
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/huija/skillmod/internal/engine"
+)
+
+// The missing-manifest advice is a recovery contract: it must name the paths
+// that actually recover the user. A project without a manifest is usually a
+// user standing in $HOME — whose installation directories are the global
+// scope's — so the project advice offers --global before suggesting init;
+// the global advice spells the same flag the command already needs. Rewording
+// either message also updates TestContractWordingIsPinned in the same change.
+func TestMissingManifestAdviceNamesScopeRecoveryPaths(t *testing.T) {
+ project := newEngine(t, t.TempDir(), t.TempDir())
+ _, err := project.Sync(ctx, engine.SyncOptions{}, testIO())
+ if err == nil {
+ t.Fatal("Sync(project without manifest) = nil, want missing-manifest error")
+ }
+ for _, want := range []string{"SKILL.mod not found", "skillmod init", "--global"} {
+ if !strings.Contains(err.Error(), want) {
+ t.Errorf("Sync(project without manifest) = %q, want advice containing %q", err, want)
+ }
+ }
+
+ global := newEngine(t, t.TempDir(), t.TempDir())
+ global.ManifestRoot = filepath.Join(global.Store.Root(), "global")
+ _, err = global.Sync(ctx, engine.SyncOptions{}, testIO())
+ if err == nil {
+ t.Fatal("Sync(global without manifest) = nil, want missing-manifest error")
+ }
+ if !strings.Contains(err.Error(), "--global init") {
+ t.Errorf("Sync(global without manifest) = %q, want advice containing --global init", err)
+ }
+ if strings.Contains(err.Error(), "project") {
+ t.Errorf("Sync(global without manifest) = %q, want no project-scoped advice", err)
+ }
+}
diff --git a/internal/engine/remove.go b/internal/engine/remove.go
index 7b302d3..8bd9f8e 100644
--- a/internal/engine/remove.go
+++ b/internal/engine/remove.go
@@ -8,10 +8,13 @@ import (
"context"
"errors"
"fmt"
+ "strings"
+ "github.com/huija/skillmod/internal/address"
"github.com/huija/skillmod/internal/fsutil"
"github.com/huija/skillmod/internal/i18n"
"github.com/huija/skillmod/internal/modfile"
+ repoaddr "github.com/huija/skillmod/internal/repo"
"github.com/huija/skillmod/internal/ui"
)
@@ -30,16 +33,43 @@ func removeOptions(options []RemoveOptions) RemoveOptions {
}
// Remove deletes declarations and clean managed installations selected by
-// published name or installation alias, by --all, or from the interactive
-// selection when the run names nothing. Locally modified installations are
-// kept and reported as partial completion.
-func (e *Engine) Remove(ctx context.Context, names []string, io IO, options ...RemoveOptions) (*Report, error) {
+// published name or installation alias, by repository, by --all, or from the
+// interactive selection when the run names nothing. --all states the whole
+// declared set, or the whole set that the repository selectors name, which is
+// what makes "everything this repository brought in" sayable without a
+// terminal. Locally modified installations are kept and reported as partial
+// completion.
+func (e *Engine) Remove(ctx context.Context, args []string, io IO, options ...RemoveOptions) (*Report, error) {
run := removeOptions(options)
- if run.All && len(names) > 0 {
- return nil, fmt.Errorf("%s", i18n.Text("engine.remove.all_exclusive"))
+ if run.All {
+ // --all states the whole set, and a repository selector is a set it can
+ // expand; a skill name already names the entry, so stating both is
+ // refused rather than guessed at.
+ for _, arg := range args {
+ if !strings.Contains(arg, "/") {
+ return nil, fmt.Errorf("%s", i18n.Text("engine.remove.all_exclusive"))
+ }
+ }
}
if len(run.Agents) > 0 {
- rep, err := e.Share(ctx, ShareOptions{Skills: names, All: run.All, Remove: run.Agents}, io,
+ // Unlinking names agents on an entry, so a repository selector resolves
+ // to the names of the entries it matches before the delegation.
+ m, err := e.loadMod()
+ if err != nil {
+ return nil, err
+ }
+ names, err := repositoryRemovalNames(m, args, io, run.All)
+ if err != nil {
+ return nil, err
+ }
+ // A repository selector expands to the names of every entry it declares,
+ // which states the set by itself; forwarding --all alongside those names
+ // would state it a second time, and share refuses a set stated twice.
+ // --all on its own still travels as --all. The refusal is share's, not
+ // this one, so a run that names skills next to --all is still rejected
+ // where the two collide, above.
+ all := run.All && len(names) == 0
+ rep, err := e.Share(ctx, ShareOptions{Skills: names, All: all, Remove: run.Agents}, io,
MutationOptions{DryRun: run.DryRun})
if rep != nil {
rep.Action = CommandRemove
@@ -59,7 +89,7 @@ func (e *Engine) Remove(ctx context.Context, names []string, io IO, options ...R
if err != nil {
return nil, err
}
- selected, err := selectRemovals(m, names, run.All, io)
+ selected, err := selectRemovals(m, args, run.All, io)
if err != nil {
return nil, err
}
@@ -180,13 +210,16 @@ func (e *Engine) Remove(ctx context.Context, names []string, io IO, options ...R
}
// selectRemovals resolves the entries a remove run acts on, keyed by folded
-// installation directory. Names and --all state the set explicitly; with
-// neither, an interactive caller picks from what the manifest declares, which
-// is how every other selection in skillmod works. Removing deletes an
-// installation outright, so the picker is only how the set is chosen — the
-// confirmation that lists the directories still comes afterwards.
-func selectRemovals(m *modfile.Mod, names []string, all bool, io IO) (map[string]bool, error) {
- if all {
+// installation directory. Names and --all state the set explicitly, and --all
+// also states the whole set a repository selector matches; a repository
+// selector without it picks the entries declared from that repository and asks
+// which of them when more than one is declared; with neither, an interactive
+// caller picks from what the manifest declares, which is how every other
+// selection in skillmod works. Removing deletes an installation outright, so
+// the picker is only how the set is chosen — the confirmation that lists the
+// directories still comes afterwards.
+func selectRemovals(m *modfile.Mod, args []string, all bool, io IO) (map[string]bool, error) {
+ if all && len(args) == 0 {
if len(m.Skills) == 0 {
return nil, fmt.Errorf("%s", i18n.Text("engine.remove.nothing_declared"))
}
@@ -196,8 +229,34 @@ func selectRemovals(m *modfile.Mod, names []string, all bool, io IO) (map[string
}
return selected, nil
}
+ selected := map[string]bool{}
+ var names []string
+ for _, arg := range args {
+ // A skill name or alias can never contain a slash, so an argument that
+ // does is a repository selector.
+ if !strings.Contains(arg, "/") {
+ names = append(names, arg)
+ continue
+ }
+ fromRepo, err := repositoryRemovals(m, arg, io, all)
+ if err != nil {
+ return nil, err
+ }
+ for _, skill := range fromRepo {
+ selected[fsutil.FoldKey(skill.DirName())] = true
+ }
+ }
if len(names) > 0 {
- return namedRemovals(m, names)
+ named, err := namedRemovals(m, names)
+ if err != nil {
+ return nil, err
+ }
+ for key := range named {
+ selected[key] = true
+ }
+ }
+ if len(selected) > 0 {
+ return selected, nil
}
if len(m.Skills) == 0 {
return nil, fmt.Errorf("%s", i18n.Text("engine.remove.nothing_declared"))
@@ -221,13 +280,105 @@ func selectRemovals(m *modfile.Mod, names []string, all bool, io IO) (map[string
if err != nil {
return nil, err
}
- selected := make(map[string]bool, len(picked))
for _, index := range picked {
selected[fsutil.FoldKey(m.Skills[index].DirName())] = true
}
return selected, nil
}
+// repositoryRemovals resolves one repository selector against the
+// declarations. A repository that declares a single skill needs no choice, and
+// all takes every entry it declares; several entries without either are
+// offered interactively, or listed for a rerun when there is no channel to ask
+// through.
+func repositoryRemovals(m *modfile.Mod, raw string, io IO, all bool) ([]modfile.ModSkill, error) {
+ addr, err := address.Parse(raw)
+ if err != nil {
+ return nil, err
+ }
+ matched := entriesFromRepository(m, addr.Repo)
+ if len(matched) == 0 {
+ return nil, fmt.Errorf(i18n.Text("engine.remove.no_entry_from_repository"), raw)
+ }
+ if len(matched) == 1 || all {
+ return matched, nil
+ }
+ if io.Confirm == nil {
+ displayOptions := make([]string, len(matched))
+ for i, skill := range matched {
+ displayOptions[i] = removalOption(skill).Label
+ }
+ return nil, &repositoryCandidatesError{Repo: raw, Candidates: displayOptions}
+ }
+ options := make([]ui.Option, len(matched))
+ for i, skill := range matched {
+ options[i] = removalOption(skill)
+ }
+ picked, err := chooseIndices(io,
+ i18n.Format("engine.remove.select_from_repository", raw),
+ options,
+ func(index int) string { return i18n.Format("engine.remove.confirm_one", matched[index].DirName()) },
+ i18n.Text("engine.remove.no_entries_selected"))
+ if err != nil {
+ return nil, err
+ }
+ out := make([]modfile.ModSkill, 0, len(picked))
+ for _, index := range picked {
+ out = append(out, matched[index])
+ }
+ return out, nil
+}
+
+// repositoryRemovalNames resolves every repository selector in args and
+// returns the names of the entries they match, with the remaining arguments
+// passed through unchanged. It is what the --agent path uses, because
+// unlinking addresses entries by name.
+func repositoryRemovalNames(m *modfile.Mod, args []string, io IO, all bool) ([]string, error) {
+ names := make([]string, 0, len(args))
+ for _, arg := range args {
+ if !strings.Contains(arg, "/") {
+ names = append(names, arg)
+ continue
+ }
+ fromRepo, err := repositoryRemovals(m, arg, io, all)
+ if err != nil {
+ return nil, err
+ }
+ for _, skill := range fromRepo {
+ names = append(names, skill.Name)
+ }
+ }
+ return names, nil
+}
+
+// entriesFromRepository returns the declarations installed from one
+// repository, in declaration order. Local entries never match.
+func entriesFromRepository(m *modfile.Mod, repo string) []modfile.ModSkill {
+ var matched []modfile.ModSkill
+ for _, skill := range m.Skills {
+ if skill.Source == "" {
+ continue
+ }
+ entryRepo, _, err := splitSource(skill.Source)
+ if err != nil {
+ continue // A malformed declaration is reported by the commands that resolve it.
+ }
+ if repoaddr.Identity(entryRepo) == repoaddr.Identity(repo) {
+ matched = append(matched, skill)
+ }
+ }
+ return matched
+}
+
+type repositoryCandidatesError struct {
+ Repo string
+ Candidates []string
+}
+
+func (e *repositoryCandidatesError) Error() string {
+ return i18n.Format("engine.remove.multiple_from_repository", e.Repo, strings.Join(e.Candidates, ", "))
+}
+
// namedRemovals resolves the requested names against the declarations. A name
// selects every entry that answers to it, whether it was published under that
// name or installed under that alias, and a name that matches nothing is
diff --git a/internal/engine/report.go b/internal/engine/report.go
index 85cd7e0..f067598 100644
--- a/internal/engine/report.go
+++ b/internal/engine/report.go
@@ -4,7 +4,11 @@
package engine
-import "github.com/huija/skillmod/internal/i18n"
+import (
+ "encoding/json"
+
+ "github.com/huija/skillmod/internal/i18n"
+)
// Command is the stable machine-readable command that produced a report.
type Command string
@@ -28,6 +32,7 @@ const (
CommandVerify Command = "verify"
CommandWhy Command = "why"
+ ActionAdopt = "adopt"
ActionConflict = "conflict"
ActionDrift = "drift"
ActionInstall = "install"
@@ -77,6 +82,21 @@ type Report struct {
Action Command `json:"action"`
Entries []EntryReport `json:"entries"`
Notes []string `json:"notes,omitempty"`
+ // Error names why the run failed. It is filled in for --json output only,
+ // so a document always carries the reason its command exited non-zero;
+ // without --json the same text reaches stderr instead.
+ Error string `json:"error,omitempty"`
+}
+
+// MarshalJSON renders entries as an array even when the command produced none,
+// so a consumer iterating the field never has to special-case null.
+func (r Report) MarshalJSON() ([]byte, error) {
+ type report Report // Shadow the type to drop the custom marshaler.
+ shadow := report(r)
+ if shadow.Entries == nil {
+ shadow.Entries = []EntryReport{}
+ }
+ return json.Marshal(shadow)
}
// PartialError reports that at least one installation target was safely
diff --git a/internal/engine/sync.go b/internal/engine/sync.go
index 84d5979..ec775f2 100644
--- a/internal/engine/sync.go
+++ b/internal/engine/sync.go
@@ -7,6 +7,7 @@ package engine
import (
"context"
"errors"
+ "fmt"
"github.com/huija/skillmod/internal/dirhash"
"github.com/huija/skillmod/internal/i18n"
@@ -18,12 +19,18 @@ import (
type SyncOptions struct {
CheckOnly bool
Relink bool
- DryRun bool
+ // Adopt declares the skill directories that exist on disk but in neither
+ // manifest as local entries, the way init adopts existing skills.
+ Adopt bool
+ DryRun bool
}
// Sync reconciles local skill directories with SKILL.lock:
// it is idempotent and verifiable, rolls back on failure, and never deletes installed files automatically.
func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report, error) {
+ if options.CheckOnly && options.Adopt {
+ return nil, fmt.Errorf("%s", i18n.Text("engine.sync.adopt_with_check"))
+ }
if options.CheckOnly {
return e.Verify(ctx, io) // sync --check is an alias for verify and uses the same implementation.
}
@@ -45,6 +52,10 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report,
if err != nil {
return nil, err
}
+ // Adopted entries join the declaration here, so the saved mod carries them
+ // alongside the declared ones. An unchanged copy marshals to the same bytes
+ // saveState already read, so a sync that adopts nothing still writes nothing.
+ newMod := &modfile.Mod{SchemaVersion: m.SchemaVersion, Skills: append([]modfile.ModSkill(nil), m.Skills...)}
rep := &Report{Action: CommandSync}
var plans []plannedInstall
var conflicts []conflict
@@ -119,6 +130,16 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report,
}
}
+ // Take stock of the skills another tool or a manual copy left in the
+ // installation directory. They are not failures and not drift, so this
+ // runs after the declared entries are classified and never touches files:
+ // --adopt declares them as local entries, and a plain sync only names them.
+ // A dry run plans the adoption without asking, so the plan never blocks.
+ adopted, err := e.reconcileUndeclaredSkills(options.Adopt, options.DryRun, m, newMod, lock, newLock, io, rep)
+ if err != nil {
+ return nil, err
+ }
+
// Leave stale entry files untouched and recommend prune.
for _, lk := range staleEntries(m, lock) {
rep.Entries = append(rep.Entries, EntryReport{
@@ -189,8 +210,8 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report,
}
// Keep past destinations for cleanup, and record all currently declared
// ones even when this machine did not have an installed copy before sync.
- for _, skill := range m.Skills {
- targets, err := e.shareTargetsFor(m, skill.DirName())
+ for _, skill := range newMod.Skills {
+ targets, err := e.shareTargetsFor(newMod, skill.DirName())
if err != nil {
return nil, err
}
@@ -212,7 +233,9 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report,
}
skipped := skippedConflictCount(conflicts, skip)
var writeErr error
- if planned == 0 && skipped > 0 {
+ if planned == 0 && adopted > 0 {
+ writeErr = io.printf(i18n.Format("engine.sync.dry_run_adopt_planned", adopted))
+ } else if planned == 0 && skipped > 0 {
writeErr = io.printf(i18n.Format("engine.sync.dry_run_writes_planned", skipped))
} else if planned == 0 {
writeErr = io.printf(i18n.Text("engine.sync.dry_run_everything_already"))
@@ -227,7 +250,7 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report,
if err != nil {
return nil, err
}
- if err := e.saveState(m, newLock); err != nil {
+ if err := e.saveState(newMod, newLock); err != nil {
return nil, errors.Join(err, finalize(false))
}
if err := finalize(true); err != nil {
@@ -243,20 +266,36 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report,
}
changed := 0
+ drifted := 0
for _, en := range rep.Entries {
if en.Action == ActionInstall || en.Action == ActionPartial {
changed++
}
- }
- if changed == 0 {
- if skipped := skippedConflictCount(conflicts, skip); skipped > 0 {
- err = io.printf(i18n.Format("engine.sync.changes_conflicting_targets", skipped))
- } else {
- err = io.printf(i18n.Text("engine.sync.changes")) // Idempotency requires a stable no-change result.
+ if en.Action == ActionLocalDrift {
+ drifted++
}
- } else {
+ }
+ skipped := skippedConflictCount(conflicts, skip)
+ switch {
+ case changed == 0 && adopted > 0:
+ err = io.printf(i18n.Format("engine.sync.adopted_entries", adopted))
+ case changed == 0 && skipped > 0:
+ err = io.printf(i18n.Format("engine.sync.changes_conflicting_targets", skipped))
+ case changed == 0 && drifted == 0:
+ err = io.printf(i18n.Text("engine.sync.changes")) // Idempotency requires a stable no-change result.
+ case changed > 0:
err = io.printf(i18n.Text("engine.sync.synchronized_entries"), changed)
}
+ // A run with only drifted local entries prints the drift line alone; the
+ // four cases above all describe alignment work that did not happen.
+ if drifted > 0 {
+ // None of the summaries above name local edits: a run can report no
+ // changes, or install remote entries, while sync silently detected
+ // and preserved the modified local ones. State it explicitly; drift
+ // is the designed steady state for a local entry, not a failure —
+ // verify is the command that judges it.
+ err = errors.Join(err, io.printf(i18n.Format("engine.sync.local_drift_preserved", drifted)))
+ }
return rep, errors.Join(err, partialError(rep, conflicts, skip))
}
diff --git a/internal/i18n/i18n_test.go b/internal/i18n/i18n_test.go
index 8a7b3e6..14f27b7 100644
--- a/internal/i18n/i18n_test.go
+++ b/internal/i18n/i18n_test.go
@@ -183,7 +183,8 @@ func TestContractWordingIsPinned(t *testing.T) {
english := englishCatalog(t)
pinned := map[string]string{
"resolve.branch_not_lockable": "branches cannot be locked; use a tag or commit SHA (%q is a branch name)",
- "engine.skill_mod_found_advice": "SKILL.mod not found\nAdvice: run skillmod init or skillmod get first",
+ "engine.skill_mod_found_advice": "SKILL.mod not found\nAdvice: run skillmod init or skillmod get to manage this directory as a project, or add --global to manage global skills",
+ "engine.skill_mod_found_advice_global": "SKILL.mod not found\nAdvice: run skillmod --global init or skillmod --global get to manage global skills",
"engine.verify.skill_lock_found_advice": "SKILL.lock not found\nAdvice: run skillmod sync first to generate the lock file",
"cli.get.use": "get [//][@]",
"cli.remove.use": "remove [names…]",
diff --git a/internal/store/store.go b/internal/store/store.go
index bd6fa83..04baa4e 100644
--- a/internal/store/store.go
+++ b/internal/store/store.go
@@ -12,7 +12,6 @@
package store
import (
- "bytes"
"crypto/sha256"
"encoding/json"
"errors"
@@ -24,6 +23,7 @@ import (
"path/filepath"
"slices"
"strings"
+ "time"
"github.com/huija/skillmod/internal/dirhash"
"github.com/huija/skillmod/internal/filelock"
@@ -607,6 +607,16 @@ func makeReadOnly(root string) error {
type repoRefsRecord struct {
Repo string `json:"repo"`
Refs resolve.Refs `json:"refs"`
+ // FetchedAt records when the snapshot was taken, so a reader can reuse a
+ // recent one instead of contacting the remote on every read-only command.
+ FetchedAt time.Time `json:"fetchedAt"`
+}
+
+// RepoRefs is one cached ls-remote snapshot: the reference set and when it was
+// taken.
+type RepoRefs struct {
+ Refs *resolve.Refs
+ FetchedAt time.Time
}
func (s *Store) repoRefsPath(repo string) string {
@@ -619,7 +629,7 @@ func (s *Store) repoRefsPath(repo string) string {
// GetRepoRefs returns the last complete ls-remote snapshot for a logical repo.
// Callers may use positive exact-tag matches locally; latest/update must refresh.
-func (s *Store) GetRepoRefs(repo string) (*resolve.Refs, bool, error) {
+func (s *Store) GetRepoRefs(repo string) (*RepoRefs, bool, error) {
p := s.repoRefsPath(repo)
data, err := os.ReadFile(p)
if errors.Is(err, fs.ErrNotExist) {
@@ -641,17 +651,19 @@ func (s *Store) GetRepoRefs(repo string) (*resolve.Refs, bool, error) {
if rec.Refs.Heads == nil {
rec.Refs.Heads = map[string]string{}
}
- return &rec.Refs, true, nil
+ return &RepoRefs{Refs: &rec.Refs, FetchedAt: rec.FetchedAt}, true, nil
}
-// PutRepoRefs atomically records one complete ls-remote snapshot. Equal content
-// is left untouched so multiple skills from the same repo do not churn the file.
+// PutRepoRefs atomically records one complete ls-remote snapshot together with
+// the time it was taken. The fetch time is rewritten on every call, even when
+// the reference set is unchanged, because it is what tells a reader how old
+// its cache is.
func (s *Store) PutRepoRefs(repo string, refs *resolve.Refs) error {
if refs == nil {
return fmt.Errorf("%s", i18n.Text("store.cache_nil"))
}
p := s.repoRefsPath(repo)
- rec := repoRefsRecord{Repo: repoaddr.Identity(repo), Refs: *refs}
+ rec := repoRefsRecord{Repo: repoaddr.Identity(repo), Refs: *refs, FetchedAt: time.Now()}
data, err := json.Marshal(rec)
if err != nil {
return err
@@ -661,9 +673,6 @@ func (s *Store) PutRepoRefs(repo string, refs *resolve.Refs) error {
return err
}
defer unlock()
- if existing, err := os.ReadFile(p); err == nil && bytes.Equal(existing, data) {
- return nil
- }
if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
return err
}
diff --git a/internal/store/store_test.go b/internal/store/store_test.go
index d911ac5..82b865f 100644
--- a/internal/store/store_test.go
+++ b/internal/store/store_test.go
@@ -321,8 +321,11 @@ func TestRepoRefs_RoundTripAndCanonicalIdentity(t *testing.T) {
if err != nil || !ok {
t.Fatalf("GetRepoRefs = %+v, %v, %v", got, ok, err)
}
- if !reflect.DeepEqual(got, want) {
- t.Fatalf("GetRepoRefs = %+v, want %+v", got, want)
+ if !reflect.DeepEqual(got.Refs, want) {
+ t.Fatalf("GetRepoRefs = %+v, want %+v", got.Refs, want)
+ }
+ if got.FetchedAt.IsZero() {
+ t.Fatal("GetRepoRefs returned no fetch time")
}
if err := s.PutRepoRefs("ssh://git@example.com:22/acme/skills.git", want); err != nil {
t.Fatal(err)
@@ -658,9 +661,12 @@ func TestRepoRefsCacheValidation(t *testing.T) {
t.Fatal(err)
}
refs, ok, err := s.GetRepoRefs(repo)
- if err != nil || !ok || refs.Tags == nil || refs.Heads == nil {
+ if err != nil || !ok || refs.Refs.Tags == nil || refs.Refs.Heads == nil {
t.Fatalf("normalized refs = %+v, %v, %v", refs, ok, err)
}
+ if refs.FetchedAt.IsZero() {
+ t.Fatal("cached refs carry no fetch time")
+ }
path := s.repoRefsPath(repo)
if err := os.WriteFile(path, []byte("{"), 0o600); err != nil {
@@ -681,6 +687,26 @@ func TestRepoRefsCacheValidation(t *testing.T) {
if _, _, err := s.GetRepoRefs(repo); err == nil || !strings.Contains(err.Error(), "identity mismatch") {
t.Fatalf("mismatched refs error = %v", err)
}
+
+ // A snapshot written before the fetch time was recorded carries none, which
+ // reads as stale rather than as fresh: refreshing one old file is safe,
+ // treating an unknown age as new silently answers from a snapshot that may
+ // be any age. The record is still valid, so the hit succeeds.
+ legacy := repoRefsRecord{Repo: repo, Refs: resolve.Refs{Tags: map[string]string{"v1.0.0": "refs/tags/v1.0.0"}}}
+ data, err = json.Marshal(legacy)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(path, data, 0o600); err != nil {
+ t.Fatal(err)
+ }
+ refs, ok, err = s.GetRepoRefs(repo)
+ if err != nil || !ok {
+ t.Fatalf("legacy refs = %+v, %v, %v", refs, ok, err)
+ }
+ if !refs.FetchedAt.IsZero() {
+ t.Errorf("legacy refs FetchedAt = %v, want the zero time that reads as stale", refs.FetchedAt)
+ }
}
func TestStoreErrorDiagnostics(t *testing.T) {
diff --git a/locales/en_US.po b/locales/en_US.po
index fe689b5..7995b38 100644
--- a/locales/en_US.po
+++ b/locales/en_US.po
@@ -213,6 +213,9 @@ msgstr "Record installed skills as linked into other agent directories"
msgid "cli.share.use"
msgstr "share [skills...]"
+msgid "cli.sync.flag_adopt"
+msgstr "declare skills added outside skillmod as local entries"
+
msgid "cli.sync.flag_check"
msgstr "verify without modifying anything (alias for skillmod verify)"
@@ -436,9 +439,14 @@ msgstr "%s — %s\n %s"
msgid "engine.get.reading_skill_metadata"
msgstr "reading skill metadata"
+#, go-format
+msgid "engine.get.short_address_resolved"
+msgstr "the short address was resolved as %s; for a local repository, use t"
+"he file:// prefix"
+
msgid "engine.get.skill_md_missing_repository"
-msgstr "SKILL.md is missing from the repository root and every descendant o"
-"f skills/"
+msgstr "no SKILL.md found; looked in the repository root, skills/, agent sk"
+"ill directories such as .agents/skills, and root-level skill directories"
#, go-format
msgid "engine.get.skill_name_matches_multiple"
@@ -524,6 +532,10 @@ msgid "engine.init.skills_found_generated_empty"
msgstr "no skills found; generated an empty manifest—use skillmod get to "
"add one"
+msgid "engine.init.skills_found_will_generate_empty"
+msgstr "no skills found; will generate an empty manifest—use skillmod get"
+" to add one"
+
#, go-format
msgid "engine.init.source_unverified_local"
msgstr "source could not be verified; kept as local: %v"
@@ -723,6 +735,11 @@ msgstr "local entry, no version"
msgid "engine.remove.locally_modified_kept"
msgstr "locally modified; kept installed files: "
+#, go-format
+msgid "engine.remove.multiple_from_repository"
+msgstr "multiple entries come from %s; rerun interactively to select one or"
+" more, or name them: %s"
+
msgid "engine.remove.needs_selection"
msgstr "no entries were requested; pass names or --all, or run remove in a "
"terminal"
@@ -730,6 +747,10 @@ msgstr "no entries were requested; pass names or --all, or run remove in a "
msgid "engine.remove.no_entries_selected"
msgstr "no entries were selected"
+#, go-format
+msgid "engine.remove.no_entry_from_repository"
+msgstr "no entry in SKILL.mod comes from %s"
+
msgid "engine.remove.nothing_declared"
msgstr "SKILL.mod declares no entries"
@@ -740,6 +761,10 @@ msgstr "removed %d declarations and %d clean installation directories"
msgid "engine.remove.select_entries"
msgstr "select the entries to remove"
+#, go-format
+msgid "engine.remove.select_from_repository"
+msgstr "multiple skills from %s; select one or more"
+
msgid "engine.remove.share_cleanup_failed"
msgstr "failed to remove some share links"
@@ -882,8 +907,12 @@ msgstr "SKILL.lock is tool-maintained; repair the listed entry by hand, or "
"back up and delete the file, then re-run skillmod sync to regenerate it"
msgid "engine.skill_mod_found_advice"
-msgstr "SKILL.mod not found\nAdvice: run skillmod init or skillmod get firs"
-"t"
+msgstr "SKILL.mod not found\nAdvice: run skillmod init or skillmod get to m"
+"anage this directory as a project, or add --global to manage global skills"
+
+msgid "engine.skill_mod_found_advice_global"
+msgstr "SKILL.mod not found\nAdvice: run skillmod --global init or skillmod"
+" --global get to manage global skills"
#, go-format
msgid "engine.skill_path_not_materializable"
@@ -935,6 +964,41 @@ msgstr "restore %s: %w"
msgid "engine.state.stage_removal"
msgstr "stage removal of %s: %w"
+#, go-format
+msgid "engine.sync.adopt_case_collision"
+msgstr "two skills differ only by letter case: %s and %s, which map to one "
+"installation directory; rename one of the directories"
+
+#, go-format
+msgid "engine.sync.adopt_confirm"
+msgstr "adopt %s (%s) as a local entry?"
+
+msgid "engine.sync.adopt_dry_run_confirm"
+msgstr "a real run confirms each one; pass --yes to adopt all"
+
+msgid "engine.sync.adopt_dry_run_entry"
+msgstr "will be adopted as a local entry on a real run"
+
+#, go-format
+msgid "engine.sync.adopt_needs_confirmation"
+msgstr "found %d undeclared skills; pass --yes to adopt them all, or run in"
+" a terminal to choose"
+
+#, go-format
+msgid "engine.sync.adopt_skipped"
+msgstr "skipped %s: %s"
+
+msgid "engine.sync.adopt_with_check"
+msgstr "--adopt cannot be combined with --check, which only verifies and ne"
+"ver writes"
+
+#, go-format
+msgid "engine.sync.adopted_entries"
+msgstr "adopted %d local entries"
+
+msgid "engine.sync.adopted_local_entry"
+msgstr "adopted as a local entry"
+
msgid "engine.sync.baseline_re_established"
msgstr "baseline re-established from the installed files (the previous remo"
"te lock record was removed)"
@@ -956,6 +1020,10 @@ msgstr "consistent"
msgid "engine.sync.contents_match_baseline_local"
msgstr "contents do not match the baseline (local changes)"
+#, go-format
+msgid "engine.sync.dry_run_adopt_planned"
+msgstr "dry-run: %d undeclared skills would be adopted"
+
#, go-format
msgid "engine.sync.dry_run_entries_installed"
msgstr "dry-run: %d entries would be installed or updated"
@@ -967,6 +1035,11 @@ msgstr "dry-run: everything is already consistent"
msgid "engine.sync.dry_run_writes_planned"
msgstr "dry-run: no writes planned; %d conflicting targets would be kept"
+#, go-format
+msgid "engine.sync.local_drift_preserved"
+msgstr "%d local entries differ from their lock records; edits are kept as-"
+"is"
+
msgid "engine.sync.missing"
msgstr "missing: "
@@ -974,6 +1047,9 @@ msgid "engine.sync.no_baseline"
msgstr "no baseline in the lock; verification skipped (run init again to es"
"tablish one)"
+msgid "engine.sync.no_skills_adopted"
+msgstr "no undeclared skills were adopted"
+
msgid "engine.sync.removed_mod_files_kept"
msgstr "removed from the mod; files were kept—run skillmod prune to clean"
" them"
@@ -985,6 +1061,11 @@ msgstr "recreating some share links failed; run sync again to retry"
msgid "engine.sync.synchronized_entries"
msgstr "synchronized %d entries; verification passed"
+#, go-format
+msgid "engine.sync.undeclared_skills_found"
+msgstr "found %d undeclared skills; run skillmod sync --adopt to declare th"
+"em as local entries"
+
msgid "engine.update.already_up_to_date"
msgstr "already up to date"
diff --git a/locales/zh_CN.po b/locales/zh_CN.po
index 226f6fc..be7e837 100644
--- a/locales/zh_CN.po
+++ b/locales/zh_CN.po
@@ -211,6 +211,9 @@ msgstr "把已安装技能记录为链接到其他 agent 目录"
msgid "cli.share.use"
msgstr "share [技能名...]"
+msgid "cli.sync.flag_adopt"
+msgstr "把 skillmod 之外新增的 skill 收录为本地条目"
+
msgid "cli.sync.flag_check"
msgstr "只校验不修改(skillmod verify 的别名)"
@@ -429,9 +432,14 @@ msgstr "%s — %s\n %s"
msgid "engine.get.reading_skill_metadata"
msgstr "正在读取 skill 元数据"
+#, go-format
+msgid "engine.get.short_address_resolved"
+msgstr "简写地址已解析为 %s;若指本地仓库,请使用 file:/"
+"/ 前缀"
+
msgid "engine.get.skill_md_missing_repository"
-msgstr "仓库根目录及 skills/ 下所有子目录中均未找到 SKILL."
-"md"
+msgstr "未找到 SKILL.md;已检查仓库根目录、skills/、.agents/s"
+"kills 等 agent 技能目录,以及根目录下的技能目录"
#, go-format
msgid "engine.get.skill_name_matches_multiple"
@@ -512,6 +520,9 @@ msgstr "正在恢复已安装技能来源:%s"
msgid "engine.init.skills_found_generated_empty"
msgstr "未发现 skill,已生成空清单,可用 skillmod get 添加"
+msgid "engine.init.skills_found_will_generate_empty"
+msgstr "未发现 skill,将生成空清单,可用 skillmod get 添加"
+
#, go-format
msgid "engine.init.source_unverified_local"
msgstr "无法验证来源,保留为本地技能:%v"
@@ -708,6 +719,11 @@ msgstr "本地条目,无版本"
msgid "engine.remove.locally_modified_kept"
msgstr "存在本地修改,已保留安装文件:"
+#, go-format
+msgid "engine.remove.multiple_from_repository"
+msgstr "%s 中有多个条目;交互模式中选择一个或多个,或"
+"直接指定:%s"
+
msgid "engine.remove.needs_selection"
msgstr "未指定条目;请给出名称或传 --all,或在终端中运"
"行 remove"
@@ -715,6 +731,10 @@ msgstr "未指定条目;请给出名称或传 --all,或在终端中运"
msgid "engine.remove.no_entries_selected"
msgstr "未选择任何条目"
+#, go-format
+msgid "engine.remove.no_entry_from_repository"
+msgstr "SKILL.mod 中没有来自 %s 的条目"
+
msgid "engine.remove.nothing_declared"
msgstr "SKILL.mod 中没有声明条目"
@@ -725,6 +745,10 @@ msgstr "已删除 %d 个声明和 %d 个内容未改动的安装目录"
msgid "engine.remove.select_entries"
msgstr "选择要删除的条目"
+#, go-format
+msgid "engine.remove.select_from_repository"
+msgstr "%s 中有多个 skill;选择一个或多个"
+
msgid "engine.remove.share_cleanup_failed"
msgstr "清理部分分享链接失败"
@@ -865,7 +889,13 @@ msgstr "SKILL.lock 由工具维护;请手工修复出错的条目,或"
"备份并删除该文件后重新运行 skillmod sync 重新生成"
msgid "engine.skill_mod_found_advice"
-msgstr "未找到 SKILL.mod\n建议先执行 skillmod init 或 skillmod get"
+msgstr "未找到 SKILL.mod\n建议:执行 skillmod init 或 skillmod get"
+" 将当前目录作为项目管理;若要管理全局技能,请在命"
+"令中加入 --global"
+
+msgid "engine.skill_mod_found_advice_global"
+msgstr "未找到 SKILL.mod\n建议先执行 skillmod --global init 或 ski"
+"llmod --global get 管理全局技能"
#, go-format
msgid "engine.skill_path_not_materializable"
@@ -917,6 +947,41 @@ msgstr "恢复 %s 失败:%w"
msgid "engine.state.stage_removal"
msgstr "暂存删除 %s 失败:%w"
+#, go-format
+msgid "engine.sync.adopt_case_collision"
+msgstr "两个 skill 仅大小写不同:%s 与 %s,会映射到同一个"
+"安装目录;请重命名其中一个目录"
+
+#, go-format
+msgid "engine.sync.adopt_confirm"
+msgstr "将 %s(%s)收录为本地条目?"
+
+msgid "engine.sync.adopt_dry_run_confirm"
+msgstr "真实运行将逐个确认;传 --yes 全部收录"
+
+msgid "engine.sync.adopt_dry_run_entry"
+msgstr "真实运行将收录为本地条目"
+
+#, go-format
+msgid "engine.sync.adopt_needs_confirmation"
+msgstr "发现 %d 个未声明 skill;传 --yes 全部收录,或在终"
+"端中选择"
+
+#, go-format
+msgid "engine.sync.adopt_skipped"
+msgstr "跳过 %s:%s"
+
+msgid "engine.sync.adopt_with_check"
+msgstr "--adopt 不能与 --check 同时使用;--check 只校验、不写"
+"任何文件"
+
+#, go-format
+msgid "engine.sync.adopted_entries"
+msgstr "已收录 %d 个本地条目"
+
+msgid "engine.sync.adopted_local_entry"
+msgstr "已收录为本地条目"
+
msgid "engine.sync.baseline_re_established"
msgstr "已从已安装文件重建本地基线(此前的 remote lock 记"
"录已移除)"
@@ -938,6 +1003,10 @@ msgstr "一致"
msgid "engine.sync.contents_match_baseline_local"
msgstr "内容与基线不符(本地改动)"
+#, go-format
+msgid "engine.sync.dry_run_adopt_planned"
+msgstr "dry-run: 将收录 %d 个未声明 skill"
+
#, go-format
msgid "engine.sync.dry_run_entries_installed"
msgstr "dry-run: %d 个条目将被安装或更新"
@@ -949,6 +1018,10 @@ msgstr "dry-run: 所有条目已一致"
msgid "engine.sync.dry_run_writes_planned"
msgstr "试运行:没有计划写入;将保留 %d 个冲突目标"
+#, go-format
+msgid "engine.sync.local_drift_preserved"
+msgstr "%d 个本地条目与锁定记录不一致(改动保留)"
+
msgid "engine.sync.missing"
msgstr "缺失: "
@@ -956,6 +1029,9 @@ msgid "engine.sync.no_baseline"
msgstr "lock 中无基线记录,跳过校验(重新 init 可建立基"
"线)"
+msgid "engine.sync.no_skills_adopted"
+msgstr "没有收录任何未声明 skill"
+
msgid "engine.sync.removed_mod_files_kept"
msgstr "已从 mod 移除,文件保留;运行 skillmod prune 清理"
@@ -966,6 +1042,11 @@ msgstr "重建部分分享链接失败;再次运行 sync 可重试"
msgid "engine.sync.synchronized_entries"
msgstr "已同步 %d 项,校验通过"
+#, go-format
+msgid "engine.sync.undeclared_skills_found"
+msgstr "发现 %d 个未声明 skill;运行 skillmod sync --adopt 可将"
+"它们收录为本地条目"
+
msgid "engine.update.already_up_to_date"
msgstr "已是最新"
diff --git a/skills/skillmod/SKILL.md b/skills/skillmod/SKILL.md
index e0d8656..2fd7eb5 100644
--- a/skills/skillmod/SKILL.md
+++ b/skills/skillmod/SKILL.md
@@ -5,88 +5,72 @@ description: Install, configure, use, and troubleshoot skillmod, or prepare a we
# skillmod
-skillmod is a Git-based dependency manager for Agent Skills: `SKILL.mod`
-declares what a project needs, `SKILL.lock` pins the exact content, and
-`skillmod sync` makes every machine identical. Reach for it when the user
-wants to share one skill set across machines, teammates, or CI, or to point
-agent directories such as `.claude` or `.codex` at installed skills.
+skillmod manages Agent Skills the way Go modules manage dependencies. The
+project declares what it needs in `SKILL.mod`, skillmod pins the exact
+content in `SKILL.lock`, and `skillmod sync` makes every machine agree.
-Help users install and operate skillmod safely. Match the user's language and
-experience level. Explain the outcome first, then show only the commands needed
-for the current task.
+Reach for it when skills have to be the same on more than one machine, when
+CI has to prove the installed skills are the declared ones, or when several
+agents on one machine should share one installed set.
-## Route the request
+Help the user install and run skillmod safely. Answer in their language,
+match their experience, and lead with the outcome before the commands.
-- For prerequisite checks, first-time installation, upgrades of the executable,
- or PATH problems, read [references/setup.md](references/setup.md).
-- For project/global setup, dependency operations, CI, inspection, updates,
- removal, or troubleshooting, read
- [references/use-cases.md](references/use-cases.md).
-- For manifest rules, accepted address and version forms, aliases, and what the
- files deliberately leave out, read
- [references/manifests.md](references/manifests.md).
-- For the shared cache, installation modes, configuration file, or where
- declarations and installations live, read
- [references/storage.md](references/storage.md).
-- For exit codes and the JSON report vocabulary that scripts and CI branch on,
- read [references/automation.md](references/automation.md).
-- When the user explicitly wants to report a problem, or diagnosis strongly
- indicates a skillmod defect, read
- [references/issue-reporting.md](references/issue-reporting.md).
+## Where to look
-Read only the references needed for the current request. Installation is not
-required before explaining concepts or drafting an issue.
+| The request is about | Read |
+| --- | --- |
+| Installing or upgrading the executable, prerequisites, PATH problems | [references/setup.md](references/setup.md) |
+| Setting up a project or the machine, adding or removing skills, CI, checking state | [references/use-cases.md](references/use-cases.md) |
+| What belongs in `SKILL.mod`, address and version forms, aliases | [references/manifests.md](references/manifests.md) |
+| Cache layout, install modes, the config file, where things live | [references/storage.md](references/storage.md) |
+| Exit codes, `--json`, what a script should branch on | [references/automation.md](references/automation.md) |
+| Reporting a bug | [references/issue-reporting.md](references/issue-reporting.md) |
-## Core workflow
+Read only what the current request needs. Explaining a concept or drafting an
+issue does not require an installation.
-1. Establish whether the user is operating on project scope or global scope.
- Do not add `--global` unless the user wants user-wide skills.
-2. At the start of setup or diagnosis, check that both `git` and `skillmod` are
- available. Do not repeat those checks during ordinary operations when the
- current session has already established them, and do not reinstall a working
- executable merely because installation was mentioned in an earlier step.
-3. Project and global scopes are independent: each has its own manifest, and
- either can be adopted alone — `skillmod init` for the project,
- `skillmod --global init` for the user-wide skills — in either order. Keep
- the scopes straight afterwards: a command affects the machine only when
- it carries `--global`.
-4. Inspect existing `SKILL.mod`, `SKILL.lock`, configuration, and installed
- directories before proposing a mutation. Preserve unrelated user changes.
-5. Prefer `--dry-run` before `init --force`, `sync --relink`, `remove`, or
- `prune` when the result is not already obvious to the user.
-6. Run the smallest command that satisfies the request and verify its result.
- Use `skillmod list`, `skillmod why `, or `skillmod verify`
- rather than inferring state from directory names alone.
+## How to work
-## Invariants
+1. Settle the scope first. Project is the default; add `--global` only when
+ the user means the skills for the whole machine. The two scopes have
+ separate manifests and never merge.
+2. Before diagnosing, check that `git` and `skillmod` both run. After that,
+ don't re-check them or reinstall a working executable just because
+ installation came up earlier in the conversation.
+3. Look before you touch: read `SKILL.mod`, `SKILL.lock`, the config file,
+ and the installed directories, and leave anything unrelated alone.
+4. Run `--dry-run` first when the result isn't obvious — `init --force`,
+ `sync --relink`, `sync --adopt`, `remove`, `prune`.
+5. Then run the smallest command that does the job and check what it did.
+ Use `list`, `why `, or `verify` rather than guessing from
+ directory names.
-- Treat `SKILL.mod` as the human-maintained declaration and `SKILL.lock` as
- tool-maintained state. Do not hand-edit `SKILL.lock` unless recovery is the
- explicit task and a backup has been made.
-- Do not silently overwrite a locally modified installation. Exit code 3 means
- independent work completed while one or more targets were safely preserved;
- inspect the report instead of treating it as total failure or total success.
-- Exit code 2 from `verify` means drift. Exit code 1 is an operational error.
-- Branch names are mutable and cannot be locked. Use a semantic-version tag, a
- full 40-character commit SHA, or let skillmod resolve an immutable version.
-- Keep repository addresses credential-free and free of an implied transport. A
- password or token in the user information, a query string, or a fragment is
- rejected instead of persisted, and `source` records `host/owner/repo` rather
- than an `https://` spelling. The version belongs in the `version` field, not
- as an `@version` suffix in `source`. Direct the user to a credential helper,
- an SSH agent, or the environment for secrets.
-- Installation directories are generated state. Preserve `SKILL.mod` and
- `SKILL.lock` in version control; do not commit installed skill directories
- unless the project deliberately chooses to do so.
-- Shared snapshots may be referenced by links from multiple projects. Never
- delete the cache as a shortcut for removing one dependency.
-- Downloading executables, changing PATH, installing packages, authenticating
- GitHub CLI, and creating an issue are external mutations. Confirm the user's
- intent immediately before any such action not already explicitly requested.
+## Rules worth keeping
-## Reporting results
+- `SKILL.mod` is for people and goes in version control. `SKILL.lock` is
+ skillmod's own; don't hand-edit it unless recovery is the task and a
+ backup exists.
+- Never overwrite a locally edited installation to make a report look
+ clean. Exit code 3 means part of the work was done and some targets were
+ kept on purpose — read the report, don't retry blindly. Exit code 2 means
+ drift. Exit code 1 means something went wrong.
+- Branch names can't be locked. Use a tag, a full 40-character commit, or
+ let skillmod pick an immutable version.
+- Keep addresses credential-free: no passwords or tokens in the URL, no
+ query strings, no fragments. `source` records `host/owner/repo`, and the
+ host defaults to `github.com`, so `owner/repo` is enough.
+- Installed skill directories are build output. Don't commit them unless the
+ project decided to.
+- One installed copy can be linked from several projects. Never "fix" a
+ removal by deleting the cache.
+- Downloading a binary, changing `PATH`, installing packages, or filing an
+ issue reaches outside the machine — confirm right before doing it, unless
+ the user already asked for it.
-State which scope was affected, which declaration or installation changed,
-whether verification passed, and whether anything was preserved because of a
-conflict. For JSON workflows, make decisions from stable fields and action
-values rather than localized `note` text.
+## Reporting back
+
+Say which scope was affected, what changed, whether `verify` passed, and
+whether anything was kept because of a conflict. For `--json` runs, decide
+from the stable fields and action values, never from the translated `note`
+text.
diff --git a/skills/skillmod/references/automation.md b/skills/skillmod/references/automation.md
index 100de27..a68fac8 100644
--- a/skills/skillmod/references/automation.md
+++ b/skills/skillmod/references/automation.md
@@ -16,18 +16,25 @@ skillmod run instead of a person reading its output.
of overwriting it. That is not total failure and not total success; read the
report to see what was preserved and why.
-An in-progress command prints its human summary as usual. Add `--json` to also
-emit a structured report on stdout.
-
## JSON reports
+`--json` (`-j`) writes exactly one document to stdout and nothing else — the
+human summary is not printed in that mode, and a failing run writes a document
+too, with an `error` field naming the failure and the same exit code it would
+have had anyway. That holds whether the command failed partway through or
+before it could report anything at all, so the document is the one place a job
+has to look. A `grep` for `"error"` therefore tells the two outcomes apart
+without parsing anything. Only a usage error, such as an unknown flag, stays
+plain text on stderr with exit code 1, because no command ran to produce a
+report.
+
A report separates the command that ran from the outcome of each declaration and
of each installation directory.
| Field | Meaning | `action` values |
| --- | --- | --- |
| `action` | The command that produced the report | `get`, `init`, `list`, `prune`, `remove`, `share`, `sync`, `update`, `upgrade`, `verify`, `why` |
-| `entries[].action` | The aggregate outcome of one declaration | `conflict`, `drift`, `install`, `installed`, `keep`, `local`, `local-drift`, `matched`, `missing`, `partial`, `prune`, `remove`, `skip`, `stale`, `unlocked`, `unresolved`, `unverifiable`, `update` |
+| `entries[].action` | The aggregate outcome of one declaration | `adopt`, `conflict`, `drift`, `install`, `installed`, `keep`, `local`, `local-drift`, `matched`, `missing`, `partial`, `prune`, `remove`, `skip`, `stale`, `unlocked`, `unresolved`, `unverifiable`, `update` |
| `entries[].targetResults[].action` | The outcome of one installation directory | `drift`, `install`, `installed`, `keep`, `missing`, `remove`, `skip`, `unlocked`, `unverifiable` |
Per-directory facts appear only in `targetResults`, which is where a conflicting
@@ -42,7 +49,8 @@ executable's own `targetResults[0].action` says what happened to the file:
`keep` means it was left alone. The report is written even when the upgrade
fails, so `--json` always decodes one document.
-Add `--json` to `list`, `why`, and `verify` for the report shape shown below:
+Every command takes `--json`. The shape is the same everywhere; the example is
+a `verify` run:
```json
{
@@ -69,6 +77,21 @@ Add `--json` to `list`, `why`, and `verify` for the report shape shown below:
}
```
+A failing run keeps the same shape and adds `"error": "..."` with the message
+that would otherwise have gone to stderr:
+
+```json
+{
+ "action": "get",
+ "entries": [],
+ "error": "no skill named \"nope\" in github.com/openai/skills; the repository provides: gh-fix-ci"
+}
+```
+
+`entries` is always an array, and a document with `error` has no entries for
+the work that never started. Read the exit code for the outcome class, the
+`action` field for the command, and `error` when the run failed.
+
Inspection reports (`list`, `why`, and `verify`) also carry `requestedVersion`
for remote entries: it is the exact `SKILL.mod` value, while `version` is the
installed version from `SKILL.lock`. An empty `requestedVersion` means the
diff --git a/skills/skillmod/references/manifests.md b/skills/skillmod/references/manifests.md
index 0cb2669..2436f4c 100644
--- a/skills/skillmod/references/manifests.md
+++ b/skills/skillmod/references/manifests.md
@@ -17,6 +17,12 @@ breaks a rule is reported instead of being halfway applied.
changes how the repository is fetched. A file that still spells out
`https://` works unchanged and is rewritten to the shorter form the next time
skillmod writes it.
+- A bare `owner/repo` path is completed with `github.com`, the host nearly
+ every skill repository lives on, so `openai/skills` and
+ `github.com/openai/skills` are the same repository. A first segment that
+ already carries a dot is a host, and so is one that carries a port. A first
+ segment that is empty, `.`, or `..` reads as a filesystem path — the same for
+ a Windows drive letter — and none of those take the `github.com` default.
- `version` is optional. An entry without one tracks the latest immutable
resolution, which `SKILL.lock` pins. An entry with one is pinned to that tag
or commit until `update` runs.
@@ -63,9 +69,33 @@ Git credential helper, an SSH agent, or the environment.
When `//` is a single segment, skillmod first tries an exact
subdirectory of the repository root, then falls back to a unique skill name
-anywhere below `skills/`. Ambiguous names require the full path. Omitting
-`//` makes `get` discover the root `SKILL.md` and every `SKILL.md`
-below `skills/`.
+found anywhere in the repository. Ambiguous names require the full path.
+Omitting `//` makes `get` discover every `SKILL.md` the
+repository publishes, wherever that is: the repository root itself, a `skills/`
+collection at any depth, an agent collection such as `.agents/skills/` or
+`.claude/skills/`, and the root-level directories. Those four are always
+scanned, so a repository that publishes a collection can still leave a skill in
+another root directory and have it installed.
+
+A repository sometimes publishes the same skill under more than one of those
+roots — `skills/` alongside `.openclaw/skills/` is the common case, because an
+agent directory is a mirror maintained for one agent. Both would install into
+one directory under one name, so `get` keeps a single copy, from the root the
+repository's own layout comes from first:
+
+| Kept copy | Discarded copies |
+| --- | --- |
+| `skills/` | a root-level `/`, and any agent collection |
+| root-level `/` | any agent collection |
+| an agent collection | nothing, for the same skill — no agent directory outranks another |
+
+Two agents holding the same skill, with no ranking between them, are not
+collapsed: `get` reports both paths and asks, the way it does for any other
+ambiguous name. Within one collection, two directories sharing a skill name are
+two skills, not a duplicate, and are reported the same way.
+
+An exact subdirectory always wins over discovery, so a repository only has to
+look conventional to people who never type a path.
## The per-skill `agents` list
diff --git a/skills/skillmod/references/storage.md b/skills/skillmod/references/storage.md
index e95d3af..23bc474 100644
--- a/skills/skillmod/references/storage.md
+++ b/skills/skillmod/references/storage.md
@@ -41,7 +41,14 @@ touching the remote. An explicit `@commit` reuses an existing snapshot of that
commit the same way. Requesting latest, or running `skillmod update`, keeps
online refresh semantics.
-Set `SKILLMOD_HOME` to relocate the store.
+Each `ls-remote` result is cached with the time it was taken. `list` reuses a
+snapshot younger than 15 minutes instead of contacting every declared
+repository again, which is what keeps `list --global` fast on a machine with
+many skills; `update` is the command that deliberately refreshes, and a `list`
+run after a new tag shows it. `why` and `verify` never contact the remote at
+all — they answer from `SKILL.mod`, `SKILL.lock`, and the installed content —
+so they report the local state rather than a snapshot. Set `SKILLMOD_HOME` to
+relocate the store.
`--dry-run` leaves manifests and installations untouched, though remote
provenance verification may still populate the shared cache.
diff --git a/skills/skillmod/references/use-cases.md b/skills/skillmod/references/use-cases.md
index e6875a9..90f96e2 100644
--- a/skills/skillmod/references/use-cases.md
+++ b/skills/skillmod/references/use-cases.md
@@ -94,6 +94,9 @@ one unresolved entry does not discard the rest of the import.
Import writes both `SKILL.mod` and `SKILL.lock`. Replacing an existing
declaration requires `--force`, which first backs it up as `SKILL.mod.bak`.
+Every detected entry is confirmed before the write, so a non-interactive
+environment passes `--yes`; a scan that finds nothing has no entry to confirm
+and writes the empty manifest rather than stopping at an unanswerable prompt.
Use global scope only when requested:
@@ -113,20 +116,28 @@ Addresses have this form:
Examples:
```sh
+skillmod get openai/skills//gh-fix-ci
skillmod get github.com/acme/agent-skills//skills/review@v1.2.0
skillmod get github.com/acme/agent-skills//review
skillmod get github.com/acme/single-skill
```
-The repository is always named; `//` then selects the skill inside it. The
-second form writes the skill name in place of its path, so a collection is
-addressed with two short words instead of the directory layout. An exact
-subdirectory always wins over a name, and a unique name resolves to the skill's
-real path, so `source` records
+The repository is always named; `//` then selects the skill inside it. The host
+defaults to `github.com`, so `openai/skills//gh-fix-ci` is the shortest
+spelling of `github.com/openai/skills//gh-fix-ci`. `//review` writes the skill
+name in place of its path, so a collection is addressed with two short words
+instead of the directory layout, and `@v1.2.0` pins an explicit version on that
+same form. An exact subdirectory always wins over a name, and a unique name
+resolves to the skill's real path, so `source` records
`github.com/acme/agent-skills//skills/review` rather than the shorthand that was
typed. When several skills in the repository answer the same name, skillmod
reports the candidate paths and refuses to guess. A repository that is itself a
-single skill needs no `//`, as in the third form.
+single skill needs no `//`, as `github.com/acme/single-skill` shows.
+
+Discovery does not assume a layout. A collection usually lives under `skills/`,
+but a repository whose skills sit directly in the root, or under an agent
+directory such as `.agents/skills/` or `.claude/skills/`, is scanned the same
+way, so unusual repositories install without anyone typing an internal path.
Omitting a version asks skillmod to resolve the latest immutable tag, with a
pseudo-version fallback for an untagged repository. A branch name is rejected,
@@ -182,6 +193,28 @@ skillmod sync --relink --dry-run
skillmod sync --relink
```
+Use `sync --adopt` when skills appeared on disk outside skillmod — installed by
+`npx`, copied in, or written by hand. It declares each one as a local entry and
+records its current content as the lock baseline, which is the same thing `init`
+does for a machine's existing skills. No file is rewritten, so a later edit
+shows up as `local-drift` instead of being reset:
+
+```sh
+skillmod sync --dry-run --adopt
+skillmod sync --adopt --yes
+```
+
+Each adopted skill is confirmed in a terminal, and `--yes` adopts all of them.
+A plain `sync` does not change the declaration; it names the undeclared skills
+and points at the flag. A directory a stale lock record still occupies is left
+for `prune`, never adopted.
+
+`sync --adopt` cannot be combined with `--check`: `--check` is `verify`, which
+only reports drift and never writes. A non-interactive run without `--yes` is
+refused and told to pass `--yes`, rather than adopting skills nobody approved;
+`sync --adopt --dry-run` plans the whole set without asking, because printing a
+plan must not block on a prompt.
+
## Inspect state and provenance
Use `list` for the complete declaration overview:
@@ -275,8 +308,22 @@ skillmod remove --all
skillmod remove
```
-`--all` takes every declared entry without asking. A bare `remove` picks from
-the declarations interactively, so it needs a terminal; `--yes` is not a
+A positional argument that contains a `/` is a repository selector instead,
+which is the same distinction a skill name can never trip: names are single
+portable segments. Name the repository and the skills declared from it are
+selected, exactly the way `get` lists what a repository publishes — one entry
+needs no choice, several are offered in a terminal, and a non-interactive run
+lists them and exits:
+
+```sh
+skillmod remove github.com/acme/agent-skills --dry-run
+skillmod remove openai/skills
+```
+
+`--all` takes every declared entry without asking, and with a repository
+selector it takes every entry that repository declares, which is how a script
+says "everything this repository brought in". A bare `remove` picks from the
+declarations interactively, so it needs a terminal; `--yes` is not a
substitute for either, because it answers the deletion confirmation rather than
choosing what to delete.
@@ -292,7 +339,9 @@ skillmod remove --all --agent claude
Without skill names, the picker offers only skills shared to the named agents
and starts with nothing checked. With `--all`, all matching skills are unshared;
skills shared only to other agents are unaffected. Agent values may repeat or
-use comma-separated names. Names and `--all` cannot be combined.
+use comma-separated names. A skill name and `--all` cannot be combined, because
+each already states the set; a repository selector can, and `--all` then takes
+everything it declares.
Clean managed installations are removed transactionally. Locally modified or
unverifiable directories are preserved and reported as partial completion.
]