POST·BUILDY

첫 번째 에이전트 플러그인 만들기: 단계별 가이드

AIMCP Teamon 24 days ago · 2 min read

첫 번째 에이전트 플러그인 만들기: 단계별 가이드

에이전트 플러그인(v1.0.0)은 호환 가능한 클라이언트에서 작동하는 에이전트 구성 요소(스킬 및 MCP 서버)를 위한 이식 가능한 패키징 표준입니다. 이 가이드에서는 실제 스펙을 준수하는 플러그인을 처음부터 만들어 볼 것입니다: 하나의 스킬과 하나의 MCP 서버를 포함하는 플러그인을 만들고 공식 스키마에 대해 검증하는 과정을 다룹니다.

1단계: 패키지 구조 생성하기

플러그인은 단순히 디렉토리입니다. 두 가지 필수 구성 요소를 미리 포함하여 생성하세요:

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       └── SKILL.md
└── mcp.json

2단계: 매니페스트 작성하기

plugin.json은 유일한 필수 파일입니다. 매니페스트 스키마는 닫힌 구조입니다 — 이식 가능한 최상위 필드는 고정된 집합으로 제한됩니다:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "summarize.tools",
  "version": "1.0.0",
  "description": "문서 요약을 위한 스킬과 서버입니다.",
  "author": {
    "name": "당신의 이름",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/summarize-tools",
  "repository": "https://github.com/you/summarize-tools",
  "license": "MIT",
  "keywords": ["summarization", "documents", "llm"]
}

$schema와 name만 필수 항목입니다. 나머지는 선택 사항이지만 권장됩니다: version(SemVer), description, author, homepage, repository, license(SPDX), 그리고 검색을 위한 keywords입니다.

참고: 스키마는 의도적으로 닫힌 구조입니다. 클라이언트별 설정은 확장 네임스페이스에 속하며 최상위 필드가 아닙니다.

3단계: 스킬 추가하기

스킬은 skills/ 디렉토리에 위치하며 에이전트 스킬 스펙을 따릅니다. SKILL.md 파일을 포함하는 각 직계 하위 디렉토리는 하나의 스킬입니다:

skills/
└── summarize/
    ├── SKILL.md
    ├── scripts/
    │   └── summarize.py
    └── references/
        └── guidelines.md

최소한의 SKILL.md:

---
name: summarize
description: 문서를 핵심 포인트로 요약합니다. 사용자가 긴 텍스트를 압축해 달라고 요청할 때 사용하세요.
---

# 요약하기

1. 사용자 입력에서 문서를 읽습니다.
2. 주요 주장, 지원 포인트, 실행 항목을 추출합니다.
3. 마크다운 형식으로 요약을 작성하며, 최대 10개의 불릿 포인트로 제한합니다.

## 스크립트

- `scripts/summarize.py` — 파일 경로를 입력받아 요약을 출력하는 CLI입니다.

클라이언트는 skills/*/SKILL.md를 스캔하여 스킬을 발견합니다; 더 깊은 디렉토리는 탐색하지 않으므로 직계 하위 디렉토리당 하나의 스킬을 유지하세요.

4단계: MCP 서버 추가하기

플러그인이 MCP 서버를 포함하는 경우 mcp.json에 설명하세요. 이 형식은 stdio, Streamable HTTP, 그리고 레거시 HTTP+SSE 전송 방식을 지원합니다:

{
  "servers": {
    "summarize": {
      "command": "python",
      "args": ["scripts/mcp_server.py"],
      "env": {}
    }
  }
}

클라이언트는 이 이식 가능한 형식을 자체 네이티브 구성에 매핑합니다 — 필드 이름이 클라이언트의 내부 형식과 일치할 필요는 없습니다.

5단계: (선택사항) 클라이언트 확장 추가하기

코어를 포크하지 않고 특정 클라이언트에 대한 동작을 추가하고 싶으신가요? 클라이언트 이름을 딴 역방향 도메인 네임스페이스 디렉토리를 사용하세요, 예: com.example.client/hooks/hooks.json. 클라이언트는 플러그인 루트에서 자신의 네임스페이스 디렉토리를 찾습니다; 알려지지 않은 네임스페이스는 무시됩니다.

6단계: 검증하기

배포하기 전에 매니페스트를 검증하세요:

$schema는 반드시 공식 스키마 URL을 참조해야 합니다: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json.
name은 반드시 존재하고 비어 있지 않아야 합니다 — 필수 필드가 누락되면 전체 플러그인이 무효화되며 클라이언트는 이를 거부해야 합니다.
SKILL.md 프론트매터에 최소한 name과 description이 있는지 확인하세요.
mcp.json을 스펙의 JSON 스키마(agent-plugins.org/schemas에 게시됨)에 대해 검증하세요.

또한 스펙 저장소의 예제 플러그인(agentplugins/agent-plugins-example)을 표준 참조 자료로 사용하거나, AIMCP의 디렉토리 제출을 통해 플러그인을 실행할 수 있습니다 — 이는 공식 스키마에 대해 검증하고 구성 요소 수를 보고합니다.

7단계: 배포하기

에이전트 플러그인은 디렉토리이므로 배포는 유연합니다: GitHub 저장소에 푸시하거나, 마켓플레이스에 게시하거나, 직접 공유할 수 있습니다. 호환 가능한 클라이언트는 전송 방식에 관계없이 일관되게 플러그인을 발견하고 로드합니다.

다음 단계

준수 세부 사항은 전체 에이전트 플러그인 스펙을 읽어보세요.
스킬 및 MCP 서버 작성 가이드를 살펴보세요.
AIMCP의 에이전트 플러그인 디렉토리를 둘러보고 실제 예제를 확인한 후 여러분의 플러그인을 추가하세요.