🛠️ 01. 스킬의 이해

Agent/🛠️ Skills/images/skills-01-기초-venn.svg

초보자 기준으로 복잡한 비교 파트는 정리하고, 바로 스킬의 뼈대부터 이해할 수 있게 구성했습니다.

---

🔍 Skill의 구조 이해하기

기본 구성 요소

Skill은 보통 다음 요소로 구성됩니다:

flowchart TD
    A[Skill] --> B[메타데이터<br/>name, description]
    A --> C[구현 로직<br/>어떻게 처리할지]
    A --> D[도구/권한<br/>무엇을 사용할 수 있나]

    B --> B1["이름: para-classifier"]
    B --> B2["설명: PARA 방식 분류"]

    C --> C1["키워드 분석"]
    C --> C2["점수 계산"]
    C --> C3["카테고리 추천"]

    D --> D1["파일 읽기 권한"]
    D --> D2["파일 쓰기 권한"]

    style A fill:#ff9,stroke:#333
    style B fill:#9f9,stroke:#333
    style C fill:#99f,stroke:#333
    style D fill:#f99,stroke:#333

실제 예시: SynStudy의 obsidian-organizer 스킬

{
  "name": "obsidian-organizer",
  "description": "옵시디안 문서 자동 구조화 및 PARA 방식 분류",
  "version": "1.0.0",
  "author": "opencode",
  "type": "obsidian-docs",
  "main": "classify-doc.js",
  "keywords": ["obsidian", "para", "organization", "classification"],
  "supported_actions": ["classify", "reorganize", "validate-structure"]
}

각 필드 설명:

필드	설명	예시
name	스킬의 고유 이름	obsidian-organizer
description	스킬의 간단한 설명	”옵시디안 문서 자동 구조화…”
version	버전 정보	1.0.0
type	스킬의 유형	obsidian-docs
main	구현 파일	classify-doc.js
keywords	검색 키워드	["obsidian", "para"]
supported_actions	지원하는 동작	["classify", "reorganize"]

---

💡 일상 생활에서의 비유

레스토랑 메뉴

메뉴 = Skill의 목록

📋 메뉴 (Skill 목록)
- 스테이크 요리 (스킬)
- 파스타 요리 (스킬)
- 샐러드 준비 (스킬)

주문 = Skill 호출

👤 손님: "스테이크 주세요"
👨‍🍳 요리사: [스테이크 요리 스킬을 실행] 완성!

요리사가 스킬을 알지 못한다면?

👤 손님: "스테이크 주세요"
👨‍🍳 요리사: "어떻게 만드는 건가요? 고기를 어떻게 자르고, 양념은 뭘 쓰고,
             오븐 온도는 몇 도로 맞춰야 하나요? 매번 설명해 주셔야 해요..."

스마트폰 앱

앱 = Skill

📱 설치된 앱들 (Skills)
- 카메라 (사진 찍기 스킬)
- 메시지 (문자 보내기 스킬)
- 지도 (길 찾기 스킬)
- 캘린더 (일정 관리 스킬)

앱 사용 = Skill 호출

👤 사용자: 카메라 앱 열기
📱 카메라: [자동으로 사진 촬영 준비]

앱이 없다면?

👤 사용자: 사진 찍고 싶은데...
📱 스마트폰: "먼저 카메라 하드웨어를 초기화하고,
               렌즈 초점을 맞추고, 셔터 속도를 설정하고...
               매번 다시 설정해야 해요."

---

🎯 Skill의 이점 정리

1. 효율성

Without Skill	With Skill
매번 긴 지시 작성	간단한 명령어
반복되는 설명	한 번의 정의
시간 낭비	시간 절약

2. 일관성

graph LR
    A[첫 번째 요청] -->|긴 지시| B[AI]
    B -->|결과 1| C[출력]

    D[두 번째 요청] -->|다른 지시| B
    B -->|결과 2| E[출력]

    C -.다를 수 있음.-> E

    style C fill:#f99,stroke:#333
    style E fill:#f99,stroke:#333

Skill을 사용하면:

graph LR
    A[첫 번째 요청] -->|동일한 스킬| B[AI]
    B -->|결과 1| C[출력]

    D[두 번째 요청] -->|동일한 스킬| B
    B -->|결과 2| E[출력]

    C -.동일함.-> E

    style C fill:#9f9,stroke:#333
    style E fill:#9f9,stroke:#333

3. 관리 용이성

📂 Skill 폴더
├── obsidian-organizer/
│   └── skill.json (한 곳에서 관리)
├── obsidian-template-manager/
│   └── skill.json (한 곳에서 관리)
└── obsidian-link-validator/
    └── skill.json (한 곳에서 관리)

수정할 때 해당 파일만 수정하면 끝!

4. 협업

👨‍💻 개발자 A: "문서 분류 스킬 만들었어!"
👩‍💻 개발자 B: "좋아! 그거 쓸게"
👨‍💼 PM: "나도 쓸게"

→ 모두가 동일한 표준을 사용

---

🔬 Skill의 작동 방식

전체 워크플로우

sequenceDiagram
    participant U as 사용자
    participant AI as AI 코딩 도구
    participant S as Skill
    participant F as 구현 파일

    U->>AI: "문서 분류해줘"
    AI->>AI: 적절한 Skill 검색
    AI->>S: obsidian-organizer 스킬 로드
    S->>AI: 스킬 정의 전달
    AI->>F: classify-doc.js 실행
    F->>F: 파일 내용 분석
    F->>F: 점수 계산
    F->>F: 카테고리 추천
    F->>AI: 결과 반환
    AI->>U: "Projects 폴더로 이동 추천합니다"

내부 처리 단계

flowchart TD
    A[사용자 요청] --> B{Skill 검색}
    B -->|찾음| C[Skill 로드]
    B -->|못 찾음| D[일반 프롬프트 처리]

    C --> E[구현 파일 실행]
    E --> F[데이터 처리]
    F --> G[결과 생성]
    G --> H[사용자에게 응답]

    D --> I[직접 처리]

    style A fill:#f9f,stroke:#333
    style C fill:#9f9,stroke:#333
    style E fill:#99f,stroke:#333
    style H fill:#9f9,stroke:#333

---

🎯 핵심 요약

Skill이란?

• ✅ AI에게 특정 일을 하는 방법을 정의한 재사용 가능한 설명서
• ✅ 한 번 정의하면 언제든 재사용 가능
• ✅ 일관된 결과 보장

왜 필요한가?

• ✅ 반복되는 지시 피하기
• ✅ 효율성 향상
• ✅ 일관성 보장
• ✅ 관리 용이
• ✅ 협업 지원

구조는 어떻게?

• ✅ 메타데이터 (이름, 설명, 버전 등)
• ✅ 구현 로직 (어떻게 처리할지)
• ✅ 도구/권한 (무엇을 사용할 수 있나)

---

🚀 다음 에피소드에서는?

Skills EP02 - skills.sh 설치 및 실행

• skills.sh 설치와 실행 환경 준비
• 기본 실행 명령과 검증 루틴
• 실무 적용 전 체크포인트 정리

---

💭 생각해볼 질문

1. 여러분의 업무에서 반복적으로 하는 일에는 어떤 것들이 있나요?
2. 그 반복 작업을 Skill로 만들면 어떤 이점이 있을까요?
3. Skill이 없다면 매번 얼마나 많은 지시를 해야 할까요?

다음 에피소드에서는 실제로 Skill을 만들어보겠습니다! 🎉

---

🔗 관련 문서

• Skills-시리즈 - 시리즈 전체 목차
• Skills EP02 - skills.sh 설치 및 실행 - 실습형 설치/검증 루틴