OpenCode Agent / Skill / Tool / MCP 사용하기

OpenCode Agent / Skill / Tool / MCP 사용하기

 

opencode는 단순한 AI 채팅이 아니라 실제로 개발 작업을 수행하는 자동화 도구입니다.

Agent Skill Tool MCP 사용하는 방법에 대해서 알아봅니다.

Agent	= 성격 (누가 일하냐)
Skill	= 지식 (어떻게 판단하냐)
Tool	= 행동 (뭘 실행하냐)
MCP	= 외부능력 (어디까지 할 수 있냐)

우선 실행하고자하는 프로젝트의 루트 폴더에 .opencode 폴더를 하나 생성합니다.

(opencode 명령은 프로텍트 폴더에서 실행합니다.)

 

AGENTS.md (프로젝트 규칙)

역할 : 프로젝트 전체에 항상 적용되는 공통 규칙

폴더 위치

my-project/
 └─ AGENTS.md

 

예시

# Project Rules

- 항상 한국어로 답변한다
- Blazor SSR 기준으로 설명한다
- 코드 예제는 실행 가능한 형태로 제공한다

 

 

Agent (에이전트)

역할 : AI의 캐릭터와 역할을 정의한다.
예시 : Blazor 개발자, 코드 리뷰어, 데이터 분석가

설정 방법

opencode.json 파일에 아래와 같이 작성하여 원하는 agent 를 정의하면됩니다.
(.opencode/opencode.json 위치도 가능)

{
  "agent": {
    "blazor-dev": {
      "mode": "primary",
      "description": "Blazor SSR 전문가",
      "prompt": "You are a Blazor SSR expert."
    },
    "code-reviewer": {
      "mode": "primary",
      "description": "코드 리뷰 전문가",
      "prompt": "Review code strictly."
    }
  },
  "default_agent": "blazor-dev"
}

• primary → 직접 선택 가능 (/agents에 표시)
• subagent → 내부 호출용 (@code-reviewer 방식)

agent.md 로 상세설정이 가능합니다.

폴더구조

.opencode/
 └─ agents/
    └─ blazor-dev/
       └─ agent.md

agent.md 예시

# Blazor SSR Expert

## 역할

Blazor SSR + MudBlazor 전문가

## 규칙

- 항상 한국어로 답변한다
- @rendermode InteractiveServer 기준으로 설명한다
- MudBlazor 최신 방식 사용
- 전체 코드 제공

## 스타일

- 원인 → 해결 → 코드 순서로 설명
- 실무 중심으로 답변
- 불필요한 이론 생략

## 금지

- 동작하지 않는 코드 작성 금지

 

Skill (스킬)

역할 : 특정 상황에서 어떻게 행동해야 하는지 정의하는 지식 문서입니다.
즉, "이럴 때 이렇게 해라"를 알려줍니다.

폴더 구조 (blazor-ssr 스킬을 만든다고 가정)

.opencode/
 └─ skills/
    └─ blazor-ssr/
       └─ SKILL.md

SKILL.md 예시

---
name: blazor-ssr
description: Blazor SSR 문제 해결
license: MIT
compatibility: opencode
---

## 역할

Blazor SSR + MudBlazor 문제 해결

## 규칙

- @rendermode InteractiveServer 확인
- MudBlazor 최신 방식 사용
- 전체 코드 제공

• name과 폴더명이 동일해야 함
• 파일명은 반드시 SKILL.md
• 자동 실행되지 않음
• AI가 필요할 때 선택해서 사용

 

Tool (툴)

역할 : AI가 실제로 실행하는 기능입니다. 이 부분이 자동화의 핵심

예시

{
  "tool": {
    "build": {
      "command": "dotnet build"
    },
    "test": {
      "command": "dotnet test"
    }
  }
}

동작 방식 : 사용자 요청에 따라 AI가 판단하여 실행한다.

예: "빌드해줘" → dotnet build 실행

변수 사용

{
  "tool": {
    "search": {
      "command": "grep -r \"{{query}}\" ."
    }
  }
}

• tool이 없으면 설명만 하는 AI
• tool이 있으면 실제로 작업 수행

 

MCP (Model Context Protocol)

역할 : 외부 시스템과 연결하는 인터페이스

가능한 기능

• 데이터베이스 조회
• API 호출
• 파일 생성
• 서버 실행
• 코드 실행

연결 방법

{
  "mcp": {
    "my-server": {
      "command": "dotnet run --project MyMcpServer"
    }
  }
}

구조

opencode
   ↓
MCP 서버 (C# / Python)
   ↓
DB / API / 파일 / 시스템

C#으로 MCP 서버를 만들면

• Blazor 서버
• 내부 API
• 데이터베이스

이 모든 것을 AI가 직접 사용할 수 있습니다.

 

전체 구조 예시

my-project/
 ├─ opencode.json
 ├─ AGENTS.md
 └─ .opencode/
    ├─ agents/
    │   └─ blazor-dev/
    │       └─ agent.md
    └─ skills/
        └─ blazor-ssr/
            └─ SKILL.md

opencode.json 통합 예시

{
  "$schema": "https://opencode.ai/config.json",

  "agent": {
    "blazor-dev": {
      "mode": "primary",
      "description": "Blazor SSR 전문가"
    },
    "code-reviewer": {
      "mode": "primary",
      "description": "코드 리뷰 전문가"
    }
  },

  "default_agent": "blazor-dev",

  "tool": {
    "search-code": {
      "description": "코드 검색",
      "command": "rg \"{{query}}\""
    },
    "read-file": {
      "description": "파일 읽기",
      "command": "cat {{path}}"
    },
    "git-diff": {
      "command": "git diff"
    },
    "build": {
      "command": "dotnet build"
    },
    "test": {
      "command": "dotnet test"
    }
  },

  "permission": {
    "tool": "allow",
    "skill": "allow"
  }
}