스킬 시스템
SKILL.md/SKILL.toml 스킬을 작성하고, MCP 메타 툴을 통해 실행하며, 오픈 스킬 라이브러리를 동기화합니다.
스킬은 Revka를 재컴파일하지 않고도 에이전트의 기능을 확장하는, 재사용 가능한 사용자 정의 또는 커뮤니티 제작 기능입니다. 스킬은 마크다운 지시 사항, 선택적 툴 정의(셸 커맨드 또는 HTTP 호출), 그리고 메타데이터를 디스크의 단일 디렉토리에 묶어 놓은 단위입니다. Revka는 시작 시 스킬을 탐색하여 에이전트의 컨텍스트에 주입하고, 모든 스킬을 개별 툴로 등록하는 대신 세 가지 간결한 메타 툴을 통해 외부 MCP 클라이언트에 노출합니다.
이 페이지에서는 디스크 기반 스킬 모델의 구조, MCP를 통한 스킬 실행 방법, 커뮤니티 오픈 스킬 라이브러리 동기화, 그리고 자율적 스킬 생성 및 개선 설정 방법을 설명합니다. 커맨드 라인에서 스킬을 설치, 감사, 테스트하는 방법은 revka 스킬, 워크플로 & SOP를 참고하세요. HTTP를 통한 스킬 관리는 에이전트, 스킬 & 팀 API 페이지를 참고하세요.
스킬 동작 방식
섹션 제목: “스킬 동작 방식”스킬은 워크스페이스 내의 고유한 디렉토리에 위치합니다:
~/.revka/workspace/skills/ release-notes/ SKILL.toml # 또는 SKILL.md — 매니페스트 (필수) PROMPT.md # 선택적 외부 프롬프트 콘텐츠 TEST.sh # 선택적 검증 케이스 (CLI 페이지 참고)Revka는 시작 시 <workspace>/skills/ (그리고 활성화된 경우 오픈 스킬 디렉토리)를 스캔하여 루트에 SKILL.md 또는 SKILL.toml 매니페스트가 있는 모든 디렉토리를 로드합니다. 로드된 각 스킬은 실행 중인 에이전트에 다음 두 가지를 제공합니다:
- 프롬프트 콘텐츠 — 마크다운 본문 또는
prompts배열로, 에이전트가 스킬을 언제, 어떻게 사용할지 알 수 있도록 주입됩니다. - 툴 —
[[tools]]항목이 있는 경우,<skill_name>.<tool_name>(점으로 구분) 형식으로 에이전트에 노출됩니다. 예를 들어,release-notes스킬의list_merged툴은release-notes.list_merged가 됩니다.
스킬 작성
섹션 제목: “스킬 작성”매니페스트는 두 가지 형식 중 하나로 작성할 수 있습니다.
SKILL.toml
섹션 제목: “SKILL.toml”[skill] 테이블과 선택적 [[tools]] 배열을 포함하는 구조화된 매니페스트입니다:
[skill]name = "release-notes"description = "Summarize merged PRs into release notes."version = "1.0.0" # defaults to "0.1.0" if omittedtags = ["git", "writing"] # optionalcontent_file = "PROMPT.md" # optional: external markdown used as prompt content
# Optional embedded prompt content (ignored when content_file is set)prompts = [ "You write concise, accurate release notes.",]
[[tools]]name = "list_merged"description = "List merged PRs since a tag."kind = "shell" # "shell" | "script" | "http"command = "gh pr list --state merged --search 'merged:>{{since}}'"
# args is a string→string map of named template parameters[tools.args]since = "v1.0.0"| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
skill.name | string | — (필수) | 고유한 스킬 이름 |
skill.description | string | — (필수) | 사람이 읽을 수 있는 목적 설명 |
skill.version | string | "0.1.0" | 시맨틱 버전 |
skill.author | string | — | 선택적 작성자 레이블 |
skill.tags | string[] | [] | 분류 태그 |
skill.content_file | string | — | 프롬프트 콘텐츠로 사용할 마크다운 파일 경로(매니페스트 기준 상대 경로). 설정 시 내장 prompts 배열은 무시됩니다 |
prompts | string[] | [] | 에이전트에 주입되는 내장 프롬프트 콘텐츠 |
tools[] | table[] | [] | 툴 정의 (아래 참고) |
SKILL.md
섹션 제목: “SKILL.md”메타데이터를 위한 YAML 프론트 매터와 프롬프트 콘텐츠로 사용되는 본문으로 구성된 마크다운 파일입니다. 지시 전용(“마크다운 전용”) 스킬에 적합하며, 툴이 필요한 경우 [[tools]] 스타일 섹션을 추가할 수 있습니다:
---name: code-review-checklistdescription: A reusable checklist for reviewing pull requests.version: 1.0.0tags: [review, quality]---
When reviewing a pull request, walk through this checklist:
1. Does every changed line trace to the stated intent?2. Are error paths and edge cases covered by tests?3. Are there secrets, credentials, or PII in the diff?마크다운 전용 스킬은 툴이 없으며, 본문에 담긴 지시 사항이 전부입니다. 에이전트는 이 지시 사항을 읽고 따릅니다.
툴 종류
섹션 제목: “툴 종류”각 [[tools]] 항목에는 kind를 선언합니다:
kind | 동작 | 제한 |
|---|---|---|
"shell" / "script" | sh -c를 통해 셸 커맨드를 실행하며, {{arg_name}} 템플릿 치환을 지원합니다 | 60초 타임아웃, 1 MB 출력 제한, 샌드박스 환경에서 실행(안전 변수만 허용) |
"http" | URL 템플릿에 대해 GET 요청을 수행합니다 | 30초 타임아웃, 1 MB 응답 제한, http:// 및 https:// URL만 허용 |
| 필드 | 타입 | 설명 |
|---|---|---|
name | string | 툴 이름. 에이전트에 <skill_name>.<tool_name> 형식으로 노출됩니다 |
description | string | 툴의 기능 설명 |
kind | string | "shell", "script", 또는 "http" |
command | string | 실행할 셸 커맨드, 스크립트, 또는 URL. {{arg_name}} 치환을 지원합니다 |
args | map | 선택적 string→string 형식의 명명된 템플릿 파라미터 맵 |
MCP 메타 툴을 통한 스킬 실행
섹션 제목: “MCP 메타 툴을 통한 스킬 실행”모든 스킬을 별도의 MCP 툴로 노출하면 클라이언트의 툴 목록이 방대해집니다. 워크스페이스에는 50개 이상의 스킬이 있을 수 있기 때문입니다. 대신 Revka의 MCP 서버는 세 가지 간결한 메타 툴을 등록하여, 외부 클라이언트(Claude Desktop, Claude Code, Codex 등)가 모든 스킬을 탐색하고 실행할 수 있도록 합니다. 이 툴들은 extended 툴 레지스트리에 등록됩니다.
skills_list
섹션 제목: “skills_list”파라미터 없이 가시적인 모든 스킬을 나열합니다.
// tools/call → skills_list{}스킬 요약 정보의 JSON 배열을 반환합니다:
[ { "id": "release-notes", "name": "release-notes", "description": "Summarize merged PRs into release notes.", "version": "1.0.0", "tags": ["git", "writing"], "tool_count": 1, "location": "workspace" }]skills_describe
섹션 제목: “skills_describe”단일 스킬의 전체 본문과 메타데이터(툴 배열 포함)를 반환합니다.
// tools/call → skills_describe{ "skill_id": "release-notes" }skills_execute
섹션 제목: “skills_execute”스킬의 하위 툴을 실행하거나, 마크다운 전용 스킬의 경우 본문을 반환합니다.
// tools/call → skills_execute{ "skill_id": "release-notes", "tool": "list_merged", // optional; defaults to the first [[tools]] entry "arguments": { "since": "v2.0.0" }}tool을 생략하면 스킬의 첫 번째[[tools]]항목이 실행됩니다.- 마크다운 전용 스킬의 경우,
skills_execute는 마크다운 본문을 그대로 반환하여 호출하는 LLM이 지시 사항을 직접 따를 수 있도록 합니다.
read_skill 툴
섹션 제목: “read_skill 툴”에이전트가 compact 프롬프트 모드(prompt_injection_mode = "compact")로 실행될 때, 스킬 본문은 시스템 프롬프트에 미리 주입되지 않고 스킬 이름만 표시됩니다. 내장 read_skill 툴은 이름으로 단일 스킬의 소스 파일을 필요 시 로드합니다:
| 파라미터 | 타입 | 설명 |
|---|---|---|
name | string (필수) | <available_skills>에 나열된 정확한 스킬 이름 |
// tool call → read_skill{ "name": "release-notes" }전체 파일 콘텐츠(마크다운 또는 TOML)를 반환합니다. 이를 통해 저컨텍스트 모델에서 시스템 프롬프트를 작게 유지하면서도, 에이전트가 필요할 때 스킬의 전체 지시 사항을 가져올 수 있습니다.
오픈 스킬
섹션 제목: “오픈 스킬”오픈 스킬은 besoeasy/open-skills GitHub 저장소에서 동기화되는 선택적 커뮤니티 라이브러리입니다. 활성화하면 Revka가 7일 간격으로 저장소를 로컬 디렉토리에 동기화하고, 해당 스킬을 워크스페이스 스킬과 함께 에이전트의 가시적 스킬 세트에 병합합니다.
[skills]open_skills_enabled = trueopen_skills_dir = "~/.revka/open-skills" # optional overrideallow_scripts = false # keep scripts blocked[skills] 설정
섹션 제목: “[skills] 설정”~/.revka/config.toml의 [skills] 섹션은 스킬 로딩, 커뮤니티 라이브러리, 자율적 생성/개선 동작을 제어합니다. 모든 키는 환경 변수 오버라이드를 지원합니다.
[skills]open_skills_enabled = false # opt-in community libraryopen_skills_dir = "~/open-skills"prompt_injection_mode = "full" # "full" (inline) or "compact" (on-demand)allow_scripts = false # allow script files in skills
[skills.skill_creation]enabled = false # auto-create skills from successful tasksmax_skills = 500 # LRU eviction limitsimilarity_threshold = 0.85 # dedup threshold
[skills.skill_improvement]enabled = true # auto-improve skills after successful usecooldown_secs = 3600 # min interval between improvements per skill| 키 | 기본값 | 환경 변수 오버라이드 | 설명 |
|---|---|---|---|
open_skills_enabled | false | REVKA_OPEN_SKILLS_ENABLED | 오픈 스킬 커뮤니티 라이브러리 활성화 |
open_skills_dir | ~/open-skills | REVKA_OPEN_SKILLS_DIR | 동기화된 오픈 스킬의 로컬 경로 |
prompt_injection_mode | "full" | REVKA_SKILLS_PROMPT_MODE | full(인라인) 또는 compact(read_skill을 통한 온디맨드) |
allow_scripts | false | REVKA_SKILLS_ALLOW_SCRIPTS | 스킬 내 .sh/.ps1/shebang 셸 파일 허용 여부 |
skill_creation.enabled | false | — | 성공한 다단계 작업에서 스킬 자동 생성 |
skill_creation.max_skills | 500 | — | 자동 생성 스킬의 최대 수. 초과 시 가장 오래된 항목이 LRU 방식으로 제거됩니다 |
skill_creation.similarity_threshold | 0.85 | — | 이 임베딩 유사도 이상이면 중복으로 간주하여 새 스킬 생성을 건너뜁니다 |
skill_improvement.enabled | true | — | 스킬이 성공적으로 사용된 후 자동 개선 |
skill_improvement.cooldown_secs | 3600 | — | 동일 스킬에 대한 개선 최소 간격 |
스킬 생성 및 개선
섹션 제목: “스킬 생성 및 개선”skill_creation.enabled = true로 설정하면, Revka는 성공한 다단계 작업 이후 새 스킬을 자율적으로 생성하여 절차를 재사용 가능하도록 캡처합니다. 새 스킬은 임베딩 유사도(similarity_threshold, 기본값 0.85)를 기준으로 기존 스킬과 중복 여부를 검사하며, max_skills(기본값 500) 한도 내에서 LRU 방식으로 가장 오래된 자동 생성 스킬을 제거합니다.
skill_improvement.enabled = true(기본값)로 설정하면, Revka는 스킬이 성공적으로 사용된 후 기존 스킬을 개선하여 지시 사항을 지속적으로 다듬습니다. cooldown_secs(기본값 3600)는 단일 스킬이 지정된 간격 이상으로 재작성되지 않도록 방지합니다.
두 동작 모두 기본값을 유지해도 안전합니다: 개선은 활성화, 생성은 비활성화.
스킬 관리 (운영자)
섹션 제목: “스킬 관리 (운영자)”디스크 기반 스킬 외에도, Operator MCP는 Kumiho 그래프 메모리에 버전 관리되는 스킬 저장소를 유지합니다. Operator 스킬은 <memory_project>/Skills/ 아래에 SKILL.md 아티팩트로 저장되며 효과성 점수를 보유하므로, 시스템 프롬프트 빌더가 최근 성공 가중치 기반으로 스킬 순위를 재조정할 수 있습니다. Operator는 다음 MCP 툴을 노출합니다:
| 툴 | 목적 |
|---|---|
capture_skill | 스킬을 Kumiho 리비전 아티팩트로 캡처하거나 업데이트합니다 |
list_skills | Kumiho에서 스킬을 나열합니다 (선택적으로 레거시 디스크 스킬 포함) |
load_skill | 이름 또는 kref로 스킬의 SKILL.md 콘텐츠를 로드합니다 (태그 기본값: "published") |
get_skill_effectiveness | 기록된 결과 기반의 롤링 성공률 |
record_skill_outcome | 스킬 사용 성공 또는 실패를 기록합니다 |
search_clawhub | ClawHub 마켓플레이스를 검색합니다 |
install_from_clawhub | 슬러그로 커뮤니티 스킬을 설치합니다 |
browse_clawhub | ClawHub의 인기 스킬 목록을 조회합니다 |
"published" 태그는 스킬의 현재 활성 버전을 나타냅니다. 스킬 효과성 점수 산출(record_skill_outcome → get_skill_effectiveness)은 프롬프트 구성에 피드백되어 성능이 우수한 스킬이 우선적으로 표시됩니다.
ClawHub 마켓플레이스
섹션 제목: “ClawHub 마켓플레이스”ClawHub는 커뮤니티 스킬을 탐색하고 설치하는 스킬 마켓플레이스입니다. 익명으로 탐색 및 설치가 가능하며, 토큰은 게시 시에만 필요합니다.
[clawhub]enabled = trueapi_url = "https://clawhub.ai"api_token = "clh_..." # only needed for publishing대시보드는 Skills 뷰 아래에 ClawHub를 표시하며, 게이트웨이 엔드포인트 GET /api/clawhub/search, GET /api/clawhub/trending, GET /api/clawhub/skills/{slug}, POST /api/clawhub/install/{slug}를 통해 제공됩니다. 스킬, 툴 & 통합 대시보드 페이지를 참고하세요.
HTTP를 통한 스킬 관리
섹션 제목: “HTTP를 통한 스킬 관리”Revka 대시보드의 스킬 UI는 /api/skills 게이트웨이 엔드포인트(모두 bearer 인증 필요)를 통해 제공됩니다. 스킬은 <memory_project>/Skills Kumiho 공간에 "skill" 종류의 아이템으로 저장되며, 콘텐츠는 ~/.revka/workspace/skills/<slug>.md를 가리키는 SKILL.md 아티팩트에 보관됩니다.
| 메서드 + 경로 | 목적 |
|---|---|
GET /api/skills | 스킬 목록 조회. 쿼리 파라미터: include_deprecated, q (전문 검색), page, per_page (최대 50) |
GET /api/skills/:kref | 전체 콘텐츠를 포함한 단일 스킬 조회 |
POST /api/skills | 스킬 생성. 요청 본문 { name, description, content, domain, tags? } → 201 응답 { skill } |
PUT /api/skills/:kref | 스킬 업데이트 (새 리비전 생성) |
POST /api/skills/deprecate | 스킬 활성화/비활성화. 요청 본문 { kref, deprecated: bool } |
DELETE /api/skills/:kref | 스킬 영구 삭제 |
:kref는 kref:// 이후의 경로입니다. 예: CognitiveMemory/Skills/my-skill.skill. 응답은 30초 인프로세스 캐시에서 제공되며, 쓰기 작업 시 캐시가 무효화됩니다. 전체 요청 및 응답 형식은 에이전트, 스킬 & 팀 API 페이지에 문서화되어 있습니다.