skillify

/skillify —— 创建、适配或更新技能

一种技能，四种模式。根据输入信号自动路由到合适的模式。

整合并取代了先前的 create-skill、adapt-skill 和 update-skill（自 v0.2.0 起合并，以确保与 -ify 三部曲的词汇护城河保持一致）。

步骤 0 — 检测模式

根据输入信号路由：

信号	模式
在对话中途调用，且近期讨论过实质性的工作流	CREATE / from-chat（默认）
/skillify from-video <url> 或 /skillify + 视频 URL	CREATE / from-video
/skillify from-dump + 粘贴的简介／转录文本／笔记	CREATE / from-dump
/skillify from-scratch <name> 或在没有上下文时说“创建一个名为 X 的新技能”	CREATE / from-scratch
/skillify <github-url> 或“适配此技能”／“移植此技能”／“分叉此技能” + 外部来源	ADAPT
/skillify <existing-skill> <change> 或“更新 X 技能”／“传播这条经验”	UPDATE / targeted
/skillify update（对话中途）	UPDATE / from-chat — 扫描近期对话中的经验
/skillify usage <skill>	UPDATE / usage — 查看近期运行记录并提出改进建议
/skillify test <skill-or-path> 或“测试此技能”／“演练 X”／“试运行 X”	TEST — 根据评估标准模拟使用

如果存在歧义，请先询问再继续。涉及外部 URL 时，绝不要猜测应选择 CREATE 还是 ADAPT。

---

模式：CREATE

根据对话／视频／内容转储／从零开始创建新技能。

步骤 1 — 确认输入来源

子模式	内容
from-chat（默认）	从本次对话中讨论的工作流提取技能。这是最常见的情况。
from-video	用户录制了 Loom／Zoom／屏幕共享视频。以视觉模式调用 watch-video → 转录文本 + 关键视觉片段 → SKILL.md。适用于视觉／UI 密集型工作流。
from-dump	用户粘贴简介、先前对话转录文本、导出的聊天记录或笔记。
from-scratch	没有源材料的新想法 — 通过交互式问答进行。

步骤 2 — 遵循 Anthropic 对 schema 的指导

不要重新发明 SKILL.md 格式规则。关于 frontmatter、描述撰写、references/ 结构和技能最佳实践：

• compound-engineering:create-agent-skill（Agent）— 创建和编辑 Claude Code 技能的专家指导
• compound-engineering:skill-creator（技能）— 编写高效技能的深入指南
• compound-engineering:heal-skill（技能）— 修复现有技能
• anthropics/skills — Anthropic 官方示例
• agentskills.io — 开放的 Agent Skills 规范

不确定格式时，直接调用这些资源。skillify 负责协调你的工作流——使用哪个代码仓库、遵循哪些约定、采用哪些交叉引用。格式方面的专业知识由上游资源提供。

步骤 3 — 选择目标代码仓库

如果存在，从 ${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/skillify/repos.yaml 加载用户的同级代码仓库列表。否则，默认使用 makerskills（此代码仓库）。示例格式：

# ~/.config/makerskills/skillify/repos.yaml
repos:
  - name: makerskills
    domain: Personal cross-cutting operator work
    path: ~/code/makerskills
  - name: marketingskills
    domain: Generic marketing tactics
    path: ~/code/marketingskills

如果根据技能所属领域可以明确判断目标，则推断目标；如果存在歧义，请询问。

第 4 步 — 按子模式进行综合

from-chat：

1. 倒序阅读这段对话。查找重复多次的工作流、重新解释的流程、重申的观点，以及关于工具、语气或输出的决策。
2. 找出关键要素：触发条件、步骤、参考资料、成功标准、语气。
3. 提出搭建框架前需要澄清的问题——提出 2–4 个简明问题。
4. 起草 SKILL.md，在文中引用对话内容（“根据你提到 X 的消息……”），方便用户核实。

from-dump：

1. 解析转储内容（Notion 页面、Slack 线程、Loom 转录、队友简报、导出的 ChatGPT 对话）。
2. 使用相同的综合逻辑。
3. 注明各项规则在转储内容中的出处。

from-video：

1. 获取 URL 或本地路径。
2. 调用 watch-video <url> visual——获取转录、关键视觉片段和摘要。
3. 阅读输出文件：<workdir>/transcript.txt、<workdir>/moments.md、<workdir>/summary.md。
4. 综合整理：触发条件（前 30 秒）、步骤（视觉片段及对应转录）、使用的工具、决策点（“如果 X，就做 Y”）、成功标准（最后几秒）、语气节奏。
5. 指出需要澄清的空缺——含糊不清的片段。
6. 起草 SKILL.md，并引用视频时间戳。
7. 可选择将源内容保存到 second-brain，命名为 call-<slug>.md 或 note-<slug>.md。

经验法则：录制时长超过 10 分钟 = 这个流程可能太复杂，不适合放进一个 skill。建议先拆分，再起草。

from-scratch： 交互式问答：

1. 名称（kebab-case，优先采用动词-名词形式——与 watch-video、read-book、paste 一致）
2. 一句话说明用途
3. 触发短语（4–8 个）
4. 是否有初始参考文件？
5. 与哪些其他 skills 组合使用？

第 5 步 — 生成 frontmatter

---
name: <kebab-case>
description: <rich, trigger-rich, ~2–4 sentences. Lead with "When you want to..." Include 4–8 trigger phrases in quotes. Differentiate from adjacent skills.>
metadata:
  version: 0.1.0
---

描述规则（至关重要——Agent 会根据描述匹配来路由）：

• 以使用场景开头（“当你想要 X 时……”）
• 明确列出触发短语
• 与相近的 skills 区分开
• 提及该 skill 会加载的关键参考资料
• 控制在约 500 个字符以内（Agent Skills 规范的硬性上限为 1024；限制更严格的宿主可能会拒绝更长的描述）

如需更深入的描述撰写指南，请参阅 compound-engineering:skill-creator。

第 6 步 — 搭建目录

<target-repo>/skills/<name>/
├── SKILL.md
└── references/
    └── ...

正文遵循现有 skills（pm、decide、second-brain）的模式：

• # /<name> — <one-line purpose>
• 带编号的 ## Step N — <phase> 部分
• 组合使用的交叉引用
• 末尾附上质量说明

第 7 步 — 更新 README、提交并推送

在目标仓库的 README skills 表格中追加一行：

| [`<name>`](./skills/<name>/SKILL.md) | <one-line purpose> |

提交并推送。报告新 skill 的路径、提交哈希，并提醒用户 /plugin install 或符号链接可能需要刷新。

第 8 步 — 提供后续选项

• “在提交前对草稿运行 TEST 模式？”（推荐用于任何会向用户提问的 skill）
• “现在完善某个特定步骤，还是之后再继续？”
• “运行 compound-engineering:heal-skill 做一次质量检查？”
• “要让这个 skill 与 [相邻 skill] 组合使用吗？”

---

模式：ADAPT

将外部 skill（GitHub URL、agentskills.io、本地磁盘内容或粘贴的 SKILL.md）移植到你的命名空间中。

第 1 步 — 获取源内容

接受以下内容：

• GitHub URL，指向 SKILL.md 或仓库（https://github.com/<owner>/<repo> 或 SKILL.md 的完整路径）
• agentskills.io URL 或 skills.sh URL
• 本地路径，指向磁盘上已有的 skill（其他已安装的插件，例如 Claude Code 中的 ~/.claude/plugins/、其他位置的 ~/.agents/skills/ 或 ~/.codex/skills/）
• 粘贴的 SKILL.md 内容

# GitHub repo: clone shallow
git clone --depth 1 <url> /tmp/skillify-adapt-<short-id>/
# OR fetch a single file
gh api -H "Accept: application/vnd.github.raw" repos/<owner>/<repo>/contents/SKILL.md > /tmp/adapt-source.md

记录提交 SHA，以便将来源归属指向稳定版本。

第 2 步 — 分析 + 分类

阅读源 SKILL.md + 随附的任何 references/。根据 references/adapt-buckets.md 将内容分为三个类别：

类别	内容	示例
原样保留	格式、架构、机制、脚本、框架	问题库、ffmpeg 参数、正则表达式模式、JSON 架构
适配	工具默认设置、路径、语气、命名、观点	他们的视频工具 → 你的 watch-video，他们的看板 → 你的 pm，他们的语气 → 你的语气
添加	指向你现有技能的交叉引用、组合说明、你的约定	“与 decide 组合使用”、“保存到 second-brain raw/”、“本地使用 MLX-Whisper”

先将分类结果以表格形式输出，供审批后再进行编写。不要悄悄改写——明确列出改动。

第 3 步 — 许可证检查

阅读源代码的 LICENSE。根据 references/adapt-license-check.md：

许可证	操作
MIT / Apache-2.0 / BSD / ISC / CC0	✅ 绿色 — 继续
MPL-2.0 / LGPL	🟡 黄色 — 可以适配；提醒文件级互惠义务
GPL-2.0 / GPL-3.0 / AGPL	❌ 红色 — 有传染性风险。继续前先说明。
专有许可证 / 无许可证	❌ 红色 — 停止。没有复制的法律依据。
不明确	🟡 黄色 — 询问；如有不确定，默认跳过

对于宽松许可证，唯一要求是注明来源——在第 6 步处理。

第 4 步 — 选择目标仓库

与 CREATE 第 3 步使用相同的表格。

第 5 步 — 改写

原样保留：直接复制；如有帮助，可添加 `` 标记。

适配：

• 命名：如果名称不是动词-名词结构，则重命名（与 watch-video、read-book、paste 一致）
• 工具替换：他们的通用看板 → pm，他们的视频工具 → watch-video，他们的笔记系统 → second-brain，他们的决策框架 → decide
• 语气：遵循你的语气规则——直接、坚定。对于与社交相关的技能，遵循链接放置规则。
• 路径：他们的 ~/outputs/ → 你的 ~/Documents/<skill>-<...>/ 约定；他们的配置 → 你的 references/ 模式
• 名称 + 上下文：在技能需要时，将通用示例替换为你的作品集上下文

添加：

• 指向现有同级技能的交叉引用
• 组合说明（此技能调用哪些其他技能，或为哪些技能提供输入）
• 你的约定（frontmatter 版本、references/ 子目录结构、如果产生子想法则添加 BACKLOG 条目）

第 6 步 — 来源说明文件

编写 references/attribution.md：

# Attribution

- **Source**: <original SKILL.md URL>
- **Repository**: <repo URL>
- **Author**: <name + handle>
- **Commit SHA**: <SHA at time of adapt>
- **License**: <license name + URL>
- **Adapted**: <YYYY-MM-DD>

## What was kept verbatim
- ...

## What was adapted
- <old> → <new>

## What was added
- ...

## License compliance
<upstream LICENSE text if MIT/BSD/Apache requires it, OR reference where in this repo it lives>

## Upgrade path
Run `git ls-remote <repo-url> HEAD`. If SHA differs from above, re-run `/skillify <same-url>` for a 3-way merge.

对于 MIT / Apache / BSD 许可证，将 LICENSE 文本复制到此文件中，或将源 LICENSE 文件复制到技能目录中。

第 7 步 — 搭建框架 + 提交

与 CREATE 第 6–7 步相同。提交信息："Adapt <name> skill from <source-name>"。

第 8 步 — 汇报 + 提供后续选项

• 提交哈希 + 新技能路径
• 再次展示三个类别的分类结果，以便清楚查看差异
• 提供以下选项：
  • “进一步完善适配内容？某些默认设置可能还需要你调整。”
  • “运行 compound-engineering:heal-skill 进行 QA 检查？”
  • “通过 loopify 设置上游检查提醒？”

---

模式：UPDATE

根据经验改进现有技能。

第 1 步 — 确认子模式

子模式	适用情况
from-chat（默认）	扫描近期对话中的经验，确定受影响的技能
from-dump	用户提供简报、反馈、转录稿或复盘材料
targeted	用户直接指定技能和改动。跳过发现步骤。
usage	检查指定技能的近期运行情况，找出不足

在对话进行期间调用，且近期有实质性活动时，默认使用：from-chat。

步骤 2 — 提取经验

对于 from-chat / from-dump / usage：寻找值得修改的信号（完整分类见 references/update-change-types.md）：

• 纠正 — “不，以后别再那样做了”
• 验证 — “对，这样有效——把它纳入规则”
• 新模式 — 用户刚刚采用了未记录的工作流；将其记录下来
• 风格 / 语气更新 — 例如 slide-deck 的朗读规则
• 工具变更 — 更改了默认设置
• 架构决策 — 命名约定、文件布局、frontmatter
• 缺漏 — 本应由技能处理，但实际未能处理的内容

输出：清晰列出 N 条经验，每条都表述为一项单独的修改。

对于 targeted：跳过提取——用户已经明确了要修改的内容。

步骤 3 — 找出受影响的技能

针对每条经验，在当前仓库的所有 SKILL.md 和 references/ 中搜索（也可以通过 --cross-repo 搜索 repos.yaml 中的所有同级仓库）：

grep -rln "<key terms>" ~/code/makerskills/skills/ --include="*.md"

# Across all sibling repos (list yours in $MAKERSKILLS_CONFIG/skillify/repos.yaml):
config="${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/skillify/repos.yaml"
for raw in $(yq -r '.repos[].path' "$config"); do
  repo="${raw/#\~/$HOME}"  # expand leading ~ to $HOME so grep resolves the real path
  grep -rln "<terms>" "$repo/skills/" --include="*.md" 2>/dev/null
done

按置信度分类：

置信度	含义	操作
高	直接匹配关键词，且主题明显相同	提议修改
中	相关主题——规则可能适用	提交用户明确批准
低	只有间接关联——牵强套用规则	提及，但不提议修改

跨技能传播操作指南见 references/update-propagation.md。

步骤 4 — 判断应记入记忆还是技能

针对每条经验：这是特定于某项技能的规则，还是更广泛的原则？

类型	记录位置
特定于技能的规则	直接编辑 SKILL.md / references 文件
跨领域原则	记入记忆存储中的 feedback_<topic>.md（Agent 记忆，或 ${MAKERSKILLS_MEMORY:-${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/memory}/）
两者兼有	写入记忆文件，并更新直接适用的技能

示例：“链接放在首条评论中，而不是正文里” → 适用于 jab-hook，同时也是更广泛的社交原则 → 两者都要做：更新 jab-hook，并保存 feedback_social_link_placement.md。

明确询问是否写入记忆：“这看起来是一项原则，而不只是技能规则。要将其保存为 feedback_<slug>.md 吗？”

步骤 5 — 按文件提出差异

对每个受影响的文件，通过修改前后对比或统一差异展示变更：

### `skills/<skill>/SKILL.md` — proposed change

**Before** (lines NN–NN):
> <existing text>

**After**:
> <new text>

**Why**: <one-line rationale>

**Version bump**: 0.2.0 → 0.2.1 (PATCH — clarification)

**Approve / edit / skip?**

每个文件单独审批。不要合并处理——小改动很容易批准；打包处理会迫使用户只能全盘接受或全盘拒绝。

语义化版本规则见 references/update-versioning.md。

步骤 6 — 应用已批准的修改

1. 使用 Edit 应用准确的修改
2. 按建议的级别更新 metadata.version
3. 如果修改涉及重命名，请遵循交叉引用更新模式（搜索所有文件，更新所有引用）

将同一技能中的多个文件修改合并为一次提交。

步骤 7 — 提交并推送

按技能分组。示例：

• 更新一项技能："slide-deck: emphasize spoken-aloud voice (write for the ear, not the page)"
• 跨技能传播："jab-hook, marketingskills:social: link placement (no inline URLs)"
• 跨仓库：每个仓库各提交一次。不要跨仓库进行原子提交。

步骤 8 — 报告

展示：

• 提取的经验
• 已更新的技能（包括版本号变更）
• 已写入的记忆文件
• compound-engineering:heal-skill 是否适合作为 QA 检查
• 是否值得运行 TEST（大幅重新设计：值得——先前的检查验证的是旧文本）
• 已标记但跳过的内容

何时不使用 UPDATE 模式

不要给小范围的精准编辑增加繁琐流程。如果用户说“在 X.md 中加上这一条”，直接使用 Edit。UPDATE 模式适用于以下情况：

1. 多项技能受到同一条经验的影响（跨技能传播）
2. 从长时间会话中批量提取
3. 难以判断应记入记忆还是技能（需要明确分流）
4. 需要严格管理版本（即将提交，并希望采用合理的语义化版本）

对于没有跨技能影响的一行修改：直接使用 Edit。

---

模式：TEST

在真实用户使用前观察技能运行情况。让模拟用户按照 SKILL.md 扮演真实用户，根据固定评分标准评判每份对话记录，并将每项失败转化为补丁。适用于已发布的技能（在 UPDATE 前后进行回归检查）以及新建的 CREATE/ADAPT 草稿。

完整场景集、评分标准和评判规则：references/test-rubric.md。请在步骤 2 前阅读。

步骤 1 — 确定目标并隔离

• 技能名称 → <repo>/skills/<name>/SKILL.md（repo 按 CREATE 步骤 3 确定）
• 明确路径 → 该文件
• 两者都没有 → 询问

固定受测版本。 子 Agent 会在运行期间从磁盘读取文件。如果工作树可能在它们运行时发生变化（例如切换分支、合并或编辑），请让它们使用冻结副本：git worktree add <scratch>/wt-<skill> <commit>（之后将其移除），或复制技能文件夹作为快照。否则，它们会在开始时测试当时检出的版本，并报告并非真实存在的问题。

阅读 SKILL.md 及其中要求 Agent 加载的所有 references/ 文件——仅此一次。从现在起，模拟执行者只知道这些文件。它需要但文件中没有的信息，应作为问题记录，而不是自行补充。如果宿主支持生成子 Agent，请让每个场景由独立的子 Agent 执行，并在提示中只提供技能路径、场景和试运行规则，同时要求它不要阅读其他内容。否则，亲自扮演双方，并先用一行说明隔离范围。

始终进行试运行。 模拟执行者的任何操作都不得超出对话记录。这意味着不得写入文件、创建草稿、提出问题单、提交、推送或调用付费 API；只展示这些操作。完整规则见 references/test-rubric.md。

步骤 2 — 选择场景

从 references/test-rubric.md 的表格中选择 3–6 个场景：始终包含 canonical、terse 和 boundary；当技能设计需要时，选择 refusal、lazy-answerer、die-and-resume 和 missing-config。每个场景用一行描述角色。展示列表；除非用户更换场景，否则继续。

步骤 3 — 运行对话记录

每个场景进行 6–12 轮，格式为 USER: / WIELDER:。模拟真实用户（回答不充分、提出反对、尝试走捷径）。执行者应按文件要求行事（指出模糊之处，绝不理想化）。问题得到解答后即停止。

步骤 4 — 评判

对每项适用的评分标准给出 PASS / WEAK / FAIL，并引用一行作为证据。没有引文，就不算发现问题。

步骤 5 — 报告并修补

1. 评定结果表 — 场景 × 评分标准
2. 补丁列表 — 将每个 FAIL/WEAK 对应到导致问题的章节，标注为 缺失/模糊 或 容易偏离，并给出具体修改
3. 将补丁交给 UPDATE 模式处理（逐文件审批、版本号递增），然后只重新运行失败的场景

通过全部检查也是有效结果。说明这一点，然后停止。

---

可组合使用

• watch-video — 对 CREATE / from-video 至关重要。视觉模式的输出（转录内容 + 关键视觉时刻 + 摘要）是合成技能的输入。处理过程录制时，始终调用 visual 模式——UI 状态与文字同样重要。
• second-brain — 可选：将源视频/转储记录为 raw/call-<slug>.md 或 raw/note-<slug>.md，让源材料与由其生成的技能保存在一起。
• toolify — -ify 三件套中的同类工具。如果目标是添加集成/MCP/API，而不是编写技能，请使用 toolify。
• loopify — -ify 三件套中的同类工具。要设置 Agent 循环而非技能时，请使用 loopify。
• compound-engineering:create-agent-skill（Agent）— 获取格式和最佳实践方面的专业知识
• compound-engineering:skill-creator（技能）— 更深入的最佳实践参考
• compound-engineering:heal-skill（技能）— 在任何模式之后进行 QA 检查

质量说明

• 注明来源。 无论内容来自聊天、视频、转储文件、外部 URL，还是用户指定的学习内容，SKILL.md 正文都应注明每项决策的来源，便于后续修订。
• 不要过度设计 v0.1。 先发布精简的 SKILL.md 和 1–2 个参考文件。首次使用后再迭代。大多数生成的技能范围都过大。
• 尽可能采用“动词-名词”命名（与 watch-video、read-book、paste 的形式一致）。对于有鲜明特点的概念，也可以使用单词名词（decide、pm、paste、skillify）。
• 始终参考 Anthropic 的官方指南来确定架构，不要自行发明格式约定。
• 面向任何 Agent 宿主编写，而不只是 Claude Code：
  • 说明功能，而非工具名称（写“获取 URL”，不要使用 Claude Code 的 fetch 工具之类的宿主工具名称；写“Typefully 的创建草稿工具”，不要使用原始 MCP 工具 ID）。
  • 记忆存放在 Agent 的记忆目录中，或 ${MAKERSKILLS_MEMORY:-${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/memory}/，绝不能使用硬编码的 Claude Code 记忆路径。
  • 对于用户自定义的架构/配置文档，读取 CLAUDE.md 或 AGENTS.md。
  • 为仅限 macOS 的命令（剪贴板、open、MLX）提供 Linux 替代方案，例如 wl-copy/xclip、xdg-open、faster-whisper。
  • 如果某项技能确实需要 Claude Code 的功能，请在正文中说明，并提供其他宿主的使用路径（参见 loopify）。
• 归属信息不可或缺：ADAPT 模式下，每项改编后的技能都必须包含 references/attribution.md。
• 许可证是硬性门槛。 未获得明确批准，不要继续处理 GPL/专有许可证内容。
• UPDATE 模式下逐文件审批。 小改动容易批准；捆绑审批会导致只能全盘接受或拒绝。
• 阅读技能不等于测试技能。 一条读起来合理的规则仍可能无法触发。TEST 模式评估的是对话记录，而非文字；如果实时运行出现 TEST 未发现的问题，应将缺失的场景或标准补充到 references/test-rubric.md。