186 lines
6.4 KiB
Markdown
186 lines
6.4 KiB
Markdown
---
|
||
name: skiff
|
||
description: >-
|
||
创建和维护 ~/.skills 自研 skill：把项目开发中产生的想法提炼为草稿，完善并校验后发布，
|
||
用 skiff add/remove 在项目及全局挂卸 skill，或用 skiff init 初始化 skill 项目状态。
|
||
触发词：skiff、自研 skill、创建 skill、想做一个 skill、publish skill、安装自研 skill、
|
||
更新 skill 到项目、初始化 skill。
|
||
---
|
||
|
||
# skiff 自研 Skill 工作流
|
||
|
||
SSOT 固定在 `~/.skills/skills/<name>/`。内容通过 **symlink** 分发到各 agent，改 SSOT 即全项目生效。
|
||
|
||
---
|
||
|
||
## 在项目中使用 skill
|
||
|
||
先浏览可用的 builtin skill，再安装到当前项目：
|
||
|
||
```bash
|
||
skiff add --list
|
||
skiff add <name> -a cursor -a claude -a codex -y
|
||
```
|
||
|
||
`skiff add <name>` 默认安装到当前项目；只有用户明确需要所有项目使用时才加 `-g`。安装结果是指向 `~/.skills/skills/<name>/` 的软链，不要在 Agent 目录创建副本。
|
||
|
||
## 创建新的 skill
|
||
|
||
### 从项目想法创建 skill
|
||
|
||
当用户在项目开发中提出“想创建一个 skill”时：
|
||
|
||
1. 用一句话确认它要解决的重复问题，并建议符合小写连字符规范的名称；信息足够时不要为了形式追问。
|
||
2. 读取当前项目中与想法直接相关的代码和规范，区分可复用工作流与项目私有事实。
|
||
3. 创建草稿：
|
||
|
||
```bash
|
||
skiff create <name> --idea "<用户原始想法>" --from-project .
|
||
```
|
||
|
||
4. 编辑 `~/.skills/.drafts/<name>/SKILL.md`，完善触发条件、不适用场景、步骤、边界与验证方法。
|
||
5. 编辑同目录的 `README.md`，用面向人类的语言说明用途、准备事项、可直接复制的请求示例、Agent 会做什么以及如何判断完成。README 不应复述 Agent 内部指令。
|
||
6. 仅在确有必要时增加 `references/`、`scripts/` 或 `assets/`。不要把项目专属路径、私有业务规则、一次性命令或密钥复制到通用 skill。
|
||
7. 运行校验并修复所有问题：
|
||
|
||
```bash
|
||
skiff check <name>
|
||
```
|
||
|
||
8. 向用户展示名称、description、README 的人类使用方式、核心步骤和验证方式。获得确认后再转正：
|
||
|
||
```bash
|
||
skiff finalize <name>
|
||
```
|
||
|
||
转正不会自动 commit、push 或安装。用户明确要求后再执行 `skiff publish` 或 `skiff add`。
|
||
|
||
## 问题或优化回流
|
||
|
||
在项目里使用 skills 遇到问题，或者发现可复用的优化时：
|
||
|
||
1. 先记录最小证据：触发用户表达、使用的 skill 名称、实际结果、期望结果，以及能复现问题的必要项目上下文。
|
||
2. 判断归属：
|
||
- 通用工作流、触发条件或验证缺陷：回流 builtin skill。
|
||
- 仅当前项目成立的命令、路径、业务规则：留在项目文档或项目配置，不写回通用 skill。
|
||
- CLI 安装、软链或校验行为异常：修改 `~/.skills/skiff/` 中的 CLI 和测试。
|
||
- 第三方 skill：不要复制成 builtin skill 或直接改安装目录；整理证据反馈上游，除非用户明确决定维护 fork。
|
||
3. 确认真实来源。Agent 目录通常是软链，builtin skill 的 SSOT 固定为：
|
||
|
||
```text
|
||
~/.skills/skills/<name>/
|
||
```
|
||
|
||
4. 修改 SSOT。行为修复应先补能复现问题的测试或示例，再改 `SKILL.md`、引用文件或脚本。
|
||
5. 校验并在原项目重跑最初失败的场景：
|
||
|
||
```bash
|
||
skiff check <name>
|
||
```
|
||
|
||
6. 汇报修改内容、验证结果和影响范围。只有用户明确要求提交或推送时才运行：
|
||
|
||
```bash
|
||
skiff publish skills/<name> -m "update <name>" --push
|
||
```
|
||
|
||
软链正确时无需重新安装；SSOT 保存后项目立即读取新内容。
|
||
|
||
## 安装与维护
|
||
|
||
安装本项目的 `skiff` skill 到所有 Agent：
|
||
|
||
```bash
|
||
skiff bootstrap
|
||
```
|
||
|
||
安装其他 skill：
|
||
|
||
```bash
|
||
# 当前项目
|
||
cd ~/code/my-app
|
||
skiff add discussion-notes -a cursor -y
|
||
|
||
# 全局（所有项目）
|
||
skiff add discussion-notes -a cursor -g -y
|
||
|
||
# 多个 agent
|
||
skiff add discussion-notes -a cursor -a codex -g -y
|
||
```
|
||
|
||
catalog source既可以指向单个 skill，也可以指向包含多个 skill 目录的
|
||
collection。安装 collection 全部内容或其中一个：
|
||
|
||
```bash
|
||
skiff add waza -a codex -g -y
|
||
skiff add waza/think -a codex -g -y
|
||
```
|
||
|
||
`skiff select` 会把 collection 显示为两级菜单：选择 `waza` 仓库会选中其
|
||
全部子 skill，也可以只选择 `waza/think`、`waza/ui` 中的若干项。
|
||
普通 `skiff select` 只向项目安装，并只读显示每个 Agent 的全局安装状态；
|
||
`skiff select -g` 只向全局安装。取消已勾选项不会卸载，卸载继续使用
|
||
`skiff remove`。
|
||
|
||
卸载：
|
||
|
||
```bash
|
||
skiff remove discussion-notes -a cursor -y # 当前项目
|
||
skiff remove discussion-notes -g -a cursor -y # 全局
|
||
skiff rm discussion-notes -g -y # rm 别名
|
||
```
|
||
|
||
浏览可用自研 skill：
|
||
|
||
```bash
|
||
skiff add --list
|
||
```
|
||
|
||
使用 Skill 自带模板初始化项目状态：
|
||
|
||
```bash
|
||
skiff init ack
|
||
skiff init ack --project ~/app
|
||
```
|
||
|
||
`skiff` 只负责可靠地生成项目状态文件，不复制或链接 Skill。需要分析项目并完善
|
||
ACK 配置、检查接入状态或
|
||
运行三角色闭环时，显式调用全局 `/ack` skill。
|
||
|
||
---
|
||
|
||
## 与 Vercel `npx skills` 的分工
|
||
|
||
| 场景 | 工具 |
|
||
|------|------|
|
||
| 自研 skill（~/.skills） | **skiff** |
|
||
| 社区 skill（GitHub 任意仓库） | `npx skills add` |
|
||
|
||
---
|
||
|
||
## 命令对照
|
||
|
||
| skiff | 说明 |
|
||
|-------|------|
|
||
| `bootstrap` | 将本项目的 `skiff` skill 全局安装到所有 Agent |
|
||
| `update` | 在 `~/.skills` 执行 `git pull`，更新 skiff 自身 |
|
||
| `add <name> [-g] [-a AGENT...] [-y]` | 安装 |
|
||
| `remove <name> [-g] [-a AGENT...] [-y]` | 卸载（`rm` / `r` 别名） |
|
||
| `add --list` | 列出可用自研 skill |
|
||
| `publish [paths] -m MSG [--push]` | git add / commit / push |
|
||
| `list` | 列出 ~/.skills 目录结构 |
|
||
| `status` | 查看软链安装状态 |
|
||
| `create <name> --idea TEXT [--from-project PATH]` | 创建自研 skill 草稿 |
|
||
| `check <name>` | 校验草稿或正式 skill |
|
||
| `finalize <name>` | 校验草稿并转为正式 skill |
|
||
| `init <name> [--project DIR]` | 使用 skill 模板初始化项目状态 |
|
||
|
||
---
|
||
|
||
## 注意
|
||
|
||
- 不要在 `project/.agents/skills/` 里直接改文件；应改 `~/.skills/skills/` 再 `publish`
|
||
- 未完成的内容保留在 `~/.skills/.drafts/`，不要直接放进正式 `skills/`
|
||
- symlink 正确时，**不需要 reinstall**；保存 SSOT 后各项目自动读到新内容
|
||
- 社区 skill 用 `npx skills add`，不要用 skiff `catalog add` 除非团队要 pin 版本
|