에이전트 스킬

에이전트 스킬을 사용하면 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 worktree에 도달할 때까지 상위로 이동합니다. 그 과정에서 .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 (선택, string-to-string 맵)

알 수 없는 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"
    }
  }
}

권한	동작
`allow`	스킬이 즉시 로드됨
`deny`	스킬이 에이전트에서 숨겨지고 액세스가 거부됨
`ask`	로드 전에 사용자 승인 요청

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

에이전트별 재정의

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

커스텀 에이전트의 경우 (에이전트 frontmatter에서):

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

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

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

skill 도구 비활성화

스킬을 사용하면 안 되는 에이전트의 경우 스킬을 완전히 비활성화하세요:

커스텀 에이전트의 경우:

---
tools:
  skill: false
---

내장 에이전트의 경우:

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

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

로드 문제 해결

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

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