skill-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill creation

技能创建

This skill helps you build new skills and improve existing ones. Think of it as the skill that teaches you how to learn.

本技能可帮助你构建新技能并优化现有技能。可以将其视为教你如何学习的技能。

Why bother with skills?

为什么要重视技能？

Every time you solve a problem, that knowledge usually dies with the session. Skills fix that. They're how you turn "I figured this out once" into "I know how to do this."

A few reasons to extract skills:

You won't have to re-discover the same solution next month
Other sessions (and other users) benefit from what you learned
Complex workflows become repeatable instead of fragile

每次你解决一个问题，相关知识通常会随着会话结束而流失。技能可以解决这个问题，它们能将“我曾经解决过这个问题”转化为“我知道如何解决这个问题”。

提取技能的几个原因：

下个月你不必重新摸索相同的解决方案
其他会话（以及其他用户）可以从你的经验中受益
复杂的工作流变得可重复，而非脆弱易断

The basic format

基本格式

Skills live in a folder with a

SKILL.md

file:

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

The file has YAML frontmatter and markdown content:

markdown

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

技能存储在包含

SKILL.md

文件的文件夹中：

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

该文件包含YAML前置元数据和Markdown内容：

markdown

---
name: my-skill
version: 1.0.0
description: |
  本技能的功能。
  使用场景。
---

My skill

Instructions go here.


The `description` matters a lot. It's how the agent decides whether to load your skill for a given task. Be specific about the problems it solves.

说明内容写在这里。


`description`非常重要，它是智能体决定是否为特定任务加载你的技能的依据。请明确说明它能解决的问题。

When to create a skill

何时创建技能

Not everything deserves to be a skill. Skills are for complex or long workflows that someone might need to repeat or share. If it's a simple one-off task, a skill is overkill.

The right level of specificity matters. A skill for "debugging in a codebase" is useful if there's a lot of common failure modes that agents might encounter. A skill for "debugging the login flow" is probably too narrow. Find the balance between general enough to reuse and specific enough to be helpful.

Ask yourself:

Did I have to dig around to figure this out?
Would I be annoyed if I had to solve this again from scratch?
Is there something here that isn't obvious from the docs?

If yes to any of those, probably worth extracting. If it was straightforward or you just followed a tutorial, skip it.

Skills can also encode preferences and best practices. Maybe a user always logs into a specific platform when doing data analysis. Maybe there's a gotcha the team keeps hitting. If you notice you're consistently doing something the user has to correct or adjust, that's worth including.

并非所有内容都值得做成技能。技能适用于复杂或冗长、可能需要重复执行或分享的工作流。如果是简单的一次性任务，技能就有些大材小用了。

把握合适的粒度很重要。如果代码库中有大量智能体可能遇到的常见故障模式，那么“代码库调试”技能会很有用。而“登录流程调试”技能可能过于狭窄。要在足够通用以便复用和足够具体以便实用之间找到平衡。

问问自己：

我是否需要花时间摸索才找到解决方案？
如果让我从头开始再次解决这个问题，我会感到厌烦吗？
这里有没有文档中没有明确说明的内容？

如果以上任何一个问题的答案是肯定的，那么提取成技能可能是值得的。如果解决过程很直接，或者你只是按照教程操作，那就没必要了。

技能还可以记录偏好和最佳实践。比如用户在做数据分析时总是登录某个特定平台，或者团队反复遇到某个陷阱。如果你发现自己一直在做用户需要纠正或调整的事情，那这部分内容就值得纳入技能。

Extracting skills from sessions

从会话中提取技能

Use the

session-navigation

skill to dig through past sessions and find patterns worth extracting. Look for things that came up multiple times, solutions that took real effort to figure out, or workflows you keep repeating.

Once you've found something, generalize it. Replace specific paths with patterns, note the prerequisites, call out assumptions. The skill should work for similar situations, not just the exact case you found.

使用

session-navigation

技能挖掘过往会话，找到值得提取的模式。寻找多次出现的内容、需要花费精力才能找到的解决方案，或者你反复执行的工作流。

找到合适的内容后，对其进行泛化处理。将具体路径替换为通用模式，注明前提条件，指出假设。技能应适用于类似场景，而不仅仅是你发现的具体案例。

Skill design tips

技能设计技巧

When writing the skill, use the

human-writing

skill. Skill docs that read like marketing copy are harder to follow.

Start small. A skill that does one thing well beats a skill that tries to cover everything. You can always compose multiple skills together.

Include verification. How do you know the skill worked? Add a check at the end:

markdown

undefined

编写技能时，请使用

human-writing

技能。读起来像营销文案的技能文档更难遵循。

从小处着手。一个能把一件事做好的技能胜过试图涵盖所有内容的技能。你始终可以将多个技能组合使用。

包含验证步骤。如何确认技能生效了？在末尾添加检查步骤：

markdown

undefined

Verify it worked

验证生效情况

Run

npm test

and make sure nothing broke. Check that the new file exists at

src/config.ts


**Document the failures too.** What doesn't work? What should you avoid? This saves future pain:

```markdown

运行

npm test

，确保没有出现问题。检查新文件是否存在于

src/config.ts

路径下。


**也要记录失败情况**。哪些情况不适用？需要避免什么？这能避免未来的麻烦：

```markdown

What not to do

注意事项

Don't run this on a dirty git working directory. The

--force

flag will overwrite without asking.


**Keep it fresh.** Skills rot. Dependencies change, APIs update, better approaches emerge. If a skill stops working or feels outdated, update it or delete it.

不要在未提交的Git工作目录中运行此技能。

--force

参数会直接覆盖内容，不会询问确认。


**保持技能更新**。技能会过时。依赖项变化、API更新、更好的方法不断出现。如果某个技能失效或显得过时，请更新或删除它。

Where skills live

技能存储位置

Location	Who sees it
`.factory/skills/`	Everyone on the project (commit it to git)
`~/.factory/skills/`	Just you, across all projects

Project skills are good for team conventions. Personal skills are good for your own workflows.

位置	可见范围
`.factory/skills/`	项目中的所有成员（提交到Git）
`~/.factory/skills/`	仅你自己可见，可跨所有项目使用

项目技能适用于团队约定，个人技能适用于你自己的工作流。

Improving existing skills

优化现有技能

Signs a skill needs work:

Users ask follow-up questions after it runs
It fails on edge cases that keep coming up
There's a better approach now than when it was written

To find patterns:

bash

undefined

技能需要优化的迹象：

用户在技能执行后提出后续问题
它在反复出现的边缘案例中失效
现在有比创建时更好的解决方案

查找模式的方法：

bash

undefined

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


When you update a skill, bump the version. If it's a breaking change (different output, different inputs), bump the major version.

rg "error|failed|retry" ~/.factory/sessions/*.jsonl -C 3


更新技能时，请升级版本号。如果是破坏性变更（输出或输入不同），请升级主版本号。

Research notes

研究笔记

Some of this comes from academic work on agents that learn:

Voyager showed that agents can build up skill libraries over time, with each skill composed from simpler ones.

CASCADE demonstrated that skills can be shared between agents, not just stored for one agent's use.

SEAgent found that learning from failures is as valuable as learning from successes.

Reflexion showed that verbal feedback (explaining what went wrong in plain language) beats numeric scores for improving agent behavior.

部分内容来自关于智能体学习的学术研究：

Voyager表明，智能体可以逐步构建技能库，每个技能由更简单的技能组合而成。

CASCADE证明，技能可以在智能体之间共享，而不仅仅是为单个智能体存储使用。

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

Reflexion表明，语言反馈（用通俗易懂的语言解释问题所在）在改善智能体行为方面优于数值评分。

The loop

循环流程

Work on something
Notice when you learn something non-obvious
Extract it as a skill
Use the skill next time
Improve the skill based on how it goes
Repeat

处理某项工作
留意你学到的非显而易见的知识
将其提取为技能
下次使用该技能
根据使用情况优化技能
重复上述步骤