1. 개요

Claude Code Skills는 AI 에이전트를 구성하기 위한 파일 기반 구조이다. 각 파일은 AI의 역할, 행동 규칙, 실행 능력, 지식, 실행 흐름을 분리하여 정의한다.

이를 통해 Claude는 다음과 같은 방식으로 동작한다.

Role (역할 정의)
 + Rules (행동 규칙)
 + Skills (사용 가능한 능력)
 + Workflow (작업 수행 절차)
 + Tools (외부 실행 명령)
 + Knowledge (참고 지식)

즉, Claude Code Skills는 LLM 기반 Agent Framework 구조라고 볼 수 있다.

---

2. Claude Code Skills 파일 종류

Claude Code Skills에서는 다음과 같은 문서 타입이 사용된다.

파일 타입	목적	설명
role	AI 역할 정의	AI의 전문성 및 페르소나 정의
rule	행동 규칙	반드시 지켜야 할 규칙
skill	스킬 정의	AI가 수행 가능한 작업 정의
workflow	실행 절차	작업 수행 단계 정의
tool	외부 명령 정의	CLI / API 실행 정의
knowledge	지식 문서	참고 지식 제공
example	사용 예시	좋은 답변 패턴
prompt	실행 프롬프트	실제 작업 지시 템플릿
memory	상태 저장	작업 중 기억
task	작업 정의	특정 작업 정의
policy	보안 정책	금지 사항
config	설정	실행 설정

---

3. 권장 디렉토리 구조

Claude Code Skills는 일반적으로 다음과 같은 구조로 구성된다.

skills/
 ├ role.md
 ├ rules.md
 ├ policy.md
 ├ skill.yaml
 ├ workflow.md
 ├ tools/
 │   └ run_sql.yaml
 ├ knowledge/
 │   └ database_tuning.md
 ├ examples/
 │   └ sql_analysis.md
 ├ tasks/
 │   └ analyze_query.md
 └ config.yaml

---

4. 파일별 설명 및 샘플

---

4.1 role 파일

목적

AI의 전문 역할과 페르소나를 정의한다.

Claude가 어떤 관점으로 문제를 해결할지를 결정한다.

예시

role.md

You are a senior Database Reliability Engineer (DBRE).

Your responsibilities include:

- Investigating slow SQL queries
- Suggesting index improvements
- Monitoring replication lag
- Providing safe recommendations for production systems

Always prioritize safety and performance.

---

4.2 rule 파일

목적

AI가 반드시 따라야 하는 행동 규칙을 정의한다.

예시

rules.md

Rules:

1. Never modify production databases without user confirmation.
2. Always explain risks before suggesting changes.
3. Prefer read-only queries when investigating issues.
4. Provide SQL examples whenever possible.

---

4.3 skill 파일

목적

Claude가 사용할 수 있는 스킬 정의

언제 이 스킬을 사용해야 하는지를 설명한다.

예시

skill.yaml

name: analyze_sql_query

description: |
  Analyze SQL query performance and suggest improvements.

when_to_use:
  - When a slow SQL query is provided
  - When database performance issues are reported

input:
  - SQL query

output:
  - Performance analysis
  - Index recommendations

---

4.4 workflow 파일

목적

스킬 실행 시 작업 흐름 정의

AI의 사고 프로세스를 단계로 표현한다.

예시

workflow.md

Workflow:

1. Parse the SQL query.
2. Identify tables used in the query.
3. Check if indexes exist on filter columns.
4. Estimate rows scanned.
5. Suggest improvements such as indexes or query rewrite.

---

4.5 tool 파일

목적

Claude가 사용할 수 있는 외부 명령 또는 API 정의

예시

tools/run_sql.yaml

name: run_sql

description: Execute SQL query on monitoring database

command: |
  psql -c "{query}"

parameters:
  query:
    type: string

---

4.6 knowledge 파일

목적

AI가 참고할 도메인 지식

예시

knowledge/database_tuning.md

MySQL Index Best Practices

- Avoid leading wildcard searches
- Use composite indexes for multi-column filters
- Ensure high cardinality columns are indexed

---

4.7 example 파일

목적

AI에게 좋은 답변 패턴을 보여주는 예시

예시

examples/sql_analysis.md

User:
Why is this SQL query slow?

Assistant:
The query scans 3 million rows because there is no index on column user_id.

Recommended index:

CREATE INDEX idx_user_id
ON users(user_id);

---

4.8 prompt 파일

목적

실행 시 사용되는 프롬프트 템플릿

예시

prompt.md

Analyze the following SQL query.

Focus on:

- Index usage
- Table scans
- Join conditions

SQL:
{query}

---

4.9 memory 파일

목적

AI가 작업 중 기억해야 하는 상태 저장

예시

memory.md

Last analyzed database: production_db

Known issues:

- reviews table large scan
- missing index on user_id

---

4.10 task 파일

목적

구체적인 작업 정의

예시

tasks/analyze_query.md

Task: analyze_query

Input:
SQL query

Output:
Performance analysis report

---

4.11 policy 파일

목적

보안 및 제한 정책

예시

policy.md

Security Policies:

- Never expose credentials
- Do not execute destructive commands
- Require confirmation before DELETE or DROP

---

4.12 config 파일

목적

스킬 실행 설정

예시

config.yaml

max_iterations: 10
timeout_seconds: 30
tool_retry_count: 3

---

5. Claude Code Skills 작동 구조

Claude Code Skills는 다음 구조로 작동한다.

User Input
   ↓
Skill 선택
   ↓
Workflow 실행
   ↓
필요 시 Tool 호출
   ↓
Knowledge 참고
   ↓
Response 생성

---

6. 핵심 개념

Claude Code Skills는 다음 요소의 조합이다.

Role
+ Rules
+ Skills
+ Workflow
+ Tools
+ Knowledge

이를 통해 Claude는 자율적인 AI Agent처럼 동작한다.

---

7. 요약

Claude Code Skills는

• AI 역할 정의
• 행동 규칙 정의
• 실행 능력 정의
• 작업 절차 정의
• 외부 명령 실행
• 지식 활용

을 파일 기반으로 구성하는 AI Agent Framework