reskill 0.1.0 → 0.11.0

package/README.md

@@ -1,87 +1,136 @@
+<div align="center">
+
 # reskill
 
-**AI Skills Package Manager** - Git-based skills management for AI agents
+**Git-based Skills Package Manager for AI Agents**
+
+*Declarative skill management like npm/Go modules — install, version, sync, and share AI agent skills*
 
 [![npm version](https://img.shields.io/npm/v/reskill.svg)](https://www.npmjs.com/package/reskill)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 概述
-
-reskill 是一个基于 Git 的 AI Skills 包管理系统，类似 npm/Go modules 的架构，实现 AI Skills 的版本化管理、共享和复用。
+English | [简体中文](./README.zh-CN.md)
 
-## 特性
+</div>
 
-- 🚀 **Git 即 Registry** - 无需额外服务，git 仓库就是 skill 存储源
-- 📦 **声明式配置** - skills.json 清晰表达项目依赖
-- 🔒 **版本锁定** - 支持精确版本、范围版本、latest
-- 🔗 **本地开发** - 支持 link 本地 skill 进行开发调试
-- ⚡ **全局缓存** - 避免重复下载，加速安装
+---
 
-## 安装
+## Quick Start
 
 ```bash
-# 全局安装
-npm install -g reskill
+# 1. Initialize project
+reskill init
 
-# 或使用 npx
-npx reskill <command>
+# 2. Install a skill
+reskill install github:anthropics/skills/frontend-design@latest
+
+# 3. List installed skills
+reskill list
 ```
 
-## 快速开始
+## What is reskill?
 
-```bash
-# 1. 初始化项目
-reskill init
+reskill is a **Git-based package manager** for AI agent skills, similar to npm or Go modules. It provides declarative configuration, version locking, and seamless synchronization for managing skills across projects and teams.
 
-# 2. 安装 skill
-reskill install github:user/my-skill@v1.0.0
+**Supports:** Cursor, Claude Code, Codex, OpenCode, Windsurf, GitHub Copilot, and more.
 
-# 3. 列出已安装的 skills
-reskill list
-```
+## Why reskill?
 
-## 命令
+reskill offers **fine-grained skill management and synchronization**:
 
-### 初始化
+### Local Experience
 
-```bash
-reskill init                    # 创建 skills.json
-reskill init --name my-project  # 指定项目名称
-reskill init --registry gitlab  # 使用 gitlab 作为默认 registry
-```
+- **Declarative config** — `skills.json` clearly expresses project dependencies
+- **Global cache** — Avoid redundant downloads, speed up installation
+- **Local development** — Use `link` to develop and debug skills locally
 
-### 安装
+### Engineering-Grade Management
 
-```bash
-reskill install                          # 安装 skills.json 中的所有 skills
-reskill install <skill>                  # 安装单个 skill
-reskill install github:user/skill@v1.0.0 # 安装指定版本
-reskill install user/skill@latest        # 安装最新版本
-reskill install user/skill@^1.0.0        # 安装 semver 范围
-reskill install --force                  # 强制重新安装
+- **Version locking** — `skills.lock` ensures team consistency
+- **Flexible versioning** — Support exact versions, semver ranges, branches, and commits
+- **Git as Registry** — No additional services needed, any Git repo is a skill source
+
+### Cross-Project Sync
+
+- **Version controlled** — Commit `skills.json` and `skills.lock` to your repo
+- **CI integration** — Run `reskill install` in CI to verify dependencies
+- **Multi-registry** — Support GitHub, GitLab, and private repositories
+
+### Flexible Version Strategy
+
+```json
+{
+  "skills": {
+    "frontend-design": "github:anthropics/skills/frontend-design@latest",
+    "code-review": "github:team/code-review@v2.1.0",
+    "testing": "github:team/testing@^1.0.0"
+  }
+}
 ```
 
-### 管理
+When running `reskill update`:
+- `@latest` skills automatically update to the newest tag
+- `@v2.1.0` stays locked
+- `@^1.0.0` updates to the latest 1.x.x version
+
+## Installation
 
 ```bash
-reskill list                    # 列出已安装 skills
-reskill list --json             # JSON 格式输出
-reskill info <skill>            # 查看 skill 详情
-reskill update                  # 更新所有 skills
-reskill update <skill>          # 更新单个 skill
-reskill outdated                # 检查过期 skills
-reskill uninstall <skill>       # 卸载 skill
+# Global install
+npm install -g reskill
+
+# Or use npx
+npx reskill <command>
 ```
 
-### 开发
+## Usage
+
+### Source Formats
 
 ```bash
-reskill link <path>             # 链接本地 skill（开发用）
-reskill link <path> --name xxx  # 链接并指定名称
-reskill unlink <skill>          # 取消链接
+# GitHub shorthand
+reskill install github:user/skill@v1.0.0
+
+# Full URL
+reskill install https://github.com/user/skill
+
+# GitLab
+reskill install gitlab:group/skill@latest
+
+# Private registry
+reskill install gitlab.company.com:team/skill@v1.0.0
+
+# Default registry (from skills.json)
+reskill install user/skill@v1.0.0
 ```
 
-## 配置文件
+### Version Specification
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| Exact | `@v1.0.0` | Lock to specific tag |
+| Latest | `@latest` | Get the latest tag |
+| Range | `@^2.0.0` | Semver compatible (>=2.0.0 <3.0.0) |
+| Branch | `@branch:develop` | Specific branch |
+| Commit | `@commit:abc1234` | Specific commit hash |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `reskill init` | Initialize `skills.json` in current directory |
+| `reskill install [skill]` | Install skills from `skills.json` or a specific skill |
+| `reskill list` | List installed skills |
+| `reskill info <skill>` | Show skill details |
+| `reskill update [skill]` | Update all or specific skill |
+| `reskill outdated` | Check for outdated skills |
+| `reskill uninstall <skill>` | Remove a skill |
+| `reskill link <path>` | Link local skill for development |
+| `reskill unlink <skill>` | Unlink a local skill |
+
+Run `reskill <command> --help` for detailed options.
+
+## Configuration
 
 ### skills.json
 
@@ -102,56 +151,33 @@ reskill unlink <skill>          # 取消链接
 }
 ```
 
-### 版本规范
+### skills.lock
 
-| 格式 | 示例 | 说明 |
-|-----|------|------|
-| 精确版本 | `@v1.0.0` | 锁定到指定 tag |
-| 最新版本 | `@latest` | 获取最新 tag |
-| 范围版本 | `@^2.0.0` | semver 兼容（>=2.0.0 <3.0.0） |
-| 分支 | `@branch:develop` | 指定分支 |
-| Commit | `@commit:abc1234` | 指定 commit hash |
+The lock file records exact versions and commit hashes to ensure reproducible installations across your team.
 
-### 仓库引用格式
+## Multi-Agent Support
 
-```
-完整格式: <registry>:<owner>/<repo>@<version>
-简写格式: <owner>/<repo>@<version>  (使用默认 registry)
-
-示例:
-  github:user/skill@v1.0.0
-  gitlab:group/skill@latest
-  gitlab.company.com:team/skill@v1.0.0
-  user/skill@v1.0.0  → 使用 defaults.registry
-```
+reskill works with all major AI coding agents. Skills are installed to the `.skills/` directory by default and can be integrated with any agent.
 
-## 目录结构
+| Agent | Integration Path |
+|-------|------------------|
+| Cursor | `.cursor/rules/` or `.cursor/skills/` |
+| Claude Code | `.claude/skills/` |
+| Codex | `.codex/skills/` |
+| OpenCode | `.opencode/skills/` |
+| Windsurf | `.windsurf/skills/` |
+| GitHub Copilot | `.github/skills/` |
 
-安装后的项目结构：
+## Skill Repository Structure
 
-```
-my-project/
-├── skills.json          # 依赖声明
-├── skills.lock          # 版本锁定
-└── .skills/             # 安装目录
-    ├── planning/
-    │   ├── skill.json
-    │   └── SKILL.md
-    └── code-review/
-        ├── skill.json
-        └── SKILL.md
-```
-
-## Skill 仓库结构
-
-每个 Skill 仓库应遵循以下结构：
+Each skill repository should follow this structure:
 
 ```
 my-skill/
-├── skill.json           # 元数据（必需）
-├── SKILL.md             # 主入口文档（必需）
-├── README.md            # 仓库说明
-└── templates/           # 模板文件（可选）
+├── skill.json           # Metadata (required)
+├── SKILL.md             # Main entry document (required)
+├── README.md            # Repository description
+└── templates/           # Template files (optional)
 ```
 
 ### skill.json
@@ -168,32 +194,63 @@ my-skill/
 }
 ```
 
-## 环境变量
+## Project Structure
+
+After installation:
+
+```
+my-project/
+├── skills.json          # Dependency declaration
+├── skills.lock          # Version lock file
+└── .skills/             # Installation directory
+    ├── planning/
+    │   ├── skill.json
+    │   └── SKILL.md
+    └── code-review/
+        ├── skill.json
+        └── SKILL.md
+```
+
+## Environment Variables
 
-| 变量 | 说明 | 默认值 |
-|-----|------|-------|
-| `SKPM_CACHE_DIR` | 全局缓存目录 | `~/.reskill-cache` |
-| `DEBUG` | 启用调试日志 | - |
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SKPM_CACHE_DIR` | Global cache directory | `~/.reskill-cache` |
+| `DEBUG` | Enable debug logging | - |
 
-## 开发
+## Development
 
 ```bash
-# 安装依赖
+# Install dependencies
 pnpm install
 
-# 开发模式
+# Development mode
 pnpm dev
 
-# 构建
+# Build
 pnpm build
 
-# 运行测试
+# Run tests
 pnpm test
 
-# 类型检查
+# Type check
 pnpm typecheck
 ```
 
+## Acknowledgements
+
+reskill was inspired by and references the implementations of these excellent projects:
+
+- [add-skill](https://github.com/vercel-labs/add-skill) by Vercel Labs
+- [skild](https://github.com/Peiiii/skild) by Peiiii
+- [openskills](https://github.com/numman-ali/openskills) by Numman Ali
+
+Thanks to these projects for pioneering the AI agent skills ecosystem!
+
+## Related Links
+
+- [Agent Skills Specification](https://agentskills.io)
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -0,0 +1,257 @@
+<div align="center">
+
+# reskill
+
+**基于 Git 的 AI Agent Skills 包管理器**
+
+*类似 npm/Go modules 的声明式 skill 管理 — 安装、版本控制、同步和共享 AI agent skills*
+
+[![npm version](https://img.shields.io/npm/v/reskill.svg)](https://www.npmjs.com/package/reskill)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English](./README.md) | 简体中文
+
+</div>
+
+---
+
+## 快速开始
+
+```bash
+# 1. 初始化项目
+reskill init
+
+# 2. 安装 skill
+reskill install github:anthropics/skills/frontend-design@latest
+
+# 3. 列出已安装的 skills
+reskill list
+```
+
+## 什么是 reskill？
+
+reskill 是一个**基于 Git 的包管理器**，用于管理 AI agent skills，类似 npm 或 Go modules。它提供声明式配置、版本锁定和无缝同步，帮助你在项目和团队间管理 skills。
+
+**支持：** Cursor、Claude Code、Codex、OpenCode、Windsurf、GitHub Copilot 等。
+
+## 为什么选择 reskill？
+
+reskill 提供**精细化的 skill 管理和同步方案**：
+
+### 本地体验优化
+
+- **声明式配置** — `skills.json` 清晰表达项目依赖
+- **全局缓存** — 避免重复下载，加速安装
+- **本地开发** — 使用 `link` 链接本地 skill 进行开发调试
+
+### 工程化项目管理
+
+- **版本锁定** — `skills.lock` 确保团队一致性
+- **灵活版本** — 支持精确版本、semver 范围、分支和 commit
+- **Git 即 Registry** — 无需额外服务，任何 Git 仓库都可作为 skill 源
+
+### 跨项目同步
+
+- **版本控制** — 将 `skills.json` 和 `skills.lock` 提交到仓库
+- **CI 集成** — 在 CI 中运行 `reskill install` 验证依赖
+- **多 Registry** — 支持 GitHub、GitLab 和私有仓库
+
+### 灵活的版本策略
+
+```json
+{
+  "skills": {
+    "frontend-design": "github:anthropics/skills/frontend-design@latest",
+    "code-review": "github:team/code-review@v2.1.0",
+    "testing": "github:team/testing@^1.0.0"
+  }
+}
+```
+
+运行 `reskill update` 时：
+
+- `@latest` 的 skill 会自动更新到最新 tag
+- `@v2.1.0` 保持不变
+- `@^1.0.0` 会更新到 1.x.x 的最新版本
+
+## 安装
+
+```bash
+# 全局安装
+npm install -g reskill
+
+# 或使用 npx
+npx reskill <command>
+```
+
+## 使用方式
+
+### 源格式
+
+```bash
+# GitHub 简写
+reskill install github:user/skill@v1.0.0
+
+# 完整 URL
+reskill install https://github.com/user/skill
+
+# GitLab
+reskill install gitlab:group/skill@latest
+
+# 私有 Registry
+reskill install gitlab.company.com:team/skill@v1.0.0
+
+# 默认 Registry（来自 skills.json）
+reskill install user/skill@v1.0.0
+```
+
+### 版本规范
+
+| 格式 | 示例 | 说明 |
+|------|------|------|
+| 精确版本 | `@v1.0.0` | 锁定到指定 tag |
+| 最新版本 | `@latest` | 获取最新 tag |
+| 范围版本 | `@^2.0.0` | semver 兼容（>=2.0.0 <3.0.0） |
+| 分支 | `@branch:develop` | 指定分支 |
+| Commit | `@commit:abc1234` | 指定 commit hash |
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `reskill init` | 在当前目录初始化 `skills.json` |
+| `reskill install [skill]` | 安装 `skills.json` 中的所有 skills 或指定 skill |
+| `reskill list` | 列出已安装的 skills |
+| `reskill info <skill>` | 查看 skill 详情 |
+| `reskill update [skill]` | 更新所有或指定 skill |
+| `reskill outdated` | 检查过期的 skills |
+| `reskill uninstall <skill>` | 卸载 skill |
+| `reskill link <path>` | 链接本地 skill（开发用） |
+| `reskill unlink <skill>` | 取消链接本地 skill |
+
+运行 `reskill <command> --help` 查看详细选项。
+
+## 配置
+
+### skills.json
+
+```json
+{
+  "name": "my-project",
+  "skills": {
+    "planning": "github:user/planning-skill@v1.0.0",
+    "code-review": "gitlab:team/code-review@latest"
+  },
+  "defaults": {
+    "registry": "github",
+    "installDir": ".skills"
+  },
+  "registries": {
+    "internal": "https://gitlab.company.com"
+  }
+}
+```
+
+### skills.lock
+
+锁定文件记录精确版本和 commit hash，确保团队间可复现的安装结果。
+
+## 多 Agent 支持
+
+reskill 支持所有主流 AI 编程 Agent。Skills 默认安装到 `.skills/` 目录，可与任何 Agent 集成。
+
+| Agent | 集成路径 |
+|-------|----------|
+| Cursor | `.cursor/rules/` 或 `.cursor/skills/` |
+| Claude Code | `.claude/skills/` |
+| Codex | `.codex/skills/` |
+| OpenCode | `.opencode/skills/` |
+| Windsurf | `.windsurf/skills/` |
+| GitHub Copilot | `.github/skills/` |
+
+## Skill 仓库结构
+
+每个 Skill 仓库应遵循以下结构：
+
+```
+my-skill/
+├── skill.json           # 元数据（必需）
+├── SKILL.md             # 主入口文档（必需）
+├── README.md            # 仓库说明
+└── templates/           # 模板文件（可选）
+```
+
+### skill.json
+
+```json
+{
+  "name": "my-skill",
+  "version": "1.0.0",
+  "description": "A skill for ...",
+  "author": "Your Name",
+  "license": "MIT",
+  "entry": "SKILL.md",
+  "keywords": ["ai", "skill"]
+}
+```
+
+## 项目结构
+
+安装后的目录结构：
+
+```
+my-project/
+├── skills.json          # 依赖声明
+├── skills.lock          # 版本锁定文件
+└── .skills/             # 安装目录
+    ├── planning/
+    │   ├── skill.json
+    │   └── SKILL.md
+    └── code-review/
+        ├── skill.json
+        └── SKILL.md
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `SKPM_CACHE_DIR` | 全局缓存目录 | `~/.reskill-cache` |
+| `DEBUG` | 启用调试日志 | - |
+
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 开发模式
+pnpm dev
+
+# 构建
+pnpm build
+
+# 运行测试
+pnpm test
+
+# 类型检查
+pnpm typecheck
+```
+
+## 致谢
+
+reskill 的实现参考了以下优秀项目：
+
+- [add-skill](https://github.com/vercel-labs/add-skill) by Vercel Labs
+- [skild](https://github.com/Peiiii/skild) by Peiiii
+- [openskills](https://github.com/numman-ali/openskills) by Numman Ali
+
+感谢这些项目为 AI agent skills 生态系统做出的开创性贡献！
+
+## 相关链接
+
+- [Agent Skills 规范](https://agentskills.io)
+
+## 许可证
+
+MIT

package/dist/cli/commands/install.d.ts

@@ -2,9 +2,17 @@ import { Command } from 'commander';
 /**
  * install 命令 - 安装 skill
  *
- * 支持两种安装模式:
- * - 项目安装 (默认): 安装到 .skills/ 目录，更新 skills.json 和 skills.lock
- * - 全局安装 (-g): 安装到 ~/.claude/skills/，不更新配置文件
+ * 支持多种安装模式:
+ * - 项目安装 (默认): 安装到项目目录
+ * - 全局安装 (-g): 安装到用户目录
+ * - 多 Agent 安装 (-a): 安装到指定 agents
+ *
+ * 交互式流程:
+ * 1. 检测已安装的 agents
+ * 2. 选择目标 agents（多选）
+ * 3. 选择安装范围 (项目/全局)
+ * 4. 选择安装方式 (symlink/copy)
+ * 5. 确认并执行
  */
 export declare const installCommand: Command;
 export default installCommand;

package/dist/cli/commands/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,SAoEvB,CAAC;AAEL,eAAe,cAAc,CAAC"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0BpC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,SAiavB,CAAC;AAEL,eAAe,cAAc,CAAC"}