メインコンテンツまでスキップ

스킬

스킬은 반복해서 쓰는 절차나 지식을 SKILL.md 파일로 패키징한 것입니다. AI가 필요할 때 스스로 불러오거나, 사용자가 /스킬이름으로 직접 실행합니다.

스킬이 동작하는 방식​

  1. 대화가 시작될 때 AI는 사용 가능한 스킬의 이름과 설명만 받습니다(본문은 받지 않습니다).
  2. 작업이 어떤 스킬의 설명과 맞으면 AI가 skill 도구로 그 스킬의 본문을 불러와 따릅니다.
  3. 스킬 폴더에 scripts/, references/ 같은 보조 파일이 있으면, 스킬 본문이 안내할 때 AI가 읽습니다. 본문의 상대 경로는 스킬 폴더 기준입니다.
  4. 사용자는 입력창에서 /스킬이름을 골라 직접 실행할 수 있습니다. 슬래시 명령

스킬 로드는 기본적으로 묻지 않고 허용됩니다(skill: allow). 다만 스킬이 안내하는 명령 실행이나 파일 편집에는 일반 권한이 적용됩니다.

스킬 만들기​

폴더 하나에 SKILL.md를 만듭니다.

.opencode/skills/deploy-staging/
├── SKILL.md
└── scripts/
    └── smoke-test.sh
---
name: deploy-staging
description: 스테이징에 배포해야 할 때 사용한다. 빌드, 배포 명령, 스모크 테스트 순서를 안내한다.
---

# 스테이징 배포

1. `pnpm build`로 빌드한다.
2. `pnpm deploy:staging`으로 배포한다.
3. `scripts/smoke-test.sh`를 실행해 결과를 보고한다.
프런트매터설명
name필수. 스킬 이름이며 /이름으로 실행합니다. 이름이 중복되면 나중에 읽힌 스킬이 앞의 것을 덮어쓰고 경고가 기록됩니다.
descriptionAI가 언제 이 스킬을 쓸지 판단하는 근거입니다. 설명이 없으면 AI에게 알려지지 않습니다. 언제 쓰는지를 구체적으로 적으세요.
ヒント

프런트매터가 잘못된 SKILL.md는 오류 없이 건너뛰어질 수 있습니다. 스킬이 목록에 안 보이면 /reload-skills를 실행해 보고, 그래도 없으면 프런트매터를 확인하세요.

스킬을 찾는 위치​

위치범위
프로젝트의 .opencode/skills/(또는 skill/)프로젝트
프로젝트(및 상위 폴더)의 .agents/skills/, .claude/skills/프로젝트
홈의 ~/.agents/skills/, ~/.claude/skills/사용자 전역
~/.config/opencode/skills/사용자 전역(헬피코드가 skills.paths로 고정)
앱 설정 폴더의 opencode/skills/사용자 전역(앱 전용 설정 홈)
  • .claude/skills, .agents/skills에 있는 docx, pptx, xlsx, pdf, docs 이름의 외부 스킬은 무시됩니다. 헬피코드의 문서 도구(document_*)와 충돌하기 때문입니다.
  • 프로젝트·사용자 설정의 skills.paths는 앱이 지정한 값에 덮여 적용되지 않습니다(알려진 제한).
  • 원격 스킬 카탈로그는 skills.urls 설정으로 불러올 수 있습니다.

스킬 목록 새로고침​

스킬을 새로 만들거나 수정했다면 앱을 재시작하지 않고 /reload-skills를 실행합니다. 진행 중인 응답을 중단하지 않고 모든 프로젝트의 스킬을 다시 읽고, 명령 목록도 갱신됩니다. 읽지 못해 건너뛴 파일이 있으면 알려 줍니다.

기본 제공 스킬​

스킬설명
helpy-docsPDF·Word·Excel·PowerPoint 문서를 읽고, 검색하고, 수정하고, 새로 만드는 절차를 안내합니다. 문서 도구가 사용 가능한 환경에서만 제공됩니다. 파일 첨부와 문서 작업
customize-opencode엔진 자체 설정을 바꿀 때 쓰는 내부용 스킬입니다. 기본적으로 거부되고 목록에서 숨겨집니다.

스킬과 서브에이전트·지침의 차이​

언제컨텍스트 비용
지침(AGENTS.md)항상 적용할 규칙매 대화 포함
스킬특정 작업에서만 필요한 절차이름·설명만 상시, 본문은 필요할 때
서브에이전트독립적인 큰 작업 위임별도 컨텍스트에서 실행, 결과만 반환

다음 단계​