laily/.pouch

Fork 0

Files

T

laily 7d1994cf93 refactor: unify skill source model

2026-07-30 12:11:25 +08:00

11 KiB

Raw Blame History

Agent Skills 仓库

自研 Agent Skills 与配套规范资料的单一事实来源（SSOT）。Skill 内容、规范包与可运行的 skiff CLI 在本仓库一并维护。

仓库	地址	职责
skills（本仓库）	https://git.yumee.top/laily/skills	skill、规范包、skiff CLI 的当前 SSOT
skiff	https://git.yumee.top/laily/skiff	skiff CLI 的独立来源 / 上游同步参考

快速开始

# 1. 克隆并关联
git clone https://git.yumee.top/laily/skills.git ~/.skills
cd ~/.skills && ./install.sh

# install.sh 会自动把 skiff 项目 skill 安装到所有 Agent
# 2. 安装其他 skill
skiff add declarative-openspec-loop -g

# 3. 查看状态
skiff list
skiff status

仓库结构

skills/
├── _template/                  # 新建 skill 的脚手架
├── ack/                        # 完整 ACK skill，含 references/templates/scripts
├── declarative-openspec-loop/  # 自研 skill，必须含 SKILL.md
│   ├── SKILL.md
│   └── reference.md
├── discussion-notes/           # 讨论沉淀笔记
│   ├── SKILL.md
│   └── reference.md
skiff/                          # CLI 源码（Python 3）
bin/skiff                       # CLI 入口
catalog.yaml                   # skiff 预置 Skill 来源目录
AGENTS.md                       # 本文档

本仓库包含：skills/、skiff/、bin/skiff、catalog.yaml、AGENTS.md 本仓库不包含：各项目的 skill 启用清单

Skill 目录

内置（Builtin）

Skill	说明
ack	ACK 入口：显式初始化、检查并运行项目三角色协作闭环
skiff	本项目工作流：创建、使用、反馈与更新 builtin skill
declarative-openspec-loop	声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过
discussion-notes	讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md

新建 skill：复制 skills/_template/ → skills/<name>/，编辑 SKILL.md，在本仓库 commit。

Skill 需要的稳定规范、模板、示例和脚本直接放在自己的目录中，例如 skills/ack/references/、templates/、examples/ 和 scripts/。项目初始化只生成项目状态，不复制或链接 Skill 内容：

skiff init ack

预置目录（Catalog）

在 catalog.yaml 中预置，通过 skiff 拉取安装：

Source	来源
waza	https://github.com/tw93/Waza

skiff fetch waza
skiff add waza/think -g

自定义仓库（Custom Sources）

公司或团队维护、且一个仓库中包含多个 skill 时，使用命名 custom source：

skiff source add company \
  git@git.company.com:platform/agent-skills.git \
  --skills-path skills
skiff list --source company
skiff add company/internal-review -g

也可以接入已有本地 checkout：

skiff source add company --local ~/code/company-skills --skills-path skills

配置保存在 ~/.config/skiff/config.yaml，Git source 默认 clone 到 ~/.local/share/skiff/sources/<source>/。项目 .skills.yaml 只记录逻辑 source 名称，每台机器独立配置实际仓库地址。

社区（External NPM / GitHub）

推荐使用 Vercel CLI 安装第三方 skill：

npx skills add vercel-labs/agent-skills -g -y
npx skills find typescript

设计原则

SSOT — 自研 skill 只存在于 skills/<name>/，不在 Agent 目录直接创建
项目自治 — 每个项目自己维护 .skills.yaml，本仓库不维护项目清单
软链优先 — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
能力内聚 — Skill 使用的规范、模板和脚本与 SKILL.md 同目录维护
一体维护 — skill 与 CLI 同仓库维护；需要时再与独立 skiff 仓库同步

架构

skills 仓库（本仓库）              skiff CLI
skills/<name>/              ←──   skiff install / enable
skiff/                      ←──   python3 -m skiff
catalog.yaml               ←──   skiff add / fetch
         ↑
    ~/.skills（symlink）
         │
    ┌────┴────┐
    ▼         ▼
~/.cursor/skills/     project/.agents/skills/
~/.claude/skills/     project/.claude/skills/
~/.codex/skills/      project/.skills.yaml

Skill 三层分类

层级	位置	维护方式
Builtin	`skills/<name>/`	本仓库 commit
Catalog	`catalog.yaml` + checkout 缓存	`skiff catalog add / fetch`
Custom Source	`~/.local/share/skiff/sources/` 或本地路径	`skiff source add/fetch`
External NPM	`node_modules/`	`npx skills add` / `skills-npm`

非 Skill 资料分类

类型	位置	维护方式
OpenSpec 配置	`openspec/`	本仓库 commit；服务于本仓库自身的规格流程

多 Agent 路径

Agent	全局	项目
Cursor	`~/.cursor/skills/`	`.agents/skills/`
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex	`~/.codex/skills/`	`.agents/skills/`

项目级启用

每个项目自己维护 .skills.yaml，不由本仓库管理：

# .skills.yaml（在项目根目录）
skills:
  - name: declarative-openspec-loop
    source: builtin
  - name: think
    source: catalog:waza
  - name: internal-review
    source: company

targets:          # 可选，默认 all
  - cursor
  - claude
  - codex

概念	类比
skills 仓库	npm registry
`.skills.yaml`	`package.json` dependencies
`skiff enable`	`npm install`
`skiff sync`	`npm ci`

项目级命令：

cd ~/code/my-app
skiff enable declarative-openspec-loop
skiff disable declarative-openspec-loop
skiff sync

skiff 命令

详见 skiff README。

已实现

命令	说明
`skiff bootstrap`	将 skiff 项目 skill 全局安装到所有 Agent
`skiff list`	列出所有 skill
`skiff status`	安装状态总览
`skiff add <name> [-g]`	项目或全局安装（symlink）
`skiff remove <name> [-g]`	移除 symlink
`skiff catalog add` / `skiff fetch`	管理和拉取 catalog source

草稿与健康检查

命令	说明
`skiff create <name> --idea TEXT [--from-project PATH]`	从 `_template/` 创建草稿
`skiff check <name>`	校验草稿或正式 skill
`skiff finalize <name>`	校验并将草稿转为正式 skill
`skiff doctor [--fix]`	symlink 健康检查与修复

Skill 编写规范

遵循 Agent Skills 开放标准：

skill-name/
├── SKILL.md          # 必需
├── reference.md      # 可选
├── examples.md       # 可选
└── scripts/          # 可选

Frontmatter

---
name: skill-name
description: >-
  做什么、何时触发。description 是 Agent 决定是否加载的唯一依据，务必写清触发关键词。
---

命名

目录名 = frontmatter name
小写 + 连字符：security-review
禁止 camelCase、空格、下划线

新建流程

skiff create my-skill --idea "..." --from-project .
Agent 编辑 ~/.skills/.drafts/my-skill/SKILL.md
skiff check my-skill
用户确认后执行 skiff finalize my-skill
skiff add my-skill -a cursor -g -y 验证
在本仓库 commit；需要的项目再用 skiff add my-skill 启用

禁止在 ~/.cursor/skills/ 或项目 Agent 目录直接创建非 symlink 的 skill。

Skill 修改回流

symlink 正确时，Agent 在项目里改 skill 文件 = 直接改 SSOT：

project/.agents/skills/foo/SKILL.md
  → ~/.skills/skills/foo/SKILL.md
  → 在本仓库 commit

Claude Code 注意事项

Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入时将 symlink 替换成普通文件。

场景	建议
Cursor / Codex	symlink，正常
Claude Code	symlink 单个 skill 目录，不要 symlink 整个 `~/.claude/skills/`
symlink 被替换	`skiff doctor --fix` → 重建 symlink

工具分工

场景	工具
自研 skill 安装/管理	skiff
社区 skill 安装	Vercel `npx skills add`
NPM 包内 skill	skills-npm / skill-indexer
搜索发现	npx skills find / skills.sh

日常速查

我要…	命令	在哪
首次安装	`git clone <repo> ~/.skills && ~/.skills/install.sh`	任意
新建 skill	`skiff create` → Agent 完善 → `check/finalize`	任意项目
全局启用	`skiff install <name>`	任意
项目启用	`skiff enable <name>`	项目目录
看状态	`skiff status`	任意
装社区 skill	`npx skills add owner/repo -g -y`	任意
更新外部 skill	`skiff fetch <name>`	任意

11 KiB Raw Blame History Unescape Escape