skill-creation

创建技能

此技能可帮助你构建新技能并改进现有技能。可以把它看作教你如何学习的技能。

为什么要创建技能？

每次解决问题时，相关知识通常都会随着会话结束而消失。技能可以解决这个问题。它们能把“我曾经弄明白过”变成“我知道该怎么做”。

提炼技能有几个好处：

• 下个月你就不用重新摸索同一个解决方案
• 其他会话（以及其他用户）也能从你的经验中受益
• 复杂的工作流可以重复执行，而不再脆弱易错

基本格式

技能放在包含 SKILL.md 文件的文件夹中：

.factory/skills/my-skill/
└── SKILL.md

该文件包含 YAML frontmatter 和 Markdown 内容：

---
name: my-skill
version: 1.0.0
description: |
  What this skill does.
  When to use it.
---

# My skill

Instructions go here.

description 非常重要。Agent 会根据它判断是否为特定任务加载你的技能。请具体说明技能能解决哪些问题。

何时创建技能

不是所有内容都值得写成技能。技能适用于复杂或耗时较长、可能需要重复执行或分享的工作流。如果只是简单的一次性任务，创建技能就有些小题大做了。

恰当的具体程度很重要。如果代码库中有许多 Agent 可能遇到的常见故障模式，那么“在代码库中调试”这样的技能就很有用。而“调试登录流程”这样的技能可能过于狭窄。要在足够通用、便于复用和足够具体、切实有用之间找到平衡。

问问自己：

• 我是否得花一番工夫才能弄明白这件事？
• 如果要从头再解决一次，我会不会觉得烦？
• 这里是否有些内容在文档中并不明显？

只要有一个答案是肯定的，就可能值得提炼成技能。如果事情很简单，或者你只是照着教程操作，那就跳过。

技能也可以记录偏好和最佳实践。比如，用户在进行数据分析时总是会登录某个特定平台。或者团队总是会遇到某个陷阱。如果你发现自己经常做某件需要用户纠正或调整的事，就值得把它写进去。

从会话中提炼技能

使用 session-navigation 技能深入查看过去的会话，找出值得提炼的规律。留意反复出现的问题、需要花费大量精力才能找到解决方法的情况，或你不断重复的工作流。

找到内容后，将其归纳总结。把具体路径替换成模式，注明前置条件，并指出假设。技能应适用于类似场景，而不只是你找到的那个具体案例。

技能设计技巧

编写技能时，请使用 human-writing 技能。读起来像营销文案的技能文档更难遵循。

从小处着手。 做好一件事的技能，胜过试图涵盖所有内容的技能。你随时可以组合多个技能。

加入验证步骤。 如何确认技能有效？在末尾添加一项检查：

## Verify it worked

Run `npm test` and make sure nothing broke.
Check that the new file exists at `src/config.ts`.

也要记录失败情况。 哪些方法行不通？应该避免什么？这能减少今后的麻烦：

## What not to do

Don't run this on a dirty git working directory.
The `--force` flag will overwrite without asking.

保持内容更新。 技能会逐渐过时。依赖项会变化，API 会更新，也会出现更好的方法。如果技能停止工作或显得过时，请更新或删除它。

技能存放位置

位置	谁可以看到
.factory/skills/	项目中的所有人（将其提交到 git）
~/.factory/skills/	你本人，可在所有项目中使用

项目技能适合记录团队规范。个人技能适合记录你自己的工作流。

改进现有技能

技能需要改进的迹象：

• 技能运行后，用户还会提出后续问题
• 技能总是在反复出现的边缘情况下失败
• 现在有比编写技能时更好的方法

查找规律：

# Which sessions used this skill?
rg -l "skill-name" ~/.factory/sessions/*.jsonl

# Where did things go wrong?
rg "error|failed|retry" ~/.factory/sessions/*.jsonl -C 3

更新技能时，请递增版本号。如果属于破坏性更改（输出或输入发生变化），请递增主版本号。

研究笔记

其中一些内容源自关于学习型 Agent 的学术研究：

Voyager 表明，Agent 可以逐步构建技能库，每项技能都由更简单的技能组成。

CASCADE 证明，技能可以在 Agent 之间共享，而不仅仅是存储起来供某个 Agent 使用。

SEAgent 发现，从失败中学习与从成功中学习同样有价值。

Reflexion 表明，文字反馈（用通俗语言解释哪里出了问题）比数字评分更能改善 Agent 的行为。

循环

1. 处理某件事
2. 留意自己何时学到了非显而易见的知识
3. 将其提炼为一项技能
4. 下次使用这项技能
5. 根据使用效果改进这项技能
6. 重复此过程