peach-skill-feedback

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

peach-skill-feedback — 스킬 개선 피드백 문서화

peach-skill-feedback — 技能改进反馈文档化

⛔ 이 스킬의 책임 범위: 문서 생성까지
할 것: 피드백 문서(
docs/스킬피드백/TODO-*.md
) 생성
하지 말 것: 대상 스킬의 SKILL.md 수정, references/ 파일 변경, 코드 수정
문서를 생성하고 사용자에게 경로를 알려주면 이 스킬의 역할은 끝난다. 실제 스킬 반영은 다른 세션의 다른 AI 에이전트가 문서를 읽고 수행한다.

피치 스킬을 사용하면서 발견한 문제점, 우회 방법, 노하우, 개선 방향을 구조화하여

docs/스킬피드백/

에 날짜별 한글 파일로 저장한다.

다른 AI 에이전트가 이 문서를 읽고 바로 스킬 업데이트 작업을 시작할 수 있도록 문제 분석 + 검증 시나리오 + 구체적 변경 제안까지 포함한다.

⛔ 本Skill的职责范围：仅到文档生成
要做的事：生成反馈文档(
docs/스킬피드백/TODO-*.md
)
禁止做的事：修改目标Skill的SKILL.md、变更references/文件、修改代码
生成文档并告知用户路径后，本Skill的任务即完成。实际的技能更新由其他会话中的AI Agent读取文档后执行。

将使用Peach Skill过程中发现的问题、规避方法、经验、改进方向进行结构化整理，保存到

docs/스킬피드백/

目录下的韩文日期命名文件中。

为让其他AI Agent读取文档后可直接启动技能更新工作，文档需包含问题分析 + 验证场景 + 具体变更建议。

이 스킬의 위치 (워크플로우)

本Skill的工作流位置

피치 스킬 사용 → 문제 발견 →
  /peach-skill-feedback (이 스킬) → docs/스킬피드백/ 문서 생성 →
  다른 에이전트가 문서를 읽고 → skills/{대상스킬}/ 업데이트

使用Peach Skill → 发现问题 →
  /peach-skill-feedback（本Skill）→ 生成docs/스킬피드백/下的文档 →
  其他Agent读取文档 → 更新skills/{目标Skill}/内容

0단계: 환경 감지

0阶段：环境检测

피치 하네스 원본 폴더를 자동 감지한다.

bash

undefined

自动检测Peach Harness原始文件夹。

bash

undefined

OS별 자동 감지

if [ -d "D:/peachSolution2/peach-harness" ]; then HARNESS_ROOT="D:/peachSolution2/peach-harness" elif [ -d "$HOME/source/peachSolution2/peach-harness" ]; then HARNESS_ROOT="$HOME/source/peachSolution2/peach-harness" else echo "❌ 피치 하네스 폴더를 찾을 수 없습니다" echo " Windows: D:\peachSolution2\peach-harness" echo " macOS: ~/source/peachSolution2/peach-harness"

사용자에게 경로 확인

FEEDBACK_DIR="$HARNESS_ROOT/docs/스킬피드백" SKILLS_DIR="$HARNESS_ROOT/skills"

사용자에게 경로 확인

FEEDBACK_DIR="$HARNESS_ROOT/docs/스킬피드백" SKILLS_DIR="$HARNESS_ROOT/skills"

피드백 폴더 생성 (최초 1회)

mkdir -p "$FEEDBACK_DIR"


> **규칙**: 피드백 문서는 반드시 피치 하네스 **원본 폴더**에 저장한다.
> 플러그인 캐시(`~/.claude/plugins/cache/`)에 저장하면 npm 업데이트 시 삭제된다.

---

mkdir -p "$FEEDBACK_DIR"


> **规则**：反馈文档必须保存到Peach Harness**原始文件夹**中。
> 若保存到插件缓存(`~/.claude/plugins/cache/`)，在npm更新时会被删除。

---

1단계: 대상 스킬 식별

1阶段：目标Skill识别

자동 감지

自动检测

현재 대화 맥락에서 사용된 피치 스킬을 파악한다:

```
/peach-e2e-browse
```
→ 대상:
```
peach-e2e-browse
```
```
/peach-gen-backend
```
→ 대상:
```
peach-gen-backend
```
복수 스킬이면 가장 문제가 많았던 스킬을 주 대상으로

从当前对话语境中识别使用过的Peach Skill：

```
/peach-e2e-browse
```
→ 目标：
```
peach-e2e-browse
```
```
/peach-gen-backend
```
→ 目标：
```
peach-gen-backend
```
若涉及多个Skill，以问题最多的Skill为主要目标

수동 지정

手动指定

사용자가 직접 지정하는 경우:

/peach-skill-feedback peach-e2e-browse

用户直接指定的情况：

/peach-skill-feedback peach-e2e-browse

대상 스킬 문서 읽기

读取目标Skill文档

bash

undefined

bash

undefined

SKILL.md 읽기

cat "$SKILLS_DIR/{대상스킬}/SKILL.md"

references/ 목록 확인

ls "$SKILLS_DIR/{대상스킬}/references/" 2>/dev/null

---

ls "$SKILLS_DIR/{대상스킬}/references/" 2>/dev/null

---

2단계: 문제/해결 패턴 수집

2阶段：问题/解决方案模式收集

현재 대화에서 아래 4가지를 추출한다:

从当前对话中提取以下4类内容：

2-1. 발견된 문제

2-1. 发现的问题

수집 항목	예시
시도했지만 실패한 것	Flutter에서 eval click()이 안 먹힘
스킬 문서에 없던 상황	accessibility 재활성화 필요
토큰 낭비가 발생한 지점	screenshot + Read 3회 = 수천 토큰
예상과 다르게 동작한 것	VPN 메뉴 클릭 → 다른 페이지로 튕김

收集项目	示例
尝试但失败的操作	Flutter中eval click()无效
Skill文档未覆盖的场景	需要重新启用accessibility
产生Token浪费的环节	screenshot + Read 3次 = 数千Token
与预期不符的行为	点击VPN菜单 → 跳转到其他页面

2-2. 해결된 방법

2-2. 已解决的方法

수집 항목	예시
성공한 우회 방법	dart.js에서 API method 추출 → fetch 직접 호출
효율적이었던 패턴	eval "body.innerText.substring(0,200)"
새로 발견한 명령/기능	highlight, record, find 명령

收集项目	示例
成功的规避方法	从dart.js提取API method → 直接调用fetch
高效的模式	eval "body.innerText.substring(0,200)"
新发现的命令/功能	highlight、record、find命令

2-3. 기존 스킬과의 차이

2-3. 与现有Skill的差异

대상 스킬의 SKILL.md + references/를 읽고, 현재 대화에서 발견된 것 중 기존 문서에 없는 항목을 식별한다.

读取目标Skill的SKILL.md + references/，识别当前对话中发现的现有文档未包含的内容。

2-4. 심각도 분류

2-4. 严重程度分类

심각도	기준	예시
높음	스킬이 안내하는 방법으로는 작업 불가	Flutter accessibility 활성화 방법 누락
중간	토큰 대량 낭비 또는 시행착오 유발	screenshot + Read 대신 eval 사용 안내 부족
낮음	편의 기능 누락	highlight, record 명령 미문서화

严重程度	标准	示例
高	按照Skill指引的方法无法完成任务	缺失Flutter accessibility启用方法
中	大量浪费Token或导致试错	未引导使用eval替代screenshot + Read
低	缺失便捷功能	未文档化highlight、record命令

3단계: 기존 스킬 문서와 비교 분석

3阶段：与现有Skill文档对比分析

bash

undefined

bash

undefined

SKILL.md에서 의사결정 트리 확인

grep -n "결정|판단|분기|├─|└─" "$SKILLS_DIR/{대상스킬}/SKILL.md"

핵심 규칙 확인

grep -n "규칙|금지|필수|주의" "$SKILLS_DIR/{대상스킬}/SKILL.md"

references/ 문서 목록

ls "$SKILLS_DIR/{대상스킬}/references/"


비교 결과를 아래 형태로 정리:

#	발견된 문제	현재 SKILL.md에 있는가	위치 (행 번호)
1	Flutter accessibility 활성화	X (없음)	—
2	eval click isTrusted 차이	X (없음)	—
3	세션 끊김 복구	X (없음)	—

---

ls "$SKILLS_DIR/{대상스킬}/references/"


对比结果整理为以下格式：

#	发现的问题	当前SKILL.md是否存在	位置（行号）
1	Flutter accessibility启用	X（不存在）	—
2	eval click isTrusted差异	X（不存在）	—
3	会话中断恢复	X（不存在）	—

---

4단계: 산출물 생성

4阶段：产出物生成

파일명 규칙

文件名规则

미반영(처리 대기) 파일은

TODO-

접두어를 붙인다. 반영 완료 시

TODO-

를 제거한다.

undefined

未处理（待处理）文件需添加

TODO-

前缀。处理完成后移除

TODO-

。

undefined

생성 시 (미반영)

生成时（未处理）

docs/스킬피드백/TODO-YYYY-MM-DD-{스킬명}-피드백.md

반영 완료 후

处理完成后

docs/스킬피드백/YYYY-MM-DD-{스킬명}-피드백.md


예시:

docs/스킬피드백/YYYY-MM-DD-{스킬명}-피드백.md


示例：

대기 중

待处理

docs/스킬피드백/TODO-2026-04-15-peach-gen-backend-피드백.md

반영 완료

处理完成

docs/스킬피드백/2026-04-12-peach-e2e-browse-피드백.md


> 폴더를 `ls`로 볼 때 `TODO-` 파일만 눈에 띄어 할 일을 즉시 파악할 수 있다.
> 대부분의 파일은 반영 완료(접두어 없음)이므로 폴더가 깔끔하게 유지된다.

docs/스킬피드백/2026-04-12-peach-e2e-browse-피드백.md


> 使用`ls`查看文件夹时，`TODO-`文件会格外显眼，可立即识别待办事项。
> 大部分文件为处理完成状态（无前缀），因此文件夹可保持整洁。

문서 구조 (필수 섹션)

文档结构（必填章节）

markdown

---
status: pending            # pending → completed
target_skill: peach-{name}
severity: 높음 N / 중간 N / 낮음 N
completed_at:              # 반영 완료 시 날짜 기입
applied_by:                # 반영 완료 시 에이전트명 기입
---

markdown

---
status: pending            # pending → completed
target_skill: peach-{name}
severity: 높음 N / 중간 N / 낮음 N
completed_at:              # 处理完成时填写日期
applied_by:                # 处理完成时填写Agent名称
---

{스킬명} 피드백 — YYYY-MM-DD

대상 스킬: peach-{name} 작성 근거: [어떤 작업을 하다가 발견했는지 한 줄] 심각도 요약: 높음 N건 / 중간 N건 / 낮음 N건

目标Skill：peach-{name} 编写依据：[一行说明在执行什么任务时发现的问题] 严重程度汇总：高 N件 / 中 N件 / 低 N件

1. 발견된 문제

1. 发现的问题

#	문제	심각도	현재 스킬에 있는가	SKILL.md 행

#	问题	严重程度	当前Skill是否存在	SKILL.md行号

2. 해결 방법 / 우회 전략

2. 解决方法 / 规避策略

(문제 번호별 대응. 실제 실행한 명령 + 결과 포함)

（按问题编号对应说明，包含实际执行的命令 + 结果）

문제 #1: {제목}

问题 #1：{标题}

원인: ... 해결: ...

bash

undefined

原因：... 解决：...

bash

undefined

실제 실행한 명령

实际执行的命令

undefined

undefined

3. 스킬 업데이트 제안

3. Skill更新建议

3-1. SKILL.md 변경

3-1. SKILL.md变更

(구체적 행 범위 + 추가/수정할 내용을 마크다운으로 제시)

（具体行范围 + 用Markdown展示需添加/修改的内容）

3-2. references/ 추가/수정

3-2. references/添加/修改

(새 레퍼런스 파일명 + 핵심 내용 요약)

（新参考文件名 + 核心内容摘要）

3-3. agent-browser-명령어.md 등 기존 레퍼런스 보완

3-3. 补充agent-browser-명령어.md等现有参考文档

(추가할 명령어/패턴)

（需添加的命令/模式）

4. 검증 시나리오

4. 验证场景

(다른 AI 에이전트가 이 문서만으로 재현할 수 있는 단계별 명령)

（其他AI Agent仅通过此文档即可重现的分步命令）

시나리오 {번호}: {제목}

场景 {编号}：{标题}

목적: ... 전제: ...

bash

undefined

目的：... 前提：...

bash

undefined

단계 1: ...

步骤1：...

단계 2: ...

步骤2：...

**기대 결과**: ...
**통과 기준**: ...

**预期结果**：...
**通过标准**：...

5. 다음 에이전트를 위한 작업 지시

5. 给后续Agent的工作指示

이 문서를 읽은 AI 에이전트는 아래 순서로 작업한다:

피치 하네스 원본 폴더 확인

Windows:
```
D:\peachSolution2\peach-harness\
```
macOS:
```
~/source/peachSolution2/peach-harness/
```

대상 스킬 현재 상태 확인
```
cat skills/{대상스킬}/SKILL.md
```
이 문서의 "3. 스킬 업데이트 제안"을 순서대로 반영
- SKILL.md 수정
- references/ 파일 추가/수정
검증 시나리오(4장) 실행하여 변경 사항 확인

변경 완료 후:

frontmatter의
```
status
```
를
```
completed
```
로 변경,
```
completed_at
```
과
```
applied_by
```
기입
파일명에서
```
TODO-
```
접두어 제거 (
```
git mv
```
로 rename)
하단에 반영 기록 추가:

markdown

## 반영 기록
- [날짜] {에이전트}: SKILL.md 행 XX~YY 수정, references/XX.md 추가

---

读取此文档的AI Agent需按以下顺序执行任务：

确认Peach Harness原始文件夹

Windows:
```
D:\peachSolution2\peach-harness\
```
macOS:
```
~/source/peachSolution2/peach-harness/
```

确认目标Skill当前状态
```
cat skills/{대상스킬}/SKILL.md
```
依次落实此文档的「3. Skill更新建议」
- 修改SKILL.md
- 添加/修改references/文件
执行验证场景（第4章）确认变更内容
变更完成后：
- 将frontmatter的
```
status
```
  改为
```
completed
```
  ，填写
```
completed_at
```
  和
```
applied_by
```
- 移除文件名中的
```
TODO-
```
  前缀（使用
```
git mv
```
  重命名）
- 在文档底部添加更新记录：
markdown
```
## 更新记录
- [日期] {Agent}：修改SKILL.md第XX~YY行，添加references/XX.md
```

---

5단계: 저장 및 안내

5阶段：保存及通知

저장

保存

bash

undefined

bash

undefined

피드백 문서 저장 (TODO- 접두어 포함)

保存反馈文档（包含TODO-前缀）

FEEDBACK_FILE="$FEEDBACK_DIR/TODO-YYYY-MM-DD-{스킬명}-피드백.md"

Write tool로 저장

使用Write工具保存

undefined

undefined

사용자 안내

通知用户

📄 피드백 문서 생성 완료

경로: docs/스킬피드백/YYYY-MM-DD-{스킬명}-피드백.md
문제: N건 (높음 X / 중간 Y / 낮음 Z)
검증 시나리오: N개

다음 에이전트가 이 문서를 읽고 스킬을 업데이트할 수 있습니다.
반영하려면: /peach-skill-feedback 문서를 참고하여 skills/{대상스킬}/ 수정

📄 反馈文档生成完成

路径：docs/스킬피드백/YYYY-MM-DD-{스킬명}-피드백.md
问题：N件（高X / 中Y / 低Z）
验证场景：N个

后续Agent可读取此文档并更新技能。
如需落实：参考/peach-skill-feedback文档修改skills/{대상스킬}/内容

⛔ 이 스킬의 작업은 여기서 끝난다

⛔ 本Skill的工作到此结束

문서를 저장하고 사용자에게 경로를 안내한 뒤 더 이상 어떤 파일도 수정하지 않는다. 스킬 반영(SKILL.md 수정, references/ 추가)은 이 문서를 읽은 다른 AI 에이전트가 수행한다.

保存文档并告知用户路径后，禁止修改任何文件。 Skill更新（修改SKILL.md、添加references/）需由读取此文档的其他AI Agent执行。

핵심 규칙

核心规则

피치 하네스 원본 폴더에만 저장 — 캐시 폴더 금지
파일명은 한글 + 날짜 —
```
YYYY-MM-DD-{스킬명}-피드백.md
```
실제 명령 포함 — 추상적 설명 금지, 실행 가능한 명령어로
검증 시나리오 필수 — 다른 에이전트가 재현할 수 있어야 함
다음 에이전트 작업 지시 필수 — 문서를 읽고 바로 작업 가능해야 함
기존 문서 비교 필수 — SKILL.md 행 번호까지 명시
스킬 파일 절대 수정 금지 — SKILL.md, references/, 기타 스킬 파일을 직접 Edit/Write 금지. 문서(TODO-*.md)를 생성하고 사용자에게 보고하면 이 스킬의 작업은 완료된다. 스킬 반영은 반드시 다른 세션의 에이전트가 피드백 문서를 읽고 수행한다.
작업 종료 기준 —
```
docs/스킬피드백/TODO-*.md
```
파일을 Write tool로 저장한 순간 작업 완료. 그 이후 어떠한 파일도 수정하지 않는다.

仅保存到Peach Harness原始文件夹 — 禁止保存到缓存文件夹
文件名采用韩文+日期 —
```
YYYY-MM-DD-{스킬명}-피드백.md
```
包含实际命令 — 禁止抽象描述，需使用可执行的命令
必须包含验证场景 — 需让其他Agent可重现
必须包含后续Agent工作指示 — 需让读取文档的Agent可直接开始工作
必须与现有文档对比 — 需明确SKILL.md的行号
绝对禁止修改Skill文件 — 禁止直接编辑/写入SKILL.md、references/及其他Skill文件。生成文档(TODO-*.md)并向用户报告后，本Skill的工作即完成。 Skill更新必须由其他会话的Agent读取反馈文档后执行。
工作结束标准 — 使用Write工具保存
```
docs/스킬피드백/TODO-*.md
```
文件的瞬间，工作完成。此后禁止修改任何文件。

사용 예시

使用示例

bash

undefined

bash

undefined

e2e-browse 스킬 사용 후 문제 발견

使用e2e-browse Skill后发现问题

/peach-skill-feedback peach-e2e-browse

gen-backend 스킬 피드백

gen-backend Skill反馈

/peach-skill-feedback peach-gen-backend

스킬명 생략 시 대화 맥락에서 자동 감지

省略Skill名称时，从对话语境自动检测

/peach-skill-feedback

undefined

/peach-skill-feedback

undefined