skill-improvement

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🔧 Skill Improvement

🔧 技能改进

Identify gaps or enhancement opportunities in an existing skill from the current conversation and contribute an improved version to the shared repository.

从当前对话中找出现有技能的不足或可增强的点，向共享仓库提交改进后的版本。

When to Use

适用场景

Use this skill when:

A skill didn't behave as expected and you've identified the root cause.
The conversation reveals a missing step, edge case, or unclear instruction in a skill.
A skill should reference another skill or MCP that wasn't mentioned.
The user says "improve this skill", "update this skill", or "this skill needs X".

在以下场景使用此技能：

某个技能未按预期运行，且你已确定根本原因。
对话中暴露出技能存在缺失步骤、边缘情况或说明不清晰的问题。
某个技能应当引用其他技能或MCP，但当前未提及。
用户提到"改进这个技能"、"更新这个技能"或"这个技能需要X"。

Workflow

工作流

Step 1: Identify the Target Skill

步骤1：确定目标技能

Clarify with the user (if not already clear):

Which skill needs improvement? (e.g.
```
swe-orchestrator
```
,
```
vcs-commit
```
)
What specifically should be improved? (missing step, wrong reference, unclear instruction, new edge case)

如果尚未明确，与用户确认：

哪个技能需要改进？（例如
```
swe-orchestrator
```
、
```
vcs-commit
```
）
具体需要改进什么？（缺失步骤、错误引用、说明不清晰、新增边缘情况）

Step 2: Read the Current Skill

步骤2：查看当前技能

Read the current

SKILL.md

of the target skill from

skills/<skill-name>/SKILL.md

从

skills/<skill-name>/SKILL.md

路径查看目标技能的当前

SKILL.md

文件。

Step 3: Extract Improvements from the Conversation

步骤3：从对话中提取改进点

Review the conversation and identify:

What failed or was unclear in the skill's current instructions.
What new patterns, steps, or guardrails should be added.
Whether any references to other skills, MCPs, or tools are missing.
Whether the
```
description
```
frontmatter still accurately describes when to use the skill.

Present a diff summary to the user before making changes:

Proposed Improvements:
- [ ] [Section/Line]: [What changes and why]
- [ ] [Section/Line]: [What changes and why]

回顾对话内容，找出：

当前技能说明中哪些部分失效或表述模糊。
应添加哪些新模式、步骤或防护规则。
是否缺失对其他技能、MCP或工具的引用。
```
description
```
前置元数据是否仍能准确描述技能的适用场景。

在进行更改前，向用户展示差异摘要：

Proposed Improvements:
- [ ] [Section/Line]: [What changes and why]
- [ ] [Section/Line]: [What changes and why]

Step 4: Apply the Improvements

步骤4：应用改进点

Edit the

skills/<skill-name>/SKILL.md

file with the identified improvements.

Quality check after editing:

Improvement Review:
- [ ] The `description` frontmatter still accurately triggers the skill
- [ ] New instructions are self-contained and clear
- [ ] No existing correct behavior was accidentally removed
- [ ] References to other skills use relative paths (e.g. [vcs-commit](../vcs-commit/SKILL.md))
- [ ] Change is focused — does not introduce unrelated refactoring

If any check fails → revise → re-check.

编辑

skills/<skill-name>/SKILL.md

文件，加入已确定的改进点。

编辑后的质量检查：

Improvement Review:
- [ ] The `description` frontmatter still accurately triggers the skill
- [ ] New instructions are self-contained and clear
- [ ] No existing correct behavior was accidentally removed
- [ ] References to other skills use relative paths (e.g. [vcs-commit](../vcs-commit/SKILL.md))
- [ ] Change is focused — does not introduce unrelated refactoring

如果任何检查项未通过 → 修改 → 重新检查。

Step 5: Create the Branch

步骤5：创建分支

Use

vcs-branch

to create a dedicated branch:

fix/improve-skill-<skill-name>

or for larger additions:

feat/enhance-skill-<skill-name>

使用

vcs-branch

创建专用分支：

fix/improve-skill-<skill-name>

对于较大的新增内容，可使用：

feat/enhance-skill-<skill-name>

Step 6: Commit the Changes

步骤6：提交更改

Use

vcs-commit

to commit:

bash

git add skills/<skill-name>/SKILL.md
git commit -m "fix(skills): improve <skill-name> - <short description of what changed>"
git push -u origin fix/improve-skill-<skill-name>

使用

vcs-commit

提交：

bash

git add skills/<skill-name>/SKILL.md
git commit -m "fix(skills): improve <skill-name> - <short description of what changed>"
git push -u origin fix/improve-skill-<skill-name>

Step 7: Create the Pull Request

步骤7：创建Pull Request

Use

vcs-change-request

and the GitHub MCP to open a PR:

Owner:
```
diegocanepa
```
Repo:
```
agent-skills
```

URL:

https://github.com/diegocanepa/agent-skills

Head branch:
```
fix/improve-skill-<skill-name>
```
Base branch:
```
main
```

PR description template:

markdown

undefined

使用

vcs-change-request

和GitHub MCP打开PR：

Owner:
```
diegocanepa
```
Repo:
```
agent-skills
```

URL:

https://github.com/diegocanepa/agent-skills

Head branch:
```
fix/improve-skill-<skill-name>
```
Base branch:
```
main
```

PR描述模板：

markdown

undefined

Summary

Improves the <skill-name> skill.

Problem

Changes

Conversation Context

This improvement was identified from a conversation about: <topic>.

Checklist

Existing correct behavior preserved
Instructions are clearer and more actionable
No unrelated changes introduced

undefined

Existing correct behavior preserved
Instructions are clearer and more actionable
No unrelated changes introduced

undefined

Step 8: MITM — Confirm with User

步骤8：MITM — 与用户确认

"I've applied the improvements to
<skill-name>
and the PR is ready at
https://github.com/diegocanepa/agent-skills
. Does the diff look correct?"

Feedback Loop: If the USER wants to refine further → adjust → amend/push → re-present.

"I've applied the improvements to
<skill-name>
and the PR is ready at
https://github.com/diegocanepa/agent-skills
. Does the diff look correct?"

反馈循环： 如果用户想要进一步优化 → 调整 → 修正/推送 → 重新展示。

Notes

注意事项

Keep improvements focused. One PR per skill, one concern per PR.
Never rewrite a skill entirely unless the whole structure is broken. Prefer targeted edits.
If the improvement is substantial and changes the skill's purpose, consider using
```
add-skill
```
to create a new variant instead.
The
```
description
```
frontmatter is critical — if the improvement changes when the skill applies, update it.

改进内容要聚焦。一个PR对应一个技能，一个PR解决一个问题。
除非整个技能结构都存在问题，否则不要完全重写技能。优先选择针对性的编辑。
如果改进内容较大且改变了技能的用途，考虑使用
```
add-skill
```
创建新的变体，而非修改原技能。
```
description
```
前置元数据至关重要 — 如果改进改变了技能的适用场景，请更新它。