Back to Details

compound

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

compound 스킬

Compound Skill

목적: 작업 과정에서 검증된 인사이트를 즉시 문서화하여, 검색 가능한 지식 베이스를 구축한다.
目的： 将工作过程中经过验证的洞见即时文档化，构建可检索的知识库。

개요

概述

이 스킬은 인사이트가 확인되는 즉시 포착하여, YAML frontmatter 기반의 구조화된 문서로 저장한다. 카테고리별 단일 파일 아키텍처를 사용하며, 각 인사이트는 
knowledge/[category]/[filename].md
에 저장된다.
<critical_sequence name="insight-capture" enforce_order="strict">
本技能会在洞见被确认的瞬间进行捕获，并以YAML frontmatter为基础保存为结构化文档。采用按类别划分的单一文件架构，每条洞见都会存储在
knowledge/[category]/[filename].md
路径下。
<critical_sequence name="insight-capture" enforce_order="strict">

7단계 프로세스

7步流程

<step number="1" required="true">
<step number="1" required="true">

Step 1: 트리거 감지

步骤1：触发检测

자동 감지 문구 (대화에서 인식):
  • "이거 잘 됐다"
  • "이 방식이 좋네"
  • "다음에도 이렇게 하자"
  • "이건 기록해두자"
  • "이 포맷이 먹혔다"
  • "이게 효과가 있었어"
  • "이렇게 하니까 됐어"
  • "기억해둬야 해"
OR 수동: 
/compound
커맨드
Non-trivial만 (재사용 가치 있는 인사이트):
  • 반복할 수 있는 패턴
  • 다른 상황에도 적용 가능한 교훈
  • 시행착오 끝에 발견한 방법
  • 실전에서 검증된 접근법
  • 구조적 개선을 가져온 발견
스킵 기준:
  • 이 상황에서만 통하는 일회성 방법
  • 단순 사실 기록 (수치, 날짜 등)
  • 이미 문서화된 내용의 반복
  • 아직 검증되지 않은 가설 </step>
<step number="2" required="true" depends_on="1">
自动检测话术（从对话中识别）：
  • "这个效果不错"
  • "这种方式很好"
  • "下次也这么做"
  • "这个要记下来"
  • "这个格式可行"
  • "这个有效果"
  • "这么做就成了"
  • "必须记住"
或手动触发： 
/compound
命令
仅捕获具备复用价值的洞见：
  • 可重复的模式
  • 适用于其他场景的经验教训
  • 历经试错后发现的方法
  • 经过实战验证的思路
  • 带来结构性优化的发现
跳过标准：
  • 仅适用于当前场景的一次性方法
  • 单纯的事实记录（数值、日期等）
  • 已文档化内容的重复
  • 尚未验证的假设 </step>
<step number="2" required="true" depends_on="1">

Step 2: 컨텍스트 수집

步骤2：上下文收集

대화 이력에서 추출:
필수 정보:
  • domain: work / learning / project / tool / personal
  • insight_type: 인사이트 유형 (schema.yaml enum 참조)
  • component: 도메인 내 하위 컴포넌트 (schema.yaml enum 참조)
  • context: 어떤 상황에서 나온 인사이트인가 (1-3문장)
  • key_learning: 핵심 교훈 한 문장 (다른 상황에도 일반화 가능하게)
  • impact: critical / high / medium / low
  • tags: 검색 키워드 (소문자, 하이픈 구분)
추가 수집 항목:
  • 배경: 어떤 프로젝트/활동 중이었는가
  • 시도한 것들: 효과 없었던 접근들
  • 효과 있었던 것: 실제로 작동한 방법
  • 작동 이유: 왜 효과적이었는가
  • 재현 조건: 언제 이 방법을 쓸 수 있는가
BLOCKING 요건: domain, insight_type, 핵심 인사이트가 불분명한 경우 사용자에게 질문하고 응답을 기다린다:
문서화를 위해 몇 가지 확인이 필요합니다:

1. 어떤 도메인인가요? (work/learning/project/tool/personal)
2. 인사이트 유형은? (예: workflow_pattern, problem_solving, tool_discovery...)
3. 핵심 교훈을 한 문장으로 정리하면?

[응답 후 계속 진행]
</step> <step number="3" required="false" depends_on="2">
从对话历史中提取：
必填信息：
  • domain: work / learning / project / tool / personal
  • insight_type: 洞见类型（参考schema.yaml枚举值）
  • component: 领域内的子组件（参考schema.yaml枚举值）
  • context: 洞见产生的场景（1-3句话）
  • key_learning: 核心经验总结（一句话，需具备场景普适性）
  • impact: critical / high / medium / low
  • tags: 搜索关键词（小写，连字符分隔）
额外收集项：
  • 背景：当时正在进行的项目/活动
  • 尝试过的方法：无效的思路
  • 有效的方法：实际可行的方案
  • 有效原因：为何该方案能起作用
  • 复用条件：何时可以使用该方法
阻塞要求： 若domain、insight_type或核心洞见不明确，需向用户询问并等待回复：
为了完成文档化，需要确认以下信息：

1. 所属领域？（work/learning/project/tool/personal）
2. 洞见类型？（例如：workflow_pattern, problem_solving, tool_discovery...）
3. 请用一句话总结核心经验？

[回复后继续推进]
</step> <step number="3" required="false" depends_on="2">

Step 3: 기존 문서 검색

步骤3：现有文档检索

knowledge/
에서 유사 인사이트 검색:
bash
undefined
在
knowledge/
目录下检索相似洞见：
bash
undefined

domain, tags, insight_type 기준으로 병렬 검색

基于domain、tags、insight_type进行并行检索

Grep: pattern="domain: [domain]" path=knowledge/ output_mode=files_with_matches Grep: pattern="tags:.*[keyword]" path=knowledge/ output_mode=files_with_matches -i=true Grep: pattern="insight_type: [type]" path=knowledge/ output_mode=files_with_matches

**유사 문서 발견 시** 사용자에게 선택지 제시 후 대기:
유사 문서 발견: knowledge/[path]
어떻게 할까요?
  1. 새 문서 생성 + 교차 참조 추가 (권장)
  2. 기존 문서 업데이트 (동일한 인사이트의 보완인 경우)
  3. 기타
선택 (1-3): _

사용자 응답 대기 후 선택한 액션 실행.

**유사 문서 없으면** Step 4로 바로 진행.
</step>

<step number="4" required="true" depends_on="2">
Grep: pattern="domain: [domain]" path=knowledge/ output_mode=files_with_matches Grep: pattern="tags:.*[keyword]" path=knowledge/ output_mode=files_with_matches -i=true Grep: pattern="insight_type: [type]" path=knowledge/ output_mode=files_with_matches

**发现相似文档时**，向用户提供选项并等待回复：
发现相似文档：knowledge/[path]
请选择处理方式：
  1. 创建新文档 + 添加交叉引用（推荐）
  2. 更新现有文档（适用于补充同一洞见的情况）
  3. 其他
选择（1-3）：_

等待用户回复后执行所选操作。

**未发现相似文档则**直接进入步骤4。
</step>

<step number="4" required="true" depends_on="2">

Step 4: 파일명 생성

步骤4：文件名生成

형식: 
YYYYMMDD-[sanitized-insight-slug].md
Sanitization 규칙:
  • 소문자
  • 공백 → 하이픈
  • 특수문자 제거 (하이픈 제외)
  • 80자 미만으로 truncate
예시:
  • 20260304-claude-code-skill-structure.md
  • 20260304-mcp-server-debugging-pattern.md
  • 20260304-prompt-iteration-framework.md
    </step>
<step number="5" required="true" depends_on="4" blocking="true">
格式：
YYYYMMDD-[sanitized-insight-slug].md
命名规则：
  • 全部小写
  • 空格替换为连字符
  • 移除特殊字符（连字符除外）
  • 长度截断至80字符以内
示例：
  • 20260304-claude-code-skill-structure.md
  • 20260304-mcp-server-debugging-pattern.md
  • 20260304-prompt-iteration-framework.md
    </step>
<step number="5" required="true" depends_on="4" blocking="true">

Step 5: YAML 검증 (BLOCKING)

步骤5：YAML验证（阻塞）

schema.yaml 기반으로 모든 필수 필드 검증.
<validation_gate name="yaml-schema" blocking="true">
검증 항목:
  • domain
    : schema.yaml의 enum 값 중 하나
  • date
    : YYYY-MM-DD 형식
  • insight_type
    : schema.yaml의 enum 값 중 하나
  • component
    : 해당 domain에 매핑된 enum 값 중 하나 (
    domain_component_mapping
    확인)
  • context
    : 20-300자, 구체적 상황 서술
  • key_learning
    : 10-200자, 일반화 가능한 교훈
  • impact
    : critical / high / medium / low
  • tags
    : 1-8개, 소문자 하이픈 구분
검증 실패 시 Step 6 차단:
YAML 검증 실패

오류:
- domain: 허용된 값이 아님 → work, learning, project, tool, personal 중 하나
- component: domain에 허용되지 않는 컴포넌트 → schema.yaml 참조
- tags: 대문자 포함 → 소문자로 변환 필요

수정된 값을 제공해주세요.
GATE 강제: 모든 검증 통과 전까지 Step 6 진행 금지.
</validation_gate> </step>
<step number="6" required="true" depends_on="5">
基于schema.yaml验证所有必填字段。
<validation_gate name="yaml-schema" blocking="true">
验证项：
  • domain
    : 必须是schema.yaml枚举值之一
  • date
    : 格式为YYYY-MM-DD
  • insight_type
    : 必须是schema.yaml枚举值之一
  • component
    : 必须是对应domain下的枚举值之一（参考
    domain_component_mapping
    ）
  • context
    : 20-300字符，需描述具体场景
  • key_learning
    : 10-200字符，需具备普适性
  • impact
    : critical / high / medium / low
  • tags
    : 1-8个，小写连字符分隔
验证失败则阻止进入步骤6：
YAML验证失败

错误信息：
- domain: 不属于允许值 → 请选择work, learning, project, tool, personal中的一项
- component: 该domain不允许此组件 → 参考schema.yaml
- tags: 包含大写字母 → 需要转换为小写

请提供修正后的信息。
强制校验： 未通过所有验证前，禁止进入步骤6。
</validation_gate> </step>
<step number="6" required="true" depends_on="5">

Step 6: 문서 작성

步骤6：文档撰写

카테고리 디렉토리 결정: schema.yaml의 
category_mapping
으로 insight_type → 저장 경로 매핑.
문서 생성:
bash
INSIGHT_TYPE="[검증된 YAML에서]"
CATEGORY_DIR="[category_mapping에서 매핑]"
FILENAME="[Step 4에서 생성]"
DOC_PATH="${CATEGORY_DIR}${FILENAME}"
确定类别目录： 通过schema.yaml中的
category_mapping
将insight_type映射到存储路径。
文档生成：
bash
INSIGHT_TYPE="[已验证的YAML中获取]"
CATEGORY_DIR="[通过category_mapping映射得到]"
FILENAME="[步骤4生成的文件名]"
DOC_PATH="${CATEGORY_DIR}${FILENAME}"

디렉토리 없으면 생성

目录不存在则创建

mkdir -p "${CATEGORY_DIR}"
mkdir -p "${CATEGORY_DIR}"

assets/resolution-template.md 기반으로 문서 작성

基于assets/resolution-template.md生成文档

(Step 2에서 수집한 컨텍스트 + Step 5에서 검증한 YAML frontmatter)

（包含步骤2收集的上下文 + 步骤5验证通过的YAML frontmatter）


**결과:**

- 카테고리 디렉토리에 단일 파일 생성
- Enum 검증으로 일관된 분류 보장
</step>

<step number="7" required="false" depends_on="6">

**结果：**

- 在对应类别目录下生成单个文件
- 通过枚举值校验确保分类一致性
</step>

<step number="7" required="false" depends_on="6">

Step 7: 교차 참조 & 패턴 감지

步骤7：交叉引用 & 模式识别

Step 3에서 유사 문서 발견된 경우:
bash
undefined
若步骤3中发现相似文档：
bash
undefined

기존 문서에 Related 섹션 추가

在现有文档中添加Related章节

새 문서에도 기존 문서 링크 추가

在新文档中添加指向现有文档的链接


**패턴 후보 감지:**

동일 카테고리에 유사 인사이트 3개 이상 존재하면:
패턴 문서 후보 감지: [카테고리]에 유사 인사이트 X개 → patterns/ 문서로 종합하시겠습니까?

**Critical Pattern 승격 조건 (자동 승격 금지, 사용자 결정):**

- impact가 `critical`인 경우
- 여러 도메인에 횡단 적용 가능한 경우
- 반드시 기억해야 하는 경우

이 경우 Decision Menu에서 "2. 크리티컬 패턴에 추가" 옵션에 주석 추가:
이 인사이트는 크리티컬 패턴 승격을 고려해볼 만합니다

</step>

</critical_sequence>

---

<decision_gate name="post-documentation" wait_for_user="true">

**模式候选识别：**

当同一类别下存在3个及以上相似洞见时：
检测到模式文档候选：[类别]下存在X条相似洞见 → 是否要将其整合到patterns/目录下的文档中？

**关键模式升级条件（禁止自动升级，需用户决策）：**

- impact为`critical`时
- 可跨多个领域适用时
- 必须牢记的内容

此时在决策菜单的“2. 添加到关键模式”选项后添加注释：
该洞见具备升级为关键模式的价值，建议考虑

</step>

</critical_sequence>

---

<decision_gate name="post-documentation" wait_for_user="true">

Decision Menu After Capture

捕获完成后的决策菜单

문서화 성공 후 선택지 제시 및 사용자 응답 대기:
인사이트가 기록되었습니다.

파일 생성:
- knowledge/[category]/[filename].md

다음 작업:
1. 계속 진행 (권장)
2. 크리티컬 패턴에 추가 - critical-patterns.md에 승격
3. 관련 문서 연결 - 유사 인사이트와 교차 참조
4. 기존 스킬에 추가 - .claude/skills/에 연결
5. 문서 확인 - 생성된 내용 보기

선택: _
각 옵션 처리:
Option 1: 계속 진행
  • 현재 작업/워크플로우로 복귀
  • 문서화 완료
Option 2: 크리티컬 패턴에 추가
사용자가 선택하는 경우:
  • 반복 적용되는 패턴
  • 절대 잊어서는 안 되는 교훈
  • 비직관적이지만 필수적인 규칙
액션:
  1. 문서에서 패턴 추출
  2. assets/critical-pattern-template.md 형식으로 구조화
  3. knowledge/patterns/critical-patterns.md
    에 추가 (순번 유지)
  4. 해당 문서에 교차 참조 추가
  5. 확인: "크리티컬 패턴에 추가되었습니다."
Option 3: 관련 문서 연결
  • 프롬프트: "어떤 문서와 연결할까요? (파일명 또는 주제 설명)"
  • knowledge/
    에서 대상 문서 검색
  • 양방향 교차 참조 추가
  • 확인: "교차 참조가 추가되었습니다"
Option 4: 기존 스킬에 추가
  • 프롬프트: "어떤 스킬에 추가할까요?"
  • .claude/skills/[skill-name]/
    의 적절한 파일에 링크와 설명 추가
  • 확인: "[skill-name] 스킬에 추가되었습니다"
Option 5: 문서 확인
  • 생성된 문서 내용 표시
  • Decision Menu 다시 제시
</decision_gate>
<integration_protocol>
文档化成功后，向用户提供选项并等待回复：
洞见已记录完成。

生成文件：
- knowledge/[category]/[filename].md

后续操作：
1. 继续当前工作（推荐）
2. 添加到关键模式 - 升级至critical-patterns.md
3. 关联相关文档 - 与相似洞见添加交叉引用
4. 添加到现有Skill - 关联至.claude/skills/目录
5. 查看文档 - 查看生成的内容

选择：_
各选项处理逻辑：
选项1：继续当前工作
  • 返回当前工作/工作流
  • 文档化流程完成
选项2：添加到关键模式
用户选择后适用于：
  • 可重复应用的模式
  • 绝对不能忘记的经验
  • 反直觉但必须遵守的规则
操作：
  1. 从文档中提取模式
  2. 按照assets/critical-pattern-template.md格式结构化
  3. 添加到
    knowledge/patterns/critical-patterns.md
    （保持编号顺序）
  4. 在对应文档中添加交叉引用
  5. 确认提示：“已添加到关键模式。”
选项3：关联相关文档
  • 提示：“要关联哪些文档？（文件名或主题描述）”
  • 在
    knowledge/
    目录下检索目标文档
  • 添加双向交叉引用
  • 确认提示：“已添加交叉引用”
选项4：添加到现有Skill
  • 提示：“要添加到哪个Skill？”
  • 在
    .claude/skills/[skill-name]/
    目录下的对应文件中添加链接和说明
  • 确认提示：“已添加到[skill-name] Skill”
选项5：查看文档
  • 展示生成的文档内容
  • 重新展示决策菜单
</decision_gate>
<integration_protocol>

통합 지점

集成要点

호출 트리거:
  • /compound
    커맨드 (주 인터페이스)
  • 대화 중 확인 문구 자동 감지
  • 워크플로우 완료 후 수동 호출
호출하는 스킬/에이전트:
  • 없음 (terminal 스킬 - 다른 스킬에 위임하지 않음)
Handoff 조건: 호출 전 대화 이력에 충분한 컨텍스트가 있어야 함.
</integration_protocol>
<success_criteria>
调用触发方式：
  • /compound
    命令（主交互方式）
  • 对话中自动识别确认话术
  • 工作流完成后手动调用
调用的Skill/Agent：
  • 无（终端Skill - 不委托给其他Skill）
移交条件： 调用前对话历史需包含足够的上下文信息。
</integration_protocol>
<success_criteria>

성공 기준

成功标准

다음 모든 조건이 충족될 때 문서화 성공:
  • YAML frontmatter 검증 통과 (모든 필수 필드, 올바른 형식, 유효한 enum 값)
  • knowledge/[category]/[filename].md
    에 파일 생성됨
  • domain-component 매핑이 schema.yaml과 일치
  • Context, What Worked, Why This Works 섹션이 구체적으로 작성됨
  • 유사 문서 발견 시 교차 참조 추가됨
  • 사용자에게 Decision Menu 제시 및 액션 확인됨
</success_criteria>
满足以下所有条件时，判定文档化成功：
  • YAML frontmatter验证通过（所有必填字段、格式正确、枚举值有效）
  • 文件已生成在
    knowledge/[category]/[filename].md
    路径下
  • domain-component映射与schema.yaml一致
  • Context、有效方法、有效原因章节内容具体
  • 发现相似文档时已添加交叉引用
  • 已向用户展示决策菜单并确认操作
</success_criteria>

에러 처리

错误处理

컨텍스트 부족:
  • 사용자에게 누락된 정보 질문
  • 필수 정보 확보 전 진행 금지
YAML 검증 실패:
  • 구체적인 오류 항목 표시
  • 수정된 값으로 재시도
  • 통과할 때까지 차단
유사 인사이트 모호함:
  • 여러 후보 모두 표시
  • 사용자 선택: 새 문서 / 기존 업데이트 / 별도 연결
카테고리 매핑 불확실:
  • 가장 근접한 카테고리 제안
  • 사용자 확인 후 진행
上下文不足：
  • 向用户询问缺失的信息
  • 未获取必填信息前禁止推进
YAML验证失败：
  • 展示具体错误项
  • 使用修正后的信息重试
  • 未通过前持续阻塞
相似洞见模糊：
  • 展示所有候选文档
  • 由用户选择：新建文档/更新现有文档/单独关联
类别映射不明确：
  • 推荐最接近的类别
  • 经用户确认后推进

실행 가이드라인

执行指南

반드시 해야 하는 것:
  • YAML frontmatter 검증 (Step 5 validation gate는 blocking)
  • domain-component 매핑 유효성 확인
  • 파일 작성 전 
    mkdir -p
    로 디렉토리 생성
  • 컨텍스트 누락 시 사용자에게 묻고 대기
  • key_learning은 다른 상황에도 적용 가능하게 일반화
절대 하지 말아야 하는 것:
  • YAML 검증 건너뛰기 (validation gate는 blocking)
  • 모호한 설명으로 문서화 (검색 불가)
  • 가설이나 미검증 내용 문서화
  • critical pattern 자동 승격 (사용자 결정 필요)
必须执行的操作：
  • 进行YAML frontmatter验证（步骤5的验证门为阻塞型）
  • 验证domain-component映射的有效性
  • 生成文件前用
    mkdir -p
    创建目录
  • 上下文缺失时向用户询问并等待回复
  • key_learning需具备场景普适性
绝对禁止的操作：
  • 跳过YAML验证（验证门为阻塞型）
  • 用模糊描述进行文档化（会导致无法检索）
  • 文档化未验证的假设
  • 自动升级关键模式（需用户决策）

예시 시나리오

示例场景

사용자: "Claude Code에서 스킬 만들 때 references/ 폴더에 예시를 넣었더니 훨씬 정확하게 따라하더라. 다음에도 이렇게 하자."
스킬 활성화:
  1. 트리거 감지: "다음에도 이렇게 하자" → 자동 활성화
  2. 컨텍스트 수집:
    • domain: tool
    • insight_type: tool_discovery
    • component: claude-code
    • context: "Claude Code 스킬 작성 시 SKILL.md만 두는 것보다 references/ 폴더에 구체적 예시 파일을 함께 두었을 때 스킬 실행 정확도가 크게 향상됨"
    • key_learning: "AI 스킬/프롬프트 작성 시 추상적 지시보다 구체적 예시 파일을 함께 제공하면 실행 정확도가 높아진다"
    • impact: high
    • tags: [claude-code, skill, references, accuracy, prompt-engineering]
  3. 기존 문서 검색: knowledge/tool-discoveries/ 검색
  4. 파일명 생성: 
    20260304-skill-references-improve-accuracy.md
  5. YAML 검증: 통과
  6. 문서 작성: 
    knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md
  7. 교차 참조: 없음 (유사 문서 없음)
출력:
인사이트가 기록되었습니다.

파일 생성:
- knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md

다음 작업:
1. 계속 진행 (권장)
2. 크리티컬 패턴에 추가 - critical-patterns.md에 승격
3. 관련 문서 연결 - 유사 인사이트와 교차 참조
4. 기존 스킬에 추가 - .claude/skills/에 연결
5. 문서 확인 - 생성된 내용 보기
用户： “在Claude Code中创建Skill时，把示例文件放到references/目录下，执行准确率大幅提升。下次就这么做。”
Skill激活流程：
  1. 触发检测： 识别到“下次就这么做” → 自动激活
  2. 上下文收集：
    • domain: tool
    • insight_type: tool_discovery
    • component: claude-code
    • context: “在创建Claude Code Skill时，相比仅保留SKILL.md，同时在references/目录下放置具体示例文件能大幅提升Skill执行准确率”
    • key_learning: “在创建AI Skill/提示词时，提供具体示例文件比抽象指令更能提升执行准确率”
    • impact: high
    • tags: [claude-code, skill, references, accuracy, prompt-engineering]
  3. 现有文档检索： 在knowledge/tool-discoveries/目录下检索无结果
  4. 文件名生成： 
    20260304-skill-references-improve-accuracy.md
  5. YAML验证： 通过
  6. 文档撰写： 生成文件
    knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md
  7. 交叉引用： 无（未发现相似文档）
输出：
洞见已记录完成。

生成文件：
- knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md

后续操作：
1. 继续当前工作（推荐）
2. 添加到关键模式 - 升级至critical-patterns.md
3. 关联相关文档 - 与相似洞见添加交叉引用
4. 添加到现有Skill - 关联至.claude/skills/目录
5. 查看文档 - 查看生成的内容