.pouch/AGENTS.md

Agent Skills 仓库

自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容与本仓库内的 skiff CLI 一并维护。

组件	路径	职责
skills/	本仓库	skill 内容与规范
skiff/	本仓库	安装、symlink、健康检查（Python 3，无编译）

---

快速开始

# 1. 克隆并安装 CLI
git clone https://git.yumee.top/laily/skills.git ~/code/gitea/skills
cd ~/code/gitea/skills && ./install.sh
skiff setup ~/code/gitea/skills

# 2. 全局安装 skill
skiff install declarative-openspec-loop

# 3. 查看状态
skiff list
skiff status

---

仓库结构

skills/
├── _template/                  # 新建 skill 的脚手架
├── 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/、skiff/、registry.yaml、AGENTS.md
本仓库不包含：各项目的 skill 启用清单（.skills.yaml）

---

Skill 目录

自研（Owned）

Skill	说明
declarative-openspec-loop	声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过
discussion-notes	讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md

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

外部（External Git）

在 registry.yaml 中注册，通过 skiff 拉取安装：

Skill	来源
superpowers	https://github.com/obra/superpowers

skiff fetch superpowers
skiff install-external superpowers

社区（External NPM / GitHub）

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

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

---

设计原则

1. SSOT — 自研 skill 只存在于 skills/<name>/，不在 Agent 目录直接创建
2. 项目自治 — 每个项目自己维护 .skills.yaml，本仓库不维护项目清单
3. 软链优先 — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
4. 一体维护 — skill 内容与 skiff CLI 同仓库，Python 3 直接运行，无需编译

---

架构

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

Skill 三层分类

层级	位置	维护方式
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/
Claude Code	~/.claude/skills/	.claude/skills/
Codex	~/.codex/skills/	.agents/skills/

---

项目级启用

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

# .skills.yaml（在项目根目录）
skills:
  - declarative-openspec-loop
  - name: superpowers
    source: registry
    ref: main

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 命令

CLI 源码在 skiff/，安装：./install.sh（软链到 ~/.local/bin/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）。

---

Skill 编写规范

遵循 Agent Skills 开放标准：

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

Frontmatter

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

命名

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

新建流程

1. cp -r skills/_template skills/my-skill
2. 编辑 skills/my-skill/SKILL.md
3. skiff install my-skill --target cursor 验证
4. 在本仓库 commit
5. 各项目 skiff enable 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

---

日常速查

我要…	命令	在哪
首次 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>	任意

---

参考

• Agent Skills 开放标准
• Vercel skills CLI
• skills.sh
• Cursor Skills 文档