refine

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Refine

优化

Review this session. Identify patterns worth capturing as new skills, improvements to existing skills, or additions to CLAUDE.md.

回顾本次会话，识别值得提炼为新技能、现有技能改进点或CLAUDE.md补充内容的模式。

Step 1: Scan the session

步骤1：扫描会话

Identify what happened:

Which skills were invoked (look for
```
<command-name>
```
tags) or created?
What corrections did the user make? These are the most valuable signals.
What workflows were repeated?
What preferences or conventions emerged?

明确会话中发生的内容：

调用或创建了哪些技能（查找
```
<command-name>
```
标签）？
用户做出了哪些修正？这些是最有价值的信号。
哪些工作流被重复执行？
浮现出哪些偏好或约定？

Step 2: Evaluate the skills

步骤2：评估技能

If skills were created or edited this session, they're already in your context — no need to re-read them. Evaluate what you already have.

If skills were used but not edited, read the actual SKILL.md files to see their current state. Check these locations:

bash

ls -la ~/.claude/skills/ 2>/dev/null
ls -la .claude/skills/ 2>/dev/null
ls -la ~/.refined/ 2>/dev/null

For each skill, whether from context or from reading, evaluate:

Is the description specific enough to trigger correctly?
Are the instructions clear and complete based on how the skill was actually used?
Did the session reveal gaps, edge cases, or missing steps?
Are references to other files/skills correct?

Check ownership before editing:

Symlink →
```
~/.refined/
```
: yours to refine
Symlink → a plugin dir: read-only (updates would overwrite)
Regular file in
```
~/.claude/skills/
```
or
```
.claude/skills/
```
: yours to refine
Anything in
```
.agents/skills/
```
: read-only (managed by
```
npx skills
```
)

Also read the project's CLAUDE.md (and

~/.claude/CLAUDE.md

if relevant). Check whether what happened in this session — tool preferences, conventions, corrections — is reflected there or should be.

如果本次会话中创建或编辑过技能，它们已在你的上下文里——无需重新阅读。直接评估现有内容即可。

如果技能被使用但未编辑，请读取实际的SKILL.md文件查看当前状态。检查以下位置：

bash

ls -la ~/.claude/skills/ 2>/dev/null
ls -la .claude/skills/ 2>/dev/null
ls -la ~/.refined/ 2>/dev/null

对于每个技能，无论是来自上下文还是读取的文件，评估以下内容：

描述是否足够具体，能正确触发技能？
根据技能的实际使用情况，指令是否清晰完整？
会话是否暴露了技能的缺口、边缘情况或缺失步骤？
对其他文件/技能的引用是否正确？

编辑前检查所有权：

符号链接指向
```
~/.refined/
```
：可优化
符号链接指向插件目录：只读（更新会覆盖修改）
```
~/.claude/skills/
```
或
```
.claude/skills/
```
中的常规文件：可优化
```
.agents/skills/
```
中的任何内容：只读（由
```
npx skills
```
管理）

同时阅读项目的CLAUDE.md（如有相关也需查看

~/.claude/CLAUDE.md

）。检查本次会话中发生的内容——工具偏好、约定、修正——是否已在其中体现，或是应该补充进去。

Step 3: Decide

步骤3：决策

After evaluating skills and CLAUDE.md, ask three questions:

Existing skills — for each one you read:

Does the description match how it was actually used? If not, fix it.
Did the session expose missing instructions, wrong assumptions, or incomplete steps?
Did the user correct something the skill should have known?

New skills — for the session overall:

Was there a repeated workflow that has no skill yet?
Was there hard-won knowledge (debugging, research) worth preserving?
Was there a correction that indicates a process worth capturing?

CLAUDE.md — for general preferences and behavioral instructions:

Did the user correct a general behavior (not tied to a specific workflow)?
Is there a tool preference, communication style, or project convention worth persisting?
Examples: "always use uv", "don't ask before committing", "use rip instead of rm"

"Nothing to refine" is a valid conclusion — but only after genuine evaluation. The point is thoroughness, not volume. If skills are solid, say so. Just don't skip the thinking.

Constraints: max 2 skills touched per refine, max 1 new skill per refine.

评估完技能和CLAUDE.md后，思考三个问题：

现有技能——针对每个读取的技能：

描述是否与实际使用情况匹配？若不匹配则修正。
会话是否暴露了缺失的指令、错误的假设或不完整的步骤？
用户是否纠正了技能本应知晓的内容？

新技能——针对整个会话：

是否存在重复执行但尚未对应技能的工作流？
是否有值得保留的来之不易的知识（调试、研究内容）？
是否有某个修正表明存在值得固化的流程？

CLAUDE.md——针对通用偏好和行为指令：

用户是否纠正了通用行为（不绑定特定工作流）？
是否有工具偏好、沟通风格或项目约定值得持久化？
示例："始终使用uv"、"提交前无需询问"、"使用rip替代rm"

“无内容可优化”是合理结论——但需经过真实评估。关键是全面性，而非数量。若技能已足够完善，直接说明即可。切勿跳过思考过程。

约束条件：每次优化最多处理2个技能，最多新增1个技能。

Step 4: Edit

步骤4：编辑

Skills

技能

Refining an existing skill: first

ls -la

to check if it's a symlink.

Symlink to
```
~/.refined/
```
→ edit the target file in
```
~/.refined/
```
Symlink to a plugin dir or
```
.agents/skills/
```
→ do NOT edit (read-only — managed externally)
Regular file in
```
~/.claude/skills/
```
or
```
.claude/skills/
```
→ edit in place

Creating a new skill: ask the user which scope:

User skill — useful across all projects. Write to
```
~/.refined/<name>/SKILL.md
```
and symlink to
```
~/.claude/skills/<name>
```
.
Local/repo skill — specific to the current project. Write to
```
.claude/skills/<name>/SKILL.md
```
in the project's repo.

优化现有技能：先执行

ls -la

检查是否为符号链接。

符号链接指向
```
~/.refined/
```
→ 编辑
```
~/.refined/
```
中的目标文件
符号链接指向插件目录或
```
.agents/skills/
```
→ 请勿编辑（只读——由外部管理）
```
~/.claude/skills/
```
或
```
.claude/skills/
```
中的常规文件 → 直接原地编辑

创建新技能：询问用户选择的范围：

用户技能：适用于所有项目。写入
```
~/.refined/<name>/SKILL.md
```
并创建符号链接至
```
~/.claude/skills/<name>
```
。
本地/仓库技能：仅适用于当前项目。写入项目根目录下的
```
.claude/skills/<name>/SKILL.md
```
。

CLAUDE.md

Always ask before editing CLAUDE.md. Show the proposed addition and ask the user to confirm.

Only append — never modify or remove existing entries
Keep additions concise (1-3 lines per entry)
Choose the right file:
- ```
~/.claude/CLAUDE.md
```
  — global preferences (affect all projects)
- ```
.claude/CLAUDE.md
```
  or
```
CLAUDE.md
```
  in project root — project-specific

编辑CLAUDE.md前务必询问用户。展示拟添加的内容并请求确认。

仅可追加内容——切勿修改或删除现有条目
新增内容需简洁（每条1-3行）
选择正确的文件：
- ```
~/.claude/CLAUDE.md
```
  —— 全局偏好（影响所有项目）
- 项目根目录下的
```
.claude/CLAUDE.md
```
  或
```
CLAUDE.md
```
  —— 项目特定偏好

Why refine doesn't touch externally managed skills

为何优化不涉及外部管理的技能

Two categories of skills are read-only:

Plugin skills (invoked as

plugin:skill

) — namespaced and versioned by their plugin.

Editing in place breaks on update.
Copying creates ambiguity — user skill names can't contain colons, so a copy of
```
roborev:fix
```
would need a different name. Two similar skills, agent doesn't know which to pick.

Skills installed via
npx skills add
— managed by the vercel-labs/skills CLI, typically symlinked from

.agents/skills/

```
npx skills update
```
would overwrite your changes.
These are designed to be shared across agents (Claude, Cursor, Cline, etc.).

The ideal future: everyone starts from base skills that get better for their personal use over time. That needs skill override support at the platform level.

For now, if an external skill needs improving: contribute upstream or fork.

Note:

~/.refined/

is itself a valid source for

npx skills add ~/.refined

— so refined skills can be shared with other agents or users.

两类技能为只读：

插件技能（以

plugin:skill

形式调用）——由插件进行命名空间管理和版本控制。

原地编辑会在更新时被覆盖。
复制会造成歧义——用户技能名称不能包含冒号，因此
```
roborev:fix
```
的副本需使用不同名称。两个相似技能会导致Agent无法判断选择哪一个。

通过
npx skills add
安装的技能——由vercel-labs/skills CLI管理，通常符号链接自

.agents/skills/

。

```
npx skills update
```
会覆盖你的修改。
这些技能设计为可在多个Agent（Claude、Cursor、Cline等）间共享。

理想未来：所有人从基础技能起步，随着个人使用不断优化提升。这需要平台层面支持技能覆盖功能。

目前，如果外部技能需要改进：请向上游贡献代码或进行分叉。

注意：

~/.refined/

本身可作为

npx skills add ~/.refined

的有效源——因此优化后的技能可与其他Agent或用户共享。

Step 5: Link, track, and commit

步骤5：链接、跟踪与提交

For each new or modified skill, ask the user whether to git track it (default: yes for user skills, no for local/repo skills).

User skills (written to

~/.refined/

bash

undefined

对于每个新增或修改的技能，询问用户是否要通过git跟踪（默认：用户技能为是，本地/仓库技能为否）。

用户技能（写入

~/.refined/

）：

bash

undefined

Symlink into ~/.claude/skills/ (-n flag handles directory symlinks correctly)

创建符号链接至~/.claude/skills/（-n标志可正确处理目录符号链接）

ln -sfn "$HOME/.refined/<name>" "$HOME/.claude/skills/<name>"

Optional: also link into .agents/skills/ for cross-agent compatibility (Cursor, Cline, etc.)

可选：也可链接至.agents/skills/以实现跨Agent兼容（Cursor、Cline等）

Only if the user uses npx skills / multi-agent setup

仅当用户使用npx skills/多Agent环境时执行

mkdir -p .agents/skills && ln -sfn "$HOME/.refined/<name>" .agents/skills/<name>

If git-tracked:

若启用git跟踪：

git -C "$HOME/.refined" add <name>/ && git -C "$HOME/.refined" commit -m "refine: <what changed and why>"


**Local/repo skills** (written to `.claude/skills/` in the project):
```bash

git -C "$HOME/.refined" add <name>/ && git -C "$HOME/.refined" commit -m "refine: <变更内容及原因>"


**本地/仓库技能**（写入项目的`.claude/skills/`）：
```bash

Commit in the project repo if the user wants

若用户同意，在项目仓库中提交

git -C <project-root> add .claude/skills/<name>/ && git -C <project-root> commit -m "refine: <what changed and why>"


**Existing skills** (edited in place): commit in whichever repo the file belongs to.

git -C <project-root> add .claude/skills/<name>/ && git -C <project-root> commit -m "refine: <变更内容及原因>"


**现有技能**（原地编辑）：在文件所属的仓库中提交。

Skill file format

技能文件格式

yaml

---
name: skill-name
description: >
  What this skill does. Be specific — this description decides when
  the skill triggers, so vague descriptions mean it never gets used.
allowed-tools:
  - Read
  - Edit
  # only what the skill actually needs
---

The body is the prompt Claude receives when the skill is invoked. Write it as direct instructions.

yaml

---
name: skill-name
description: >
  该技能的用途。描述需具体——它决定了技能何时触发，模糊的描述会导致技能无法被正确调用。
allowed-tools:
  - Read
  - Edit
  # 仅包含技能实际需要的工具
---

文件主体是技能被调用时Claude收到的提示。请以直接指令的形式撰写。

Constraints

约束条件

Max 2 skills touched per refine. Max 1 new skill per refine.
A skill should be under 200 lines. Longer means it's doing too much.
Prefer refining an existing skill over creating a new one.
Never edit externally managed skills (plugins,
```
npx skills
```
installs) — they get overwritten on update.
Always check symlink targets before editing — don't follow symlinks into plugin dirs or
```
.agents/skills/
```
.
Don't create skills for one-off tasks that won't recur.
Don't capture things obvious from reading code or CLAUDE.md.
Always ask before editing CLAUDE.md. Only append, never modify existing entries.

每次优化最多处理2个技能，最多新增1个技能。
单个技能内容不得超过200行。过长意味着它承担了过多职责。
优先优化现有技能，而非创建新技能。
切勿编辑外部管理的技能（插件、
```
npx skills
```
安装的技能）——更新时会被覆盖。
编辑前务必检查符号链接目标——不要跟随指向插件目录或
```
.agents/skills/
```
的符号链接。
不为不会重复执行的一次性任务创建技能。
不要记录从代码或CLAUDE.md中可直接获取的明显内容。
编辑CLAUDE.md前务必询问用户。仅可追加内容，切勿修改现有条目。

Output

输出

One-line summary of what you did (or "nothing to refine").

用一句话总结你所做的工作（或“无内容可优化”）。