스킬 작동 방식
스킬은 컨텍스트를 가볍게 유지하기 위해 점진적 로딩을 사용합니다. 프로젝트를 열면 Agent는 모든 스킬의 이름과 설명만 확인합니다 — 각각 수십 단어 정도입니다. 시작 시 로드되는 것은 이것뿐입니다. 요청이 스킬의 설명과 일치하면 Agent가 해당 스킬을 활성화하고 전체 지시문을 로드합니다. 단편 소설 창작 스킬은 쿼리 레터를 쓰는 동안 휴면 상태를 유지하고, 공포 소설 스킬은 스릴러 아웃라인을 작성할 때 컨텍스트를 소비하지 않습니다.| 레벨 | 로드 시점 | 내용 |
|---|---|---|
| 메타데이터 | 항상, 시작 시 | 프론트매터의 이름과 설명 |
| 지시문 | 스킬이 활성화될 때 | SKILL.md 전체 본문 |
| 지원 파일 | 필요에 따라 | 템플릿, 스크립트, 참고 문서 |
스킬 구조와 저장 위치
각 스킬은SKILL.md 파일을 포함하는 디렉토리입니다. 디렉토리 이름이 스킬 이름이 됩니다. 스킬에는 세 가지 선택적 서브디렉토리에 지원 파일을 포함할 수 있습니다.
.soloent/skills/ 에 저장됩니다. 이 로맨스 시리즈의 특정 규칙을 기반으로 구축된 스킬이나 현재 작품의 수위와 서술 방식에 맞춰 조정된 스킬 등 특정 프로젝트나 장르에 묶인 기능에 사용하세요.
스킬 토글
각 스킬에는 파일을 삭제하지 않고 활성화 또는 비활성화할 수 있는 토글이 있습니다. 현재 작업에 필요하지 않은 스킬은 비활성화하면 컨텍스트에서 제외되어 의도치 않은 활성화를 방지합니다.스킬 만들기
SKILL.md 파일은 프론트매터 블록(메타데이터)과 지시문 본문 두 부분으로 구성됩니다.
name은 디렉토리 이름과 정확히 일치해야 합니다description은 Agent에게 이 스킬을 언제 트리거할지 알려줍니다. 무엇을 할 수 있는지가 아닙니다 (1,024자 이내)

새 스킬 만들기
“New skill…”을 클릭하고 이름 (예:
short-story)을 입력한 다음 ”+“를 클릭합니다. Agent가 템플릿 SKILL.md 파일이 포함된 스킬 디렉토리를 생성합니다.english-short-story 스킬 전체 내용 — 클릭하여 펼치고 복사
english-short-story 스킬 전체 내용 — 클릭하여 펼치고 복사
세 가지 일반적인 스킬 유형
유형 1: 체크리스트형
고정된 시점에서 여러 기준을 한 번에 검증하는 데 최적 — 누락을 방지합니다. 예를 들어 각 챕터 완성 후 제출 전 체크:유형 2: 워크플로우형
명확한 단계 순서가 있고 실행 전 확인이 필요한 작업에 최적.유형 3: 도메인 전문가형
Agent가 감으로 추측하지 않고 전문가 경험으로 작업하게 하고 싶을 때 최적. 예를 들어 글쓰기가 막혔을 때의 진단 스킬:완전한 예시: 도서 요약
이것은 도메인 전문가형 스킬입니다. 콘텐츠 검색 경로(스크립트가 챕터를 온디맨드로 추출), 전문 지식(docs/에 챕터 인식 패턴), 고정 출력 형식(templates/에 노트 템플릿) — 이 세 가지 요소가 도메인 전문가형 스킬의 전형적인 구조입니다.
이 스킬은 로컬 도서 파일에서 구조화된 독서 노트를 추출합니다 — 챕터 요약, 핵심 인사이트, 인용구 — 포맷된 Markdown으로 저장합니다.
디렉토리 구조
왜 스크립트가 필요한가
도서는 깁니다. 챕터 구조를 추출하기 위해 전체 소설을 컨텍스트에 로드하는 것은 낭비이고 느립니다. 전처리 스크립트가 이 문제를 해결합니다:info명령 — 처음 50줄을 읽어 제목, 인코딩, 총 줄 수 파악chapters명령 — 전문을 읽지 않고 챕터 제목을 스캔하여 줄 번호 반환extract명령 — 특정 챕터의 줄만 읽어 Agent가 한 챕터씩 처리할 수 있게 함
왜 docs 파일이 필요한가
중국어와 영어 도서는 챕터 제목 형식이 크게 다릅니다. 모든 인식 패턴을SKILL.md에 내장하는 대신 스킬은 docs/chapter-patterns.md에 저장합니다. Agent는 챕터 경계를 식별해야 할 때 이 참고 파일을 읽고, 그 외에는 무시합니다.
참고 자료를 docs/에 두면 두 가지 장점이 있습니다: SKILL.md를 워크플로우 로직에 집중시킬 수 있고, 메인 지시문을 수정하지 않고 패턴을 업데이트할 수 있습니다.
왜 템플릿이 필요한가
출력 형식은 고정되어 있습니다: 모든 독서 노트는 동일한 구조를 따릅니다 — 도서 개요, 챕터별 요약(핵심 관점과 인용구 포함), 전체 도서 하이라이트, 개인 소감. 매번 프롬프트에서 형식을 재지정하는 대신 스킬은templates/note-template.md에 저장합니다.
5단계(최종 정리)가 실행되면 Agent는 템플릿을 로드하고 플레이스홀더를 채웁니다. 형식은 매번 일관되며 한 곳에서만 관리하면 됩니다.
SKILL.md가 지원 파일을 참조하는 방법
SKILL.md의 지시문은 각 지원 파일을 명시적으로 가리킵니다:
효과적인 스킬 작성하기
”언제 사용하는가”를 쓰고, “무엇을 하는가”를 쓰지 마세요
비슷하게 들리지만 트리거 정확도에 큰 영향을 미칩니다.완전한 단계, 입력, 출력, 중단 조건을 갖추세요
프로세스의 시작만 작성하고 명확한 완료 신호가 없는 경우, Agent는 언제 멈출지 스스로 결정합니다 — 보통 원하는 곳이 아닙니다. 각 단계에는 다음이 필요합니다:- 입력: 이 단계에 필요한 컨텍스트나 파일
- 출력: 이 단계가 생성하는 것
- 중단 조건: 확인을 기다리는 시점, 계속 진행하는 시점
본문은 핵심만 유지하고 대용량 자료는 지원 파일로
SKILL.md는 5,000단어 이내로 유지하세요. 스타일 가이드, 인식 패턴, 캐릭터 프로필 등 대용량 참고 자료가 필요한 경우 docs/ 서브디렉토리에 넣고 파일 이름으로 참조하세요. Agent는 필요할 때만 로드하고 그 외에는 컨텍스트를 소비하지 않습니다.
호출 빈도에 따라 자동 트리거 결정
| 사용 빈도 | 권장 전략 |
|---|---|
| 고빈도 (세션당 1회 이상) | 자동 트리거 유지; 더 정확한 활성화를 위해 설명 최적화 |
| 저빈도 (세션당 1회 이하) | 자동 트리거 비활성화; 수동 호출; 설명은 컨텍스트 밖에 있어도 됨 |
| 매우 저빈도 (월 1회 미만) | 스킬 제거; SOLOENT.md에 문서로 기록 |
자주 빠지는 함정
| 문제 | 증상 | 수정 방법 |
|---|---|---|
| 설명이 너무 광범위 | description: help with writing — 모든 글쓰기 요청이 트리거됨 | 구체적인 시나리오로 좁히고 실제 트리거 문구 포함 |
| 본문이 너무 길음 | 수백 줄의 작업 매뉴얼을 SKILL.md 본문에 전부 넣음 | 참고 자료를 docs/로 이동; 지시문에는 골격만 유지 |
| 하나의 스킬이 다섯 가지 일 | 같은 스킬이 검토, 속편, 개요, 캐릭터 설계, 진단을 다 커버 | 분리하기; 도메인당 스킬 하나씩, 각각 독립적으로 온/오프 가능 |
다른 사람의 스킬 사용하기
모든 스킬을 처음부터 작성할 필요는 없습니다. 스킬은 자기 완결적 디렉토리입니다 — 수동으로 설치하거나, 리포지토리에서 클론하거나, 플러그인으로 설치할 수 있습니다.수동 설치
스킬 디렉토리를 다운로드하거나 복사하여 적절한 위치에 배치합니다:- 전역 스킬 → 시스템 수준의 스킬 디렉토리 (모든 프로젝트에서 사용 가능)
- 워크스페이스 스킬 → 프로젝트 내의
.soloent/skills/
git clone으로 설치
GitHub에서 공개된 스킬은 스킬 디렉토리에 직접 클론할 수 있습니다:git pull로 리포지토리의 변경 사항을 가져올 수 있습니다.
플러그인으로 설치
일부 스킬 작성자는 스킬을 패키지된.vsix 확장 파일로 배포합니다. 확장을 설치하면 번들된 스킬이 자동으로 로드됩니다 — 수동으로 파일을 배치할 필요가 없습니다.
문제 해결
스킬이 예상대로 활성화되지 않을 때
스킬이 예상대로 활성화되지 않을 때
가장 가능한 원인: 설명이 충분히 구체적이지 않거나, 스킬이 꺼져 있습니다.
- Skills 패널에서 스킬이 켜져 있는지 확인
description을 다시 작성하여 실제로 사용하는 문구와 작업 유형을 포함 — “글쓰기 돕기”는 거의 올바르게 트리거되지 않음; 워크플로우, 출력 유형, 샘플 호출 문구를 구체적으로 명시- 스킬 디렉토리에 유효한
SKILL.md가 있고name과description프론트매터 필드가 모두 포함되어 있는지 확인 - 프론트매터의
name이 디렉토리 이름과 정확히 일치하는지 확인
원하지 않을 때 스킬이 계속 활성화될 때
원하지 않을 때 스킬이 계속 활성화될 때
설명이 너무 광범위합니다 — 의도하지 않은 요청과도 매칭됩니다.
description을 이 스킬이 처리하는 특정 작업만 설명하도록 좁히기- 해당 도메인 외의 작업을 할 때는 스킬 끄기
- 설명이 겹치는 스킬이 여러 개 있다면 각각 언제 활성화되어야 하는지 더 구체적으로 만들기
스킬 지시문이 무시되거나 일부만 실행될 때
스킬 지시문이 무시되거나 일부만 실행될 때
다음 일반적인 문제를 확인하세요:
- 지시문이 컨텍스트 한도를 초과했을 수 있음 —
SKILL.md를 5,000단어 이내로 유지하고 참고 자료는docs/서브디렉토리로 이동 - 충돌하는 전역 또는 프로젝트 규칙이 스킬 동작의 일부를 재정의할 수 있음 — 활성 규칙에 모순이 없는지 확인
- 스킬이 체크리스트를 사용하는 경우 각 항목에 명시적인 “확인 대기” 게이트가 있는지 확인; 없으면 Agent가 자동으로 진행할 수 있음
- 지시문에서 참조된 지원 파일은 지정된 경로에 존재해야 함 — 파일이 없으면 해당 단계가 조용히 건너뜀
지원 파일(템플릿, docs, 스크립트)이 로드되지 않을 때
지원 파일(템플릿, docs, 스크립트)이 로드되지 않을 때
Agent는 지시문에서 명시적으로 참조될 때만 지원 파일을 로드합니다.
- 지시문의 파일 경로가 실제 위치와 일치하는지 확인 (예:
chapter-outline.md가 아닌templates/chapter-outline.md) - 파일이 스킬 디렉토리 내의 올바른 서브디렉토리 (
templates/,docs/, 또는scripts/)에 있는지 확인 SKILL.md에서 파일 이름이 참조되지 않으면 Agent가 로드할 이유가 없음
워크스페이스 스킬과 전역 스킬이 같은 이름으로 충돌할 때
워크스페이스 스킬과 전역 스킬이 같은 이름으로 충돌할 때
워크스페이스 스킬은 항상 같은 이름의 전역 스킬보다 우선합니다.
- 이것은 예상된 동작입니다 — 워크스페이스 스킬이 활성화되어 있으면 같은 이름의 전역 스킬은 완전히 무시됨
- 전역 스킬을 적용하려면 워크스페이스 스킬의 이름을 변경하거나 삭제하세요
- 둘 다 공존해야 한다면 서로 다른 이름을 지정하고 각각의 설명을 업데이트하세요
더 많은 고급 팁
워크플로우 (Workflows)
워크플로우 파일로 반복적인 다단계 프로세스를 자동화하세요
규칙 (Rules)
글쓰기 선호도를 규칙에 담아 Agent가 항상 당신의 스타일로 쓰게 하세요
규칙 · 워크플로우 · 스킬 비교
세 가지 AI 지시 방법 — 차이점과 각각의 사용 시점을 이해하세요