SuperAPI AI Directory

compound

General & other

View repository

Updated 10-15 16:43

About this skill

compound skill

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.md
  • 20260304-mcp-server-debugging-pattern.md
  • 20260304-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.yaml
  • date: YYYY-MM-DD format
  • insight_type: one of the enum values in schema.yaml
  • component: one of the enum values mapped to that domain (domain_component_mapping check)
  • context: 20-300 characters, describe a specific situation
  • key_learning: 10-200 characters, a generalizable lesson
  • impact: critical / high / medium / low
  • tags: 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:

  1. Extract the pattern from the document
  2. Structure it in the format of assets/critical-pattern-template.md
  3. knowledge/patterns/critical-patterns.mdAdd to (maintain numbering)
  4. Add a cross-reference to that document
  5. 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:

  • /compound command (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:

  1. Trigger detection: "Let's do it this way next time too" → automatic activation
  2. 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]
  3. Existing document search: searching knowledge/tool-discoveries/
  4. Filename generation: 20260304-skill-references-improve-accuracy.md
  5. YAML validation: passed
  6. Document writing: knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md
  7. 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. 문서 확인 - 생성된 내용 보기