Purpose: Immediately document verified insights from the work process to build a searchable knowledge base.
Overview
This skill captures insights the moment they are identified and saves them as structured documents based on YAML frontmatter. It uses a single-file-per-category architecture, and each insight is stored in knowledge/[category]/[filename].md.
<critical_sequence name="insight-capture" enforce_order="strict">
7-step process
Auto-detection phrases (recognized in conversation):
- "This turned out well"
- "This approach is good"
- "Let's do it this way next time too"
- "Let's record this"
- "This format worked"
- "This was effective"
- "It worked when I did it this way"
- "I need to remember this"
OR manual: /compound command
Non-trivial only (insights worth reusing):
- Repeatable patterns
- Lessons applicable to other situations
- Methods discovered through trial and error
- Approaches verified in practice
- Findings that led to structural improvements
Skip criteria:
- One-off methods that only work in this situation
- Simple factual records (numbers, dates, etc.)
- Repetition of content already documented
- Hypotheses not yet verified
Extract from conversation history:
Required information:
- domain: work / learning / project / tool / personal
- insight_type: Insight type (see schema.yaml enum)
- component: Subcomponent within the domain (see schema.yaml enum)
- context: What situation the insight came from (1-3 sentences)
- key_learning: One-sentence core lesson (generalizable to other situations)
- impact: critical / high / medium / low
- tags: Search keywords (lowercase, hyphen-separated)
Additional items to collect:
- Background: What project/activity were you doing
- Things tried: Approaches that did not work
- What worked: Methods that actually worked
- Why it worked: Why it was effective
- Reproduction conditions: When this method can be used
BLOCKING requirement: If domain, insight_type, or the core insight is unclear, ask the user and wait for a response:
문서화를 위해 몇 가지 확인이 필요합니다:
1. 어떤 도메인인가요? (work/learning/project/tool/personal)
2. 인사이트 유형은? (예: workflow_pattern, problem_solving, tool_discovery...)
3. 핵심 교훈을 한 문장으로 정리하면?
[응답 후 계속 진행]
knowledge/ Search for similar insights in:
# 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
When a similar document is found Present options to the user and wait:
유사 문서 발견: knowledge/[path]
어떻게 할까요?
1. 새 문서 생성 + 교차 참조 추가 (권장)
2. 기존 문서 업데이트 (동일한 인사이트의 보완인 경우)
3. 기타
선택 (1-3): _
After waiting for the user's response, execute the selected action.
If there is no similar document Proceed directly to Step 4.
Format: YYYYMMDD-[sanitized-insight-slug].md
Sanitization rules:
- Lowercase
- Spaces → hyphens
- Remove special characters (except hyphens)
- Truncate to under 80 characters
Example:
20260304-claude-code-skill-structure.md20260304-mcp-server-debugging-pattern.md20260304-prompt-iteration-framework.md
Validate all required fields based on schema.yaml.
<validation_gate name="yaml-schema" blocking="true">
Validation items:
domain: one of the enum values in schema.yamldate: YYYY-MM-DD formatinsight_type: one of the enum values in schema.yamlcomponent: one of the enum values mapped to that domain (domain_component_mappingcheck)context: 20-300 characters, describe a specific situationkey_learning: 10-200 characters, a generalizable lessonimpact: critical / high / medium / lowtags: 1-8 items, lowercase hyphen-separated
Block Step 6 on validation failure:
YAML 검증 실패
오류:
- domain: 허용된 값이 아님 → work, learning, project, tool, personal 중 하나
- component: domain에 허용되지 않는 컴포넌트 → schema.yaml 참조
- tags: 대문자 포함 → 소문자로 변환 필요
수정된 값을 제공해주세요.
GATE enforcement: Do not proceed to Step 6 until all validations pass.
</validation_gate>
Determine category directory: schema.yaml의 category_mappingmap insight_type → storage path.
Document generation:
INSIGHT_TYPE="[검증된 YAML에서]"
CATEGORY_DIR="[category_mapping에서 매핑]"
FILENAME="[Step 4에서 생성]"
DOC_PATH="${CATEGORY_DIR}${FILENAME}"
# 디렉토리 없으면 생성
mkdir -p "${CATEGORY_DIR}"
# assets/resolution-template.md 기반으로 문서 작성
# (Step 2에서 수집한 컨텍스트 + Step 5에서 검증한 YAML frontmatter)
Result:
- Create a single file in the category directory
- Ensure consistent classification through enum validation
If a similar document was found in Step 3:
# 기존 문서에 Related 섹션 추가
# 새 문서에도 기존 문서 링크 추가
Pattern candidate detection:
If 3 or more similar insights exist in the same category:
패턴 문서 후보 감지: [카테고리]에 유사 인사이트 X개
→ patterns/ 문서로 종합하시겠습니까?
Critical Pattern promotion conditions (no automatic promotion, user decision):
- impact가
criticalif - if it can be applied across multiple domains
- if it must be remembered
In this case, add a note to the "2. Add to critical patterns" option in the Decision Menu:
이 인사이트는 크리티컬 패턴 승격을 고려해볼 만합니다
</critical_sequence>
<decision_gate name="post-documentation" wait_for_user="true">
Decision Menu After Capture
After successful documentation, present options and wait for user response:
인사이트가 기록되었습니다.
파일 생성:
- knowledge/[category]/[filename].md
다음 작업:
1. 계속 진행 (권장)
2. 크리티컬 패턴에 추가 - critical-patterns.md에 승격
3. 관련 문서 연결 - 유사 인사이트와 교차 참조
4. 기존 스킬에 추가 - .claude/skills/에 연결
5. 문서 확인 - 생성된 내용 보기
선택: _
Handling each option:
Option 1: Continue
- Return to the current task/workflow
- Documentation complete
Option 2: Add to critical patterns
If the user selects it:
- A pattern that is applied repeatedly
- A lesson that must never be forgotten
- A non-intuitive but essential rule
Action:
- Extract the pattern from the document
- Structure it in the format of assets/critical-pattern-template.md
knowledge/patterns/critical-patterns.mdAdd to (maintain numbering)- Add a cross-reference to that document
- Confirmation: "Added to critical patterns."
Option 3: Link related documents
- Prompt: "Which document would you like to link? (filename or topic description)"
knowledge/Search for the target document in- Add bidirectional cross-references
- Confirmation: "Cross-reference added"
Option 4: Add to an existing skill
- Prompt: "Which skill would you like to add it to?"
.claude/skills/[skill-name]/Add the link and description to the appropriate file in- Confirmation: "Added to the [skill-name] skill"
Option 5: Review the document
- Display the generated document contents
- Present the Decision Menu again
</decision_gate>
<integration_protocol>
Integration points
Invocation triggers:
/compoundcommand (main interface)- Automatically detect confirmation phrases during conversation
- Manual invocation after workflow completion
Skills/agents that invoke it:
- None (terminal skill - does not delegate to other skills)
Handoff conditions: There must be sufficient context in the conversation history before invocation.
</integration_protocol>
<success_criteria>
Success Criteria
Documentation succeeds when all of the following conditions are met:
- YAML frontmatter validation passes (all required fields, correct format, valid enum values)
knowledge/[category]/[filename].mdfile created in- domain-component mapping matches schema.yaml
- Context, What Worked, Why This Works sections are written concretely
- Cross-references added when similar documents are found
- Decision Menu presented to user and action confirmed
</success_criteria>
Error Handling
Insufficient context:
- Ask user for missing information
- Do not proceed before securing required information
YAML validation failure:
- Display specific error items
- Retry with corrected values
- Block until it passes
Similar insight ambiguity:
- Display all candidates
- User choice: new document / update existing / link separately
Category mapping uncertainty:
- Suggest the closest category
- Proceed after user confirmation
Execution Guidelines
Must do:
- YAML frontmatter validation (Step 5 validation gate is blocking)
- Verify domain-component mapping validity
- Before writing the file,
mkdir -pcreate directory with - If context is missing, ask the user and wait
- Generalize key_learning so it applies to other situations
Must not do:
- Skip YAML validation (validation gate is blocking)
- Document with vague descriptions (unsearchable)
- Document hypotheses or unverified content
- Automatically promote critical patterns (user decision required)
Example Scenario
User: "When making a skill in Claude Code, putting examples in the references/ folder made it follow much more accurately. Let's do it this way next time too."
Skill activation:
- Trigger detection: "Let's do it this way next time too" → automatic activation
- Context collection:
- domain: tool
- insight_type: tool_discovery
- component: claude-code
- context: "When writing Claude Code skills, skill execution accuracy improves greatly when specific example files are placed together in a references/ folder rather than having only SKILL.md"
- key_learning: "When writing AI skills/prompts, providing specific example files together rather than abstract instructions increases execution accuracy"
- impact: high
- tags: [claude-code, skill, references, accuracy, prompt-engineering]
- Existing document search: searching knowledge/tool-discoveries/
- Filename generation:
20260304-skill-references-improve-accuracy.md - YAML validation: passed
- Document writing:
knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md - Cross-reference: none (no similar documents)
Output:
인사이트가 기록되었습니다.
파일 생성:
- knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md
다음 작업:
1. 계속 진행 (권장)
2. 크리티컬 패턴에 추가 - critical-patterns.md에 승격
3. 관련 문서 연결 - 유사 인사이트와 교차 참조
4. 기존 스킬에 추가 - .claude/skills/에 연결
5. 문서 확인 - 생성된 내용 보기