From 54a5145d3ccf9cf38857f3b5317906be12f0aecf Mon Sep 17 00:00:00 2001 From: Jingchao Date: Wed, 12 Aug 2026 09:19:07 +0800 Subject: [PATCH 1/2] docs: highlight providers/targets, add tag-triggered release workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README: add Provider/Target tables, condense Install+Quick start+ Everyday workflows into one TUI-first Quick start, fold Extend it and Configure your tools into the Provider/Target customization section, add emoji + Release badge. CI: add release.yml — cross-builds linux/darwin amd64/arm64 on tag push and publishes a draft GitHub Release with checksums. --- .github/workflows/release.yml | 58 ++++++++++ README.md | 193 +++++++++------------------------- 2 files changed, 107 insertions(+), 144 deletions(-) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..fd2802a --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,58 @@ +name: Release + +on: + push: + tags: ['v*'] + +permissions: + contents: write + +jobs: + build: + runs-on: ubuntu-latest + strategy: + matrix: + include: + - goos: linux + goarch: amd64 + - goos: linux + goarch: arm64 + - goos: darwin + goarch: amd64 + - goos: darwin + goarch: arm64 + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # VERSION is derived from `git describe --tags` + - uses: actions/setup-go@v5 + with: + go-version-file: go.mod + - run: make build GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} + - name: Package + run: | + cd bin + asset="skm-${{ matrix.goos }}-${{ matrix.goarch }}" + archive="skm-${GITHUB_REF_NAME}-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz" + tar czf "../${archive}" "${asset}" + - uses: actions/upload-artifact@v4 + with: + name: skm-${{ matrix.goos }}-${{ matrix.goarch }} + path: '*.tar.gz' + + release: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/download-artifact@v4 + with: + path: dist + merge-multiple: true + - name: Checksums + working-directory: dist + run: sha256sum *.tar.gz > checksums.txt + - uses: softprops/action-gh-release@v2 + with: + draft: true + generate_release_notes: true + files: dist/* diff --git a/README.md b/README.md index 43dd297..48718bd 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ English | [简体中文](README.zh-CN.md) [![CI](https://github.com/alswl/skm/actions/workflows/ci.yml/badge.svg)](https://github.com/alswl/skm/actions/workflows/ci.yml) [![Go](https://img.shields.io/badge/go-1.26%2B-00ADD8?logo=go&logoColor=white)](go.mod) +[![Release](https://img.shields.io/github/v/release/alswl/skm?include_prereleases&sort=semver)](https://github.com/alswl/skm/releases) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) Claude Code has `~/.claude/skills`. Codex has `~/.codex/skills`. Pi has its own. Every new agent @@ -34,135 +35,18 @@ later. Browse it in a TUI, or script it in CI. One column per tool. A `✓` means installed there. That's the whole idea. -## What you get - -- **Write once, install everywhere.** `skm install code-review` puts it in every tool that accepts - skills. No more three copies drifting apart. -- **Your skills become a git repo.** Plain directories and markdown — commit, branch, review, share - with your team like any other code. -- **Always know where things stand.** The install columns and `skm status` tell you what's installed - where, what's dangling, what drifted. -- **Safe by default.** `--dry-run` shows the plan before touching anything, destructive actions - require `--force`, and `uninstall` only removes what skm installed — files you wrote by hand are - never touched. -- **New tool tomorrow? Add it in one command.** Tools are configuration, not code. `skm target add` - teaches skm a new agent; no waiting for a release. -- **Explore in the TUI, automate with the CLI.** Both do the same things, so today's experiment is - tomorrow's script. Every command speaks `--json`. -- **Move machines in two commands.** `skm export` on the old one, `skm deploy` on the new one. - -## Install +## 🏁 Quick start Requires Go 1.26+ and `git` on your `PATH`. ```bash -git clone git@github.com:alswl/skm.git -cd skm -make build # -> ./bin/skm -make install # optional: copy onto your PATH -``` - -## Quick start - -```bash -# 1. Create a skills repository — plain directories, git-friendly. -skm init ~/skills -cd ~/skills - -# 2. Bring assets in, from a local path or a git remote. -skm import ./my-skill --kind skill -skm import git@github.com:org/skills.git - -# 3. Install into every tool that accepts this kind — or pick targets. -skm install code-review -skm install code-review --target codex - -# 4. See where things stand. -skm list -skm status code-review - -# 5. Later: refresh everything that came from somewhere. -skm batch-update +git clone git@github.com:alswl/skm.git && cd skm && make build && make install +skm init ~/skills && cd ~/skills ``` -Then `git init && git commit` the repository and you're done — your skills are now versioned, -portable, and installed in every tool at once. - -Run `skm` with no subcommand to do all of it interactively. - -## Everyday workflows - -### Try before you commit - -Any write operation accepts `--dry-run`, which reports what *would* happen and changes nothing. - -```bash -skm install code-review --dry-run -skm batch-update --dry-run -``` - -### Collect the skills already scattered across your tools - -You almost certainly have skills sitting in `~/.claude/skills` or `~/.codex/skills` that skm doesn't -manage yet. Find them, then take them over — or clean them out. - -```bash -skm discover # what's out there but unmanaged? -skm adopt ~/.codex/skills/review # move it into the repo, replace it with a managed install -skm delete-external ~/.codex/skills/obsolete --force -``` - -### Share a team repository - -Point your team at one git repo and let everyone install from it. - -```bash -skm import git@github.com:team/skills.git # pull the whole repo in -skm install release-notes --target codex -skm batch-update # later: pull everyone's updates in one go -``` - -### Set up a new machine - -```bash -# On the old machine — prints a ready-to-run command reproducing your installs: -skm export - -# On the new one: -skm deploy --repo git@github.com:team/skills.git --target codex --only review,release -``` - -### Curate the repository - -```bash -skm info code-review # metadata, files, frontmatter -skm archive old-skill --force / skm unarchive old-skill -skm to-command review # a skill and a command are the same content, different layout -skm to-skill review -skm verify # whole-repository consistency check -``` - -### Script it - -Every command takes `--json`, so skm composes with `jq`, Makefiles, and CI: - -```bash -# Everything not yet installed anywhere -skm list --json | jq -r '.entries[] | select(.installed | not) | .name' - -# Install a curated set on a fresh CI runner -for s in code-review changelog; do skm install "$s" --json; done -``` - -Global flags: `--json` (machine-readable stdout), `--dry-run` (plan only), `--force` (authorize -overwrite/delete), `--root` (pick the repository), `--config` (pick the config dir), `--timing` -(timings on stderr only). - -## The TUI - -Run `skm` with no arguments. You get a searchable catalog with one install column per tool, entry -detail, a target editor (`t`), and a task center (`J`) where long-running jobs report progress while -you keep browsing. +Run `skm` with no arguments — that's the primary way to use it. A searchable catalog with one +install column per tool, entry detail, a target editor (`t`), and a task center (`J`) where +long-running jobs report progress while you keep browsing. | Key | Action | |---|---| @@ -177,29 +61,51 @@ The footer always shows what's available *right now* — unavailable actions are one tells you why instead of silently doing nothing. Confirmations spell out the consequence before anything destructive happens. -## Configure your tools - -Targets ship preconfigured for Claude skills, Claude commands, Codex, and pi. Adding another agent -is one command: +Prefer scripting? Every action has a CLI equivalent: ```bash -skm target add --name my-tool --platform mytool --path ~/.mytool/skills \ - --accepts skill --strategy skill=skill-symlink - -skm target list -skm target validate my-tool -skm target update --name my-tool --path ~/.mytool/skills-v2 +skm import ./my-skill --kind skill +skm install code-review --target codex +skm list +skm status code-review ``` -A target is just a path, the kinds it accepts (`skill`, `command`), and an install strategy — -`skill-symlink`, `command-marker`, `command-adapter`, or `plugin:`. Config lives in -`targets.json` under `~/.config/skm` (or `$XDG_CONFIG_HOME/skm`, or `--config`). +Then `git init && git commit` the repository and you're done — your skills are now versioned, +portable, and installed in every tool at once. -## Extend it +## ✨ What you get -Where assets come from (**providers**) and how they get installed (**targets**) are both pluggable -with plain executables — no Go, no rebuilding skm. Built-in providers cover Local, SelfBuild, GitHub, -GitLab, and Skills.sh; drop your own beside them: +- 🔁 **Write once, install everywhere.** `skm install code-review` puts it in every tool that accepts + skills. No more three copies drifting apart. +- 📦 **Your skills become a git repo.** Plain directories and markdown — commit, branch, review, share + with your team like any other code. +- 🔍 **Always know where things stand.** The install columns and `skm status` tell you what's installed + where, what's dangling, what drifted. +- 🔌 **New tool tomorrow? Add it in one command.** Tools are configuration, not code. `skm target add` + teaches skm a new agent; no waiting for a release. + +Providers say where assets come from; targets say where they get installed. Both ship with +built-ins, and both are pluggable with plain executables — no Go, no rebuilding skm. + +| Provider | Brings in | +|---|---| +| Local | A path on disk | +| SelfBuild | A skill/command you author in place | +| GitHub | Any GitHub repo | +| GitLab | Any GitLab repo | +| Skills.sh | The Skills.sh registry | +| *your own* | Anything a plugin executable can fetch | + +| Target | Installs into | +|---|---| +| Claude skills | `~/.claude/skills` | +| Claude commands | `~/.claude/commands` | +| Codex | `~/.codex/skills` | +| pi | `~/.pi/agent/skills` | +| *your own* | Any path, via `skm target add` | + +Custom providers and targets live beside the built-ins as plugins — a plugin that's broken, slow, or +hung is isolated and never takes skm down or blocks the others: ```text ~/.config/skm/plugins/ @@ -207,17 +113,16 @@ GitLab, and Skills.sh; drop your own beside them: └── targets/ # how assets get installed ``` -A plugin that's broken, slow, or hung is isolated — it never takes skm down or blocks other plugins. -`SKM_PLUGINS_DIR` adds more directories. - ```bash +skm target add --name my-tool --platform mytool --path ~/.mytool/skills \ + --accepts skill --strategy skill=skill-symlink skm provider list && skm provider validate skm target plugin list ``` Protocol, error codes, and working templates: [docs/plugins/README.md](docs/plugins/README.md). -## Docs & development +## 📚 Docs & development Full command reference: [docs/cli](docs/cli/) — or `skm --help` for anything. From f686c519e01e01ef9346860191233ce926b8b312 Mon Sep 17 00:00:00 2001 From: Jingchao Date: Wed, 12 Aug 2026 09:21:11 +0800 Subject: [PATCH 2/2] docs: recommend discover+adopt for quick start, sync zh-CN README Quick start now points new repos at `skm discover`/`skm adopt` (TUI: o then enter) instead of starting from scratch. README.zh-CN.md is retranslated to match the current English README structure. --- README.md | 10 +++ README.zh-CN.md | 183 ++++++++++++++---------------------------------- 2 files changed, 61 insertions(+), 132 deletions(-) diff --git a/README.md b/README.md index 48718bd..5c1bbbf 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,16 @@ git clone git@github.com:alswl/skm.git && cd skm && make build && make install skm init ~/skills && cd ~/skills ``` +Don't start from a blank repo — you almost certainly have skills already sitting in +`~/.claude/skills`, `~/.codex/skills`, and the like. Discover them and adopt the ones you want: + +```bash +skm discover # what's out there but unmanaged? +skm adopt ~/.codex/skills/review # pull it into the repo, replace it with a managed install +``` + +In the TUI that's `o` to discover, then `enter` to adopt. + Run `skm` with no arguments — that's the primary way to use it. A searchable catalog with one install column per tool, entry detail, a target editor (`t`), and a task center (`J`) where long-running jobs report progress while you keep browsing. diff --git a/README.zh-CN.md b/README.zh-CN.md index 7050862..29ecba5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,6 +6,7 @@ [![CI](https://github.com/alswl/skm/actions/workflows/ci.yml/badge.svg)](https://github.com/alswl/skm/actions/workflows/ci.yml) [![Go](https://img.shields.io/badge/go-1.26%2B-00ADD8?logo=go&logoColor=white)](go.mod) +[![Release](https://img.shields.io/github/v/release/alswl/skm?include_prereleases&sort=semver)](https://github.com/alswl/skm/releases) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) Claude Code 有 `~/.claude/skills`，Codex 有 `~/.codex/skills`，Pi 又是自己的一套。每接入一个新的 @@ -34,130 +35,28 @@ AI 编程工具,就多一个技能目录，你精心写好的技能最后被复 每个工具一列，`✓` 表示已在该工具中安装。核心思路就这么简单。 -## 你能得到什么 - -- **写一次，处处安装。** `skm install code-review` 会装进所有接受该类型的工具，不用再维护三份互相 - 不同步的拷贝。 -- **技能变成一个 git 仓库。** 纯目录加 Markdown——像管理代码一样提交、分支、评审、和团队共享。 -- **随时知道现状。** 安装状态列和 `skm status` 会告诉你哪里已装、哪里失效、哪里和源头不一致了。 -- **默认安全。** `--dry-run` 会在动手前先展示计划；破坏性操作需要显式加 `--force`；`uninstall` - 只会移除 skm 自己装的东西——你手写的文件永远不会被碰。 -- **明天来个新工具？一条命令搞定。** 工具是配置，不是代码。`skm target add` 就能让 skm 认识一个 - 新的 agent，不用等版本发布。 -- **TUI 里探索，CLI 里自动化。** 两者做的是同一件事，今天的手动尝试就是明天的脚本。所有命令都支持 - `--json`。 -- **换机器只要两条命令。** 旧机器上 `skm export`，新机器上 `skm deploy`。 - -## 安装 +## 🏁 快速上手 需要 Go 1.26+ 和 `PATH` 里的 `git`。 ```bash -git clone git@github.com:alswl/skm.git -cd skm -make build # -> ./bin/skm -make install # 可选：拷贝到 PATH 里 +git clone git@github.com:alswl/skm.git && cd skm && make build && make install +skm init ~/skills && cd ~/skills ``` -## 快速上手 - -```bash -# 1. 创建一个技能仓库——纯目录，对 git 友好。 -skm init ~/skills -cd ~/skills - -# 2. 把资产导入进来，可以来自本地路径，也可以来自 git 地址。 -skm import ./my-skill --kind skill -skm import git@github.com:org/skills.git - -# 3. 装进所有接受这个类型的工具——或者指定目标。 -skm install code-review -skm install code-review --target codex - -# 4. 查看现状。 -skm list -skm status code-review - -# 5. 之后：把所有有来源记录的资产统一刷新一遍。 -skm batch-update -``` - -然后对这个仓库执行 `git init && git commit`，大功告成——你的技能现在被版本化、可迁移，并且已经装 -进了每一个工具。 - -不带任何子命令运行 `skm`，就能以交互方式完成以上全部操作。 - -## 日常工作流 - -### 先试跑，再落地 - -所有写操作都支持 `--dry-run`，只报告*将要*发生什么，不改动任何东西。 - -```bash -skm install code-review --dry-run -skm batch-update --dry-run -``` - -### 收编散落在各个工具里的技能 - -你的 `~/.claude/skills` 或 `~/.codex/skills` 里大概率已经躺着一些 skm 还没接管的技能。先找出来， -再决定收编还是清理。 +不用从空仓库开始——你的 `~/.claude/skills`、`~/.codex/skills` 之类的地方大概率已经躺着一些技能了。 +先发现它们，再收编你想要的： ```bash skm discover # 有哪些东西存在，但 skm 还没管？ skm adopt ~/.codex/skills/review # 挪进仓库，替换成受管理的安装 -skm delete-external ~/.codex/skills/obsolete --force -``` - -### 共享一个团队仓库 - -让团队都指向同一个 git 仓库，从这里统一安装。 - -```bash -skm import git@github.com:team/skills.git # 把整个仓库拉进来 -skm install release-notes --target codex -skm batch-update # 之后：一条命令拉取团队所有人的更新 -``` - -### 迁移到新机器 - -```bash -# 在旧机器上——打印出一条能重现当前安装状态的命令： -skm export - -# 在新机器上： -skm deploy --repo git@github.com:team/skills.git --target codex --only review,release ``` -### 整理仓库 +在 TUI 里对应的按键是 `o`（发现）再 `enter`（收编）。 -```bash -skm info code-review # 元数据、文件列表、frontmatter -skm archive old-skill --force / skm unarchive old-skill -skm to-command review # skill 和 command 本质是同一份内容，只是布局不同 -skm to-skill review -skm verify # 整个仓库的一致性检查 -``` - -### 脚本化 - -所有命令都支持 `--json`，方便和 `jq`、Makefile、CI 组合使用： - -```bash -# 找出所有还没在任何地方安装的条目 -skm list --json | jq -r '.entries[] | select(.installed | not) | .name' - -# 在全新的 CI runner 上安装一组指定技能 -for s in code-review changelog; do skm install "$s" --json; done -``` - -全局参数：`--json`（输出机器可读的结果）、`--dry-run`（只出计划）、`--force`（授权覆盖/删除）、 -`--root`（指定仓库位置）、`--config`（指定配置目录）、`--timing`（耗时信息只输出到 stderr）。 - -## TUI - -不带参数运行 `skm`。你会看到一个可搜索的目录列表，每个工具一列安装状态，还有条目详情、目标编辑器 -（`t`）、以及后台任务中心（`J`）——长时间运行的任务在这里汇报进度，你可以继续浏览别的内容。 +不带任何参数运行 `skm`——这是主要的使用方式。你会看到一个可搜索的目录列表，每个工具一列安装状态， +还有条目详情、目标编辑器（`t`）、以及后台任务中心（`J`）——长时间运行的任务在这里汇报进度，你可以 +继续浏览别的内容。 | 按键 | 作用 | |---|---| @@ -171,28 +70,49 @@ for s in code-review changelog; do skm install "$s" --json; done 底部状态栏始终显示*此刻*能做什么——不可用的操作会变暗，按下去会告诉你原因，而不是悄无声息地什么 都不做。破坏性操作的确认提示会先说清楚后果。 -## 配置你的工具 - -内置目标已预先配置好 Claude skills、Claude commands、Codex 和 pi。接入另一个 agent 只需一条命令： +想用脚本？每个操作都有对应的 CLI 命令： ```bash -skm target add --name my-tool --platform mytool --path ~/.mytool/skills \ - --accepts skill --strategy skill=skill-symlink - -skm target list -skm target validate my-tool -skm target update --name my-tool --path ~/.mytool/skills-v2 +skm import ./my-skill --kind skill +skm install code-review --target codex +skm list +skm status code-review ``` -一个 target 就是一个路径、它接受的类型（`skill`、`command`）、以及一种安装策略—— -`skill-symlink`、`command-marker`、`command-adapter`，或 `plugin:`。配置存放在 -`~/.config/skm`（或 `$XDG_CONFIG_HOME/skm`，或 `--config` 指定的目录）下的 `targets.json` 里。 +然后对这个仓库执行 `git init && git commit`，大功告成——你的技能现在被版本化、可迁移，并且已经装 +进了每一个工具。 + +## ✨ 你能得到什么 -## 扩展它 +- 🔁 **写一次，处处安装。** `skm install code-review` 会装进所有接受该类型的工具，不用再维护三份 + 互相不同步的拷贝。 +- 📦 **技能变成一个 git 仓库。** 纯目录加 Markdown——像管理代码一样提交、分支、评审、和团队共享。 +- 🔍 **随时知道现状。** 安装状态列和 `skm status` 会告诉你哪里已装、哪里失效、哪里和源头不一致了。 +- 🔌 **明天来个新工具？一条命令搞定。** 工具是配置，不是代码。`skm target add` 就能让 skm 认识一个 + 新的 agent，不用等版本发布。 + +provider 决定资产从哪里来，target 决定它们装到哪里。两者都自带内置实现，也都可以用纯可执行文件 +扩展——不需要 Go，不需要重新编译 skm。 + +| Provider | 带来什么 | +|---|---| +| Local | 本地磁盘上的一个路径 | +| SelfBuild | 你就地编写的一个 skill/command | +| GitHub | 任意 GitHub 仓库 | +| GitLab | 任意 GitLab 仓库 | +| Skills.sh | Skills.sh 注册表 | +| *自定义* | 任何插件可执行文件能拉取到的东西 | + +| Target | 装到哪里 | +|---|---| +| Claude skills | `~/.claude/skills` | +| Claude commands | `~/.claude/commands` | +| Codex | `~/.codex/skills` | +| pi | `~/.pi/agent/skills` | +| *自定义* | 任意路径，通过 `skm target add` 添加 | -资产从哪里来（**provider**）、怎么安装（**target**）都可以用纯可执行文件扩展——不需要 Go，不需要 -重新编译 skm。内置 provider 覆盖 Local、SelfBuild、GitHub、GitLab 和 Skills.sh；把你自己的放在 -旁边即可： +自定义 provider 和 target 以插件形式和内置实现放在一起——一个坏掉、卡住或运行缓慢的插件是被隔离 +的，不会拖垮 skm，也不会阻塞其他插件： ```text ~/.config/skm/plugins/ @@ -200,17 +120,16 @@ skm target update --name my-tool --path ~/.mytool/skills-v2 └── targets/ # 怎么安装资产 ``` -一个坏掉、卡住或运行缓慢的插件是被隔离的——它不会拖垮 skm，也不会阻塞其他插件。用 -`SKM_PLUGINS_DIR` 可以添加更多目录。 - ```bash +skm target add --name my-tool --platform mytool --path ~/.mytool/skills \ + --accepts skill --strategy skill=skill-symlink skm provider list && skm provider validate skm target plugin list ``` 协议细节、错误码和可用的模板：[docs/plugins/README.md](docs/plugins/README.md)。 -## 文档与开发 +## 📚 文档与开发 完整命令参考：[docs/cli](docs/cli/)——或者对任何命令执行 `skm --help`。 @@ -218,6 +137,6 @@ skm target plugin list make build && make test && make lint ``` -## 许可证 +## License MIT © Jingchao —— 详见 [LICENSE](LICENSE)。