본문으로 건너뛰기

Skill 시스템

Skill은 SKILL.md 파일 형태로 존재하는 재사용 가능한 지침 집합입니다. 실행 중에 Agent는 툴을 통해 Skill 콘텐츠를 읽고, 이를 추가 컨텍스트로 대화에 주입할 수 있습니다. Skill을 활용하면 도메인 지식, 워크플로, 모범 사례를 표준화된 재사용 단위로 캡슐화할 수 있습니다.

Skill이란​

Skill은 본질적으로 YAML frontmatter와 Markdown 본문으로 구성된 파일입니다.

---
name: Code Review Standards
description: Unified code review standards and checklist for the project
---

# Code Review Standards

## Required Checks

1. Does the code follow naming conventions?
2. Are there any unused imports?
3. Does the file exceed the line limit?
4. Are there any leftover `console.log` statements?

## Review Template

**File**: `{filename}`
**Issues found**: {N}
**Severity**: High / Medium / Low

| # | Issue | Location | Suggestion |
|---|-------|----------|------------|
| 1 | ... | L42 | ... |

Agent는 list_skills 툴로 사용 가능한 Skill 목록을 확인한 후, read_skill 툴로 특정 Skill의 콘텐츠를 가져와 작업 수행 시 참고합니다.

Skill 탐색 위치​

Skill은 다음 순서로 탐색되고 로드됩니다.

우선순위위치경로출처 태그설명
1워크스페이스.claude/skills/<name>/SKILL.mdworkspace현재 프로젝트 전용
2프로젝트<projectRoot>/.claude/skills/<name>/SKILL.mdproject프로젝트 레벨 공유
3개인~/.claude/skills/<name>/SKILL.mdpersonal사용자 글로벌 사용 가능
4플러그인~/.elftia/plugins/skills/<name>/SKILL.mdplugin커뮤니티에서 설치한 Skill
5내장앱에 번들 포함builtinElftia 사전 설치 Skill

동일한 이름의 Skill이 있을 경우, 우선순위가 높은 것이 적용됩니다.

Skill 툴​

Agent는 두 가지 내장 툴을 통해 Skill 시스템과 상호 작용합니다.

list_skills​

사용 가능한 모든 Skill과 설명을 나열합니다.

파라미터: 없음

출력 예시:

Available skills:
- code-standards (workspace): Project coding standards and best practices
- architecture-index (workspace): Project architecture index and file location guide
- build-optimization (personal): Build optimization standards

read_skill​

지정한 Skill의 전체 콘텐츠를 읽습니다.

파라미터:

파라미터타입필수설명
namestring필수Skill 이름

반환값: Skill 파일의 전체 Markdown 콘텐츠.

SkillHub 커뮤니티 마켓플레이스​

SkillHub는 Skill을 위한 커뮤니티 마켓플레이스로, 다른 사용자가 공유한 Skill을 검색하고 설치할 수 있습니다.

Skill 검색​

Agent는 skillhub_search 툴을 사용하여 커뮤니티 Skill을 검색할 수 있습니다.

Search for skills related to "React best practices"

Skill 설치​

원하는 Skill을 찾은 후, skillhub_install 툴로 로컬에 설치합니다.

Install the skill "react-best-practices" to the personal directory

설치된 Skill은 ~/.elftia/plugins/skills/에 저장되며 모든 프로젝트에서 사용 가능합니다.

Agent에 Skill 연결하기​

Agent에 Skill을 연결하는 방법은 두 가지입니다.

방법 1: Agent 설정에서 선언​

Agent의 frontmatter에 skills 필드를 사용합니다.

---
name: Code Assistant
skills:
  - code-standards
  - architecture-index
---

이 설정을 통해 Agent가 시작될 때 해당 Skill의 콘텐츠가 시스템 프롬프트에 자동으로 주입됩니다.

방법 2: 런타임에 직접 읽기​

실행 중에 Agent가 능동적으로 list_skills와 read_skill을 호출하여 Skill 콘텐츠를 가져올 수 있습니다.

User: Please review this code according to the project standards
Agent: Let me check the available skills first... [calls list_skills]
Agent: Found the code-standards skill, let me read it... [calls read_skill]
Agent: Based on the standards, I found the following issues...

커스텀 Skill 만들기​

단계​

  1. Skill 저장 위치 선택:

    • 프로젝트 전용 → .claude/skills/<name>/SKILL.md
    • 글로벌 사용 가능 → ~/.claude/skills/<name>/SKILL.md

  2. 디렉터리와 파일 생성:

mkdir -p .claude/skills/my-skill
  1. SKILL.md 파일 작성:
---
name: My Skill
description: One-sentence description of the skill's purpose
---

# Skill Title

Detailed skill content...

SKILL.md 형식 참고​

기본 형식​

---
name: Skill name
description: Brief description of the skill
---

Skill body content (Markdown format)

전체 형식 (확장 메타데이터 포함)​

---
name: Skill name
description: Skill description
always: false
allowedTools:
  - Read
  - Grep
  - Glob
metadata:
  always: false
  emoji: "📋"
  os:
    - win32
    - darwin
    - linux
  requires:
    bins:
      - node
      - npm
    env:
      - GITHUB_TOKEN
---

Skill body...

Frontmatter 필드 참고​

필드타입설명
namestringSkill 표시 이름
descriptionstring간략한 설명
alwaysboolean항상 시스템 프롬프트에 주입할지 여부 (기본값: false)
allowedToolsstring[]이 Skill 사용 시 허용할 툴 목록
metadata.alwaysbooleanalways와 동일 (중첩 형식)
metadata.emojistring표시 아이콘
metadata.osstring[]플랫폼 제한 (비어 있으면 모든 플랫폼)
metadata.requires.binsstring[]필요한 CLI 툴
metadata.requires.envstring[]필요한 환경 변수

Always-on Skill​

always: true로 설정된 Skill은 Agent가 시작될 때마다 Agent 설정에 별도 선언 없이 자동으로 시스템 프롬프트에 로드됩니다. 프로젝트 레벨의 기본 표준에 유용합니다.

툴 허용 목록​

allowedTools 필드를 사용하면 해당 Skill을 사용할 때 Agent가 사용할 수 있는 툴 집합을 제한할 수 있습니다. 보안이 중요한 시나리오에서 유용하며, 예를 들어:

allowedTools:
  - Read
  - Grep
  - Glob

이렇게 하면 Agent에서 사용 가능한 툴이 읽기 전용 툴로 제한됩니다.

Skill 작성 모범 사례​

명확한 구조​

---
name: API Design Standards
description: RESTful API design guide and naming conventions
---

# API Design Standards

## Naming Rules
- URLs use kebab-case
- Query parameters use camelCase

## Status Code Usage
- 200: Success
- 201: Created
- 400: Bad request parameters

## Checklist
- [ ] Does the URL conform to RESTful conventions?
- [ ] Is there appropriate error handling?
- [ ] Is pagination supported?

실용적인 팁​

  1. 단일 주제에 집중 — 하나의 Skill은 하나의 문제 범주를 다룹니다
  2. 구체적인 예시 제공 — 코드 스니펫과 템플릿을 포함합니다
  3. 체크리스트 사용 — Agent가 체계적으로 실행하기 쉽게 만듭니다
  4. 범위 명시 — Skill의 전제 조건과 제한 사항을 설명합니다
  5. 간결하게 유지 — 지나치게 긴 Skill 콘텐츠는 컨텍스트 윈도우를 과도하게 소모합니다

자주 묻는 질문​

문제원인해결 방법
Agent가 Skill을 찾을 수 없음Skill 파일이 올바른 경로에 없거나 이름이 맞지 않음list_skills로 사용 가능한 Skill 이름 확인
Skill 콘텐츠가 시스템 프롬프트에 주입되지 않음Agent 설정에 선언되지 않았고 always가 falseskills 필드에 추가하거나 always: true 설정
Skill에 필요한 툴을 사용할 수 없음Agent 툴 허용 목록에 필요한 툴이 포함되지 않음Agent 설정에 필요한 툴 추가
플랫폼 제한으로 Skill을 사용할 수 없음metadata.os가 현재 플랫폼을 제한함os 필드를 수정하거나 현재 플랫폼에 필요한 의존성 설치
Skill 콘텐츠가 너무 길어 성능 저하Skill 콘텐츠가 컨텍스트 윈도우를 과도하게 소모여러 작은 Skill로 분할하고 필요 시 로드
SkillHub 검색 결과 없음검색 키워드가 일치하지 않음다른 키워드를 시도하거나 영어로 검색

관련 링크​