에이전트 스킬

에이전트 스킬을 통해 OpenCode는 저장소나 홈 디렉토리에서 재사용 가능한 지침을 발견할 수 있습니다. 스킬은 네이티브 skill 도구를 통해 필요할 때 로드됩니다 - 에이전트는 사용 가능한 스킬을 보고 필요할 때 전체 내용을 로드할 수 있습니다.

파일 배치

스킬 이름당 하나의 폴더를 만들고 그 안에 SKILL.md를 넣으세요. OpenCode는 다음 위치를 검색합니다:

• 프로젝트 설정: .opencode/skills/<name>/SKILL.md
• 전역 설정: ~/.config/opencode/skills/<name>/SKILL.md
• 프로젝트 Claude 호환: .claude/skills/<name>/SKILL.md
• 전역 Claude 호환: ~/.claude/skills/<name>/SKILL.md
• 프로젝트 agent 호환: .agents/skills/<name>/SKILL.md
• 전역 agent 호환: ~/.agents/skills/<name>/SKILL.md

검색 이해하기

프로젝트 로컬 경로의 경우, OpenCode는 현재 작업 디렉토리에서 git 워크트리 루트까지 올라갑니다. .opencode/의 일치하는 skills/*/SKILL.md와 경로상의 일치하는 .claude/skills/*/SKILL.md 또는 .agents/skills/*/SKILL.md를 로드합니다.

전역 정의도 ~/.config/opencode/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md, ~/.agents/skills/*/SKILL.md에서 로드됩니다.

Frontmatter 작성

각 SKILL.md는 YAML frontmatter로 시작해야 합니다. 다음 필드만 인식됩니다:

• name (필수)
• description (필수)
• license (선택)
• compatibility (선택)
• metadata (선택, 문자열-문자열 맵)

알 수 없는 frontmatter 필드는 무시됩니다.

이름 검증

name은 다음을 충족해야 합니다:

• 1-64자
• 소문자 영숫자, 단일 하이픈 구분자
• -로 시작하거나 끝나지 않음
• 연속 -- 포함하지 않음
• SKILL.md를 포함하는 디렉토리 이름과 일치

동등한 정규식:

^[a-z0-9]+(-[a-z0-9]+)*$

길이 규칙 따르기

description은 1-1024자여야 합니다. 에이전트가 올바르게 선택할 수 있도록 충분히 구체적으로 유지하세요.

예제 사용

.opencode/skills/git-release/SKILL.md를 다음과 같이 생성:

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---
 
## What I do
 
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command
 
## When to use me
 
Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

도구 설명 인식

OpenCode는 skill 도구 설명에 사용 가능한 스킬을 나열합니다. 각 항목에는 스킬 이름과 설명이 포함됩니다:

<available_skills>
<skill>
  <name>git-release</name>
  <description>Create consistent releases and changelogs</description>
</skill>
</available_skills>

에이전트는 도구를 호출하여 스킬을 로드합니다:

skill({ name: "git-release" })

권한 설정

opencode.json에서 패턴 기반 권한을 사용하여 에이전트가 액세스할 수 있는 스킬을 제어:

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

패턴은 와일드카드 지원: internal-*은 internal-docs, internal-tools 등과 일치합니다.

에이전트별 재정의

특정 에이전트에 전역 기본값과 다른 권한 부여.

사용자 정의 에이전트의 경우 (에이전트 frontmatter에서):

---
permission:
  skill:
    "documents-*": "allow"
---

내장 에이전트의 경우 (opencode.json에서):

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

스킬 도구 비활성화

스킬을 사용하지 않아야 하는 에이전트에 대해 완전히 비활성화:

사용자 정의 에이전트의 경우:

---
tools:
  skill: false
---

내장 에이전트의 경우:

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

비활성화되면 <available_skills> 섹션이 완전히 생략됩니다.

로딩 문제 해결

스킬이 표시되지 않는 경우:

• SKILL.md가 모두 대문자인지 확인
• frontmatter에 name과 description이 포함되어 있는지 확인
• 스킬 이름이 모든 위치에서 고유한지 확인
• 권한 확인 - deny가 설정된 스킬은 에이전트에서 숨겨짐