laily/.pouch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add skiff

Browse Source
This commit is contained in:
laily
2026-07-04 10:50:03 +08:00
parent 8b5ac01a9d
commit c2acbc3809
16 changed files with 1501 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+97 -73
View File
@@ -1,20 +1,23 @@
# Agent Skills 仓库
自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容与本仓库内的 **skiff** CLI 一并维护。
自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容在本仓库维护；安装与管理由 [skiff](https://git.yumee.top/laily/skiff) CLI 负责。
| 仓库 | 地址 | 职责 |
| --------------- | ------------------------------------------------------------------------ | --------------- |
| **skills**（本仓库） | [https://git.yumee.top/laily/skills](https://git.yumee.top/laily/skills) | skill 内容与规范 |
| **skiff** | [https://git.yumee.top/laily/skiff](https://git.yumee.top/laily/skiff) | 安装、symlink、健康检查 |
| 组件 | 路径 | 职责 |
|------|------|------|
| **skills/** | 本仓库 | skill 内容与规范 |
| **skiff/** | 本仓库 | 安装、symlink、健康检查（Python 3，无编译） |
---
## 快速开始
```bash
# 1. 克隆并安装 CLI
# 1. 克隆并关联
git clone https://git.yumee.top/laily/skills.git ~/code/gitea/skills
cd ~/code/gitea/skills && ./install.sh
git clone https://git.yumee.top/laily/skiff.git ~/code/gitea/skiff
cd ~/code/gitea/skiff && ./install.sh
skiff setup ~/code/gitea/skills
# 2. 全局安装 skill
@@ -38,15 +41,12 @@ skills/
├── discussion-notes/ # 讨论沉淀笔记
│ ├── SKILL.md
│ └── reference.md
skiff/ # CLI 源码（python3 -m skiff）
bin/skiff # CLI 入口脚本
install.sh # 安装到 ~/.local/bin
registry.yaml # 外部 Git skill 来源目录
AGENTS.md # 本文档
```
**本仓库包含**：`skills/`、`skiff/`、`registry.yaml`、`AGENTS.md`
**本仓库不包含**：各项目的 skill 启用清单（`.skills.yaml`）
**本仓库包含**：`skills/`、`registry.yaml`、`AGENTS.md`
**本仓库不包含**：CLI 代码、各项目的 skill 启用清单
---
@@ -54,10 +54,12 @@ AGENTS.md # 本文档
### 自研（Owned）
| Skill | 说明 |
|-------|------|
| Skill | 说明 |
| ---------------------------------------------------------------------- | ------------------------------------------------- |
| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过 |
| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md |
| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md |
新建 skill：复制 `skills/_template/` → `skills/<name>/`，编辑 `SKILL.md`，在本仓库 commit。
@@ -65,9 +67,11 @@ AGENTS.md # 本文档
在 `registry.yaml` 中注册，通过 skiff 拉取安装：
| Skill | 来源 |
|-------|------|
| superpowers | https://github.com/obra/superpowers |
| Skill | 来源 |
| ----------- | -------------------------------------------------------------------------- |
| superpowers | [https://github.com/obra/superpowers](https://github.com/obra/superpowers) |
```bash
skiff fetch superpowers
@@ -90,17 +94,16 @@ npx skills find typescript
1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`，不在 Agent 目录直接创建
2. **项目自治** — 每个项目自己维护 `.skills.yaml`，本仓库不维护项目清单
3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
4. **一体维护** — skill 内容与 skiff CLI 同仓库，Python 3 直接运行，无需编译
4. **仓库分离** — skill 内容与 CLI 工具分仓库，互不影响更新
---
## 架构
```
skills 仓库（本仓库）
skills 仓库（本仓库） skiff CLI
skills/<name>/ ←── skiff install / enable
registry.yaml ←── skiff add / fetch
skiff/ ←── python3 -m skiff
↑
~/.skills（symlink）
│
@@ -113,19 +116,23 @@ skiff/ ←── python3 -m skiff
### Skill 三层分类
| 层级 | 位置 | 维护方式 |
|------|------|---------|
| **Owned** | `skills/<name>/` | 本仓库 commit |
| **External Git** | `~/.local/share/skills/externals/` | `skiff fetch` |
| **External NPM** | `node_modules/` | `npx skills add` / `skills-npm` |
| 层级 | 位置 | 维护方式 |
| ---------------- | ---------------------------------- | ------------------------------- |
| **Owned** | `skills/<name>/` | 本仓库 commit |
| **External Git** | `~/.local/share/skills/externals/` | `skiff fetch` |
| **External NPM** | `node_modules/` | `npx skills add` / `skills-npm` |
### 多 Agent 路径
| Agent | 全局 | 项目 |
|-------|------|------|
| Cursor | `~/.cursor/skills/` | `.agents/skills/` |
| Agent | 全局 | 项目 |
| ----------- | ------------------- | ----------------- |
| Cursor | `~/.cursor/skills/` | `.agents/skills/` |
| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
| Codex | `~/.codex/skills/` | `.agents/skills/` |
| Codex | `~/.codex/skills/` | `.agents/skills/` |
---
@@ -147,14 +154,16 @@ targets: # 可选，默认 all
- codex
```
| 概念 | 类比 |
|------|------|
| skills 仓库 | npm registry |
| `.skills.yaml` | `package.json` dependencies |
| `skiff enable` | `npm install` |
| `skiff sync` | `npm ci` |
项目级命令：
| 概念 | 类比 |
| -------------- | --------------------------- |
| skills 仓库 | npm registry |
| `.skills.yaml` | `package.json` dependencies |
| `skiff enable` | `npm install` |
| `skiff sync` | `npm ci` |
项目级命令（skiff 待实现）：
```bash
cd ~/code/my-app
@@ -167,24 +176,31 @@ skiff sync
## skiff 命令
CLI 源码在 `skiff/`，安装：`./install.sh`（软链到 `~/.local/bin/skiff`）。
详见 [skiff README](https://git.yumee.top/laily/skiff)。
### 命令一览
### 已实现
| 命令 | 说明 |
|------|------|
| `skiff setup <path>` | 关联 `~/.skills` 到本仓库 |
| `skiff list` | 列出所有 skill |
| `skiff status` | 安装状态总览 |
| `skiff install <name>` | 全局安装（symlink） |
| `skiff uninstall <name>` | 移除 symlink |
| `skiff add / fetch / install-external` | 外部 Git skill |
| `skiff enable / disable` | 项目级启用/关闭 |
| `skiff sync` | 按 `.skills.yaml` 重建 symlink |
| `skiff create <name>` | 从 `_template/` 脚手架创建 skill |
| `skiff doctor` | symlink 健康检查（`--fix` 自动修复） |
`--target` 可选 `cursor`、`claude`、`codex`、`all`（默认 all）。
| 命令 | 说明 |
| -------------------------------------- | ------------------- |
| `skiff setup <path>` | 关联 `~/.skills` 到本仓库 |
| `skiff list` | 列出所有 skill |
| `skiff status` | 安装状态总览 |
| `skiff install <name>` | 全局安装（symlink） |
| `skiff uninstall <name>` | 移除 symlink |
| `skiff add / fetch / install-external` | 外部 Git skill |
### 待实现
| 命令 | 说明 |
| ------------------------ | --------------------------- |
| `skiff enable / disable` | 项目级启用/关闭 |
| `skiff sync` | 按 `.skills.yaml` 重建 symlink |
| `skiff create` | 从 `_template/` 脚手架创建 skill |
| `skiff doctor` | symlink 健康检查 |
---
@@ -222,7 +238,7 @@ description: >-
2. 编辑 `skills/my-skill/SKILL.md`
3. `skiff install my-skill --target cursor` 验证
4. 在本仓库 commit
5. 各项目 `skiff enable my-skill`
5. 各项目 `skiff enable my-skill`（待实现）
**禁止**在 `~/.cursor/skills/` 或项目 Agent 目录直接创建非 symlink 的 skill。
@@ -244,42 +260,50 @@ project/.agents/skills/foo/SKILL.md
Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入时将 symlink 替换成普通文件。
| 场景 | 建议 |
|------|------|
| Cursor / Codex | symlink，正常 |
| Claude Code | symlink 单个 skill 目录，不要 symlink 整个 `~/.claude/skills/` |
| symlink 被替换 | `skiff doctor --fix` → 重建 symlink |
| 场景 | 建议 |
| -------------- | ----------------------------------------------------- |
| Cursor / Codex | symlink，正常 |
| Claude Code | symlink 单个 skill 目录，不要 symlink 整个 `~/.claude/skills/` |
| symlink 被替换 | `skiff doctor`（待实现）→ 重建 symlink |
---
## 工具分工
| 场景 | 工具 |
|------|------|
| 自研 skill 安装/管理 | **skiff** |
| 社区 skill 安装 | **Vercel `npx skills add`** |
| NPM 包内 skill | **skills-npm** / **skill-indexer** |
| 搜索发现 | **npx skills find** / [skills.sh](https://skills.sh) |
| 场景 | 工具 |
| -------------- | ---------------------------------------------------- |
| 自研 skill 安装/管理 | **skiff** |
| 社区 skill 安装 | **Vercel `npx skills add`** |
| NPM 包内 skill | **skills-npm** / **skill-indexer** |
| 搜索发现 | **npx skills find** / [skills.sh](https://skills.sh) |
---
## 日常速查
| 我要… | 命令 | 在哪 |
|-------|------|------|
| 首次 setup | `git clone ... && ./install.sh && skiff setup <path>` | 任意 |
| 新建 skill | 复制 `_template/` → 编辑 → commit | 本仓库 |
| 全局启用 | `skiff install <name>` | 任意 |
| 项目启用 | `skiff enable <name>` | 项目目录 |
| 看状态 | `skiff status` | 任意 |
| 装社区 skill | `npx skills add owner/repo -g -y` | 任意 |
| 更新外部 skill | `skiff fetch <name>` | 任意 |
| 我要… | 命令 | 在哪 |
| ---------- | --------------------------------- | ---- |
| 首次 setup | `skiff setup ~/code/gitea/skills` | 任意 |
| 新建 skill | 复制 `_template/` → 编辑 → commit | 本仓库 |
| 全局启用 | `skiff install <name>` | 任意 |
| 项目启用 | `skiff enable <name>` | 项目目录 |
| 看状态 | `skiff status` | 任意 |
| 装社区 skill | `npx skills add owner/repo -g -y` | 任意 |
| 更新外部 skill | `skiff fetch <name>` | 任意 |
---
## 参考
- [Agent Skills 开放标准](https://agentskills.io)
- [skiff CLI](https://git.yumee.top/laily/skiff)
- [Vercel skills CLI](https://github.com/vercel-labs/skills)
- [skills.sh](https://skills.sh)
- [Cursor Skills 文档](https://cursor.com/docs/context/skills)