diff --git a/AGENTS.md b/AGENTS.md index 4886df9..b697579 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,21 +1,20 @@ # Agent Skills 仓库 -自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容在本仓库维护；安装与管理由 [skiff](https://git.yumee.top/laily/skiff) CLI 负责。 +自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容与本仓库内的 **skiff** CLI 一并维护。 -| 仓库 | 地址 | 职责 | +| 组件 | 路径 | 职责 | |------|------|------| -| **skills**（本仓库） | https://git.yumee.top/laily/skills | skill 内容与规范 | -| **skiff** | https://git.yumee.top/laily/skiff | 安装、symlink、健康检查 | +| **skills/** | 本仓库 | skill 内容与规范 | +| **skiff/** | 本仓库 | 安装、symlink、健康检查（Python 3，无编译） | --- ## 快速开始 ```bash -# 1. 克隆并关联 +# 1. 克隆并安装 CLI git clone https://git.yumee.top/laily/skills.git ~/code/gitea/skills -git clone https://git.yumee.top/laily/skiff.git ~/code/gitea/skiff -cd ~/code/gitea/skiff && ./install.sh +cd ~/code/gitea/skills && ./install.sh skiff setup ~/code/gitea/skills # 2. 全局安装 skill @@ -36,12 +35,18 @@ skills/ ├── declarative-openspec-loop/ # 自研 skill │ ├── SKILL.md │ └── reference.md +├── 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/`、`registry.yaml`、`AGENTS.md` -**本仓库不包含**：CLI 代码、各项目的 skill 启用清单 +**本仓库包含**：`skills/`、`skiff/`、`registry.yaml`、`AGENTS.md` +**本仓库不包含**：各项目的 skill 启用清单（`.skills.yaml`） --- @@ -52,6 +57,7 @@ AGENTS.md # 本文档 | Skill | 说明 | |-------|------| | [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过 | +| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md | 新建 skill：复制 `skills/_template/` → `skills//`，编辑 `SKILL.md`，在本仓库 commit。 @@ -84,16 +90,17 @@ npx skills find typescript 1. **SSOT** — 自研 skill 只存在于 `skills//`，不在 Agent 目录直接创建 2. **项目自治** — 每个项目自己维护 `.skills.yaml`，本仓库不维护项目清单 3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT -4. **仓库分离** — skill 内容与 CLI 工具分仓库，互不影响更新 +4. **一体维护** — skill 内容与 skiff CLI 同仓库，Python 3 直接运行，无需编译 --- ## 架构 ``` -skills 仓库（本仓库） skiff CLI +skills 仓库（本仓库） skills// ←── skiff install / enable registry.yaml ←── skiff add / fetch +skiff/ ←── python3 -m skiff ↑ ~/.skills（symlink） │ @@ -147,7 +154,7 @@ targets: # 可选，默认 all | `skiff enable` | `npm install` | | `skiff sync` | `npm ci` | -项目级命令（skiff 待实现）： +项目级命令： ```bash cd ~/code/my-app @@ -160,9 +167,9 @@ skiff sync ## skiff 命令 -详见 [skiff README](https://git.yumee.top/laily/skiff)。 +CLI 源码在 `skiff/`，安装：`./install.sh`（软链到 `~/.local/bin/skiff`）。 -### 已实现 +### 命令一览 | 命令 | 说明 | |------|------| @@ -172,15 +179,12 @@ skiff sync | `skiff install ` | 全局安装（symlink） | | `skiff uninstall ` | 移除 symlink | | `skiff add / fetch / install-external` | 外部 Git skill | - -### 待实现 - -| 命令 | 说明 | -|------|------| | `skiff enable / disable` | 项目级启用/关闭 | | `skiff sync` | 按 `.skills.yaml` 重建 symlink | -| `skiff create` | 从 `_template/` 脚手架创建 skill | -| `skiff doctor` | symlink 健康检查 | +| `skiff create ` | 从 `_template/` 脚手架创建 skill | +| `skiff doctor` | symlink 健康检查（`--fix` 自动修复） | + +`--target` 可选 `cursor`、`claude`、`codex`、`all`（默认 all）。 --- @@ -218,7 +222,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,7 +248,7 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入 |------|------| | Cursor / Codex | symlink，正常 | | Claude Code | symlink 单个 skill 目录，不要 symlink 整个 `~/.claude/skills/` | -| symlink 被替换 | `skiff doctor`（待实现）→ 重建 symlink | +| symlink 被替换 | `skiff doctor --fix` → 重建 symlink | --- @@ -263,7 +267,7 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入 | 我要… | 命令 | 在哪 | |-------|------|------| -| 首次 setup | `skiff setup ~/code/gitea/skills` | 任意 | +| 首次 setup | `git clone ... && ./install.sh && skiff setup ` | 任意 | | 新建 skill | 复制 `_template/` → 编辑 → commit | 本仓库 | | 全局启用 | `skiff install ` | 任意 | | 项目启用 | `skiff enable ` | 项目目录 | @@ -276,7 +280,6 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入 ## 参考 - [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) diff --git a/skills/discussion-notes/SKILL.md b/skills/discussion-notes/SKILL.md new file mode 100644 index 0000000..c6a2b16 --- /dev/null +++ b/skills/discussion-notes/SKILL.md @@ -0,0 +1,104 @@ +--- +name: discussion-notes +description: >- + 讨论沉淀模式：协作问答并持续更新 Markdown 笔记。Use when the user invokes + discussion-notes, asks to enter 讨论模式, or wants to 沉淀到文档/整理笔记 during + learning or decision conversations. Triggers on 讨论模式、讨论沉淀、记笔记、单开文档. + No .raw.md—only living curated notes updated each round. +--- + +# Discussion Notes（讨论沉淀） + +与用户讨论的同时，把可复用结论持续写入项目内的 Markdown 笔记。 + +笔记模板与示例见 [reference.md](reference.md)。 + +--- + +## 何时使用 + +- 用户 `@discussion-notes` 或说「进入讨论模式」 +- 用户希望边讨论边沉淀到文档（`沉淀到文档`、`整理笔记`） +- 学习新概念、做技术选型，需要产出可回顾的笔记 +- 用户说「单开文档」记录某个子话题 + +**退出**：用户说「结束讨论」「不用记了」→ 可选写收尾「更新」节，之后不再自动改笔记。 + +--- + +## 步骤 + +### 1. 确认笔记目标 + +| 情况 | 动作 | +|------|------| +| 用户指定路径 | 使用该路径（项目仓库内） | +| 未指定路径 | 默认 `000inbox/.md` | +| 无明确话题 | 询问话题名与路径 | + +**新开话题** → 新建独立 `.md`。**续聊** → 打开已有笔记继续改。 + +### 2. 判断文档类型 + +| 类型 | 何时用 | 结构要点 | +|------|--------|----------| +| 选型 / 决策 | 要不要、选哪个 | 背景、对比、结论、落地清单 | +| 概念 / 原理 | 是什么、怎么工作 | 核心结论、原理、误解、示例 | +| 混合 | 选型 + 深层概念 | 主文档写选型；概念单开并互相链接 | + +### 3. 每轮讨论 + +``` +1. 理解用户问题（结合对话历史） +2. 用简体中文回复 +3. 更新笔记： + - 新结论 → 写入或修订对应章节 + - 纠正旧理解 → 直接改，不保留错误版本 + - 关键约束 → 记入「背景」或结论旁 +4. 只沉淀可复用知识，不抄 Q&A 全文 +``` + +用户说「这轮不用记」→ 只回复，不改文件。 + +### 4. 可选收尾 + +讨论告一段落时，在笔记加： + +```markdown +## 更新 +- 搞懂了：… +- 纠正了：… +- 待动手：… +``` + +--- + +## 注意事项 + +### 必须遵守 + +- **单文件沉淀**：只维护 `xxx.md`，**禁止** `xxx.raw.md` +- **笔记是活的**：理解变了就改笔记 +- **不主动 git commit**：除非用户明确要求 +- 对话与笔记均用**简体中文** + +### 写什么 / 不写什么 + +| 写 | 不写 | +|----|------| +| 结论、理由、对比表、命令示例 | 逐轮 Q&A 全文 | +| 待验证 / 待深入行动项 | 寒暄、重复铺垫 | +| 纠正过的误解 | 无关闲聊 | + +### 反模式 + +- ❌ 创建 `.raw.md` +- ❌ 只聊天不更新已约定的笔记 +- ❌ 每轮末尾追加「第 N 轮 Q&A」 +- ❌ 未经确认把无关话题塞进同一文件 +- ❌ 笔记写成聊天转录 + +### 协作约定 + +- 笔记过长（建议 > 400 行）→ 拆章节或拆文件 +- 项目级默认笔记目录：`000inbox/`（Obsidian 收件箱） diff --git a/skills/discussion-notes/reference.md b/skills/discussion-notes/reference.md new file mode 100644 index 0000000..407916b --- /dev/null +++ b/skills/discussion-notes/reference.md @@ -0,0 +1,127 @@ +# Discussion Notes 参考 + +## Frontmatter + +```yaml +--- +title: {{主题名}} +date: "{{YYYY-MM-DD}}THH:MM:00+08:00" +--- +``` + +新建时写 `date`；大改时追加文内「更新」节即可。 + +--- + +## 笔记结构模板 + +### 选型 / 决策类 + +```markdown +# 标题 + +> 一句话说明文档用途。讨论过程中持续更新。 + +## 背景 +## 结论 +## （各专题章节） +## 落地清单 +## 待验证 +## 待深入 +## 更新（可选） +``` + +### 概念 / 原理类 + +```markdown +# 标题 + +> 与 xxx 选型文档无关（若适用）。 + +## 核心结论 +## 定位（是什么 / 不是什么） +## 工作原理 +## 与相关概念对比 +## 示例 +## 常见误解 +## 待验证 +``` + +--- + +## 示例：选型笔记（节选） + +```markdown +--- +title: Podman vs Docker +date: "2026-07-02T22:50:00+08:00" +--- + +# Podman vs Docker + +> 公司内部基础设施容器运行时选型笔记。讨论过程中持续更新。 + +## 背景 + +- 默认系统：Debian +- 部署：一服务一 VM，VM 内跑容器 + +## 结论 + +推荐 Podman；compose 用 `podman compose`。概念见 [quadlet](quadlet.md)。 + +## 待验证 + +- [ ] Debian VM 上 rootless + compose 冒烟测试 +``` + +--- + +## 示例：概念笔记（节选） + +```markdown +--- +title: Quadlet +date: "2026-07-02T23:30:00+08:00" +--- + +# Quadlet + +> Podman 与 systemd 的集成机制。 + +## 核心结论 + +- Quadlet 不是容器引擎，依赖 Podman +- `.container` 经 systemd generator 编译为 `.service` + +## 常见误解 + +| 误解 | 事实 | +|------|------| +| 不装 Podman 也能跑 | ❌ ExecStart 即 podman run | +``` + +--- + +## 调用方式 + +``` +@discussion-notes 讨论 xxx，记到 000inbox/xxx.md +``` + +--- + +## 工作流示意 + +``` +用户提问 + │ + ▼ +Agent 回复（中文） + │ + ▼ +更新 000inbox/.md + │ + ├─ 延续话题 → 改已有文件 + └─ 新子话题 → 新建 md + 主文档加链接 +```