저도 호기심에 ~/.cursor/plugins 폴더를 열어본 게 시작이었습니다. 대표적으로 Atlassian 플러그인 하나를 열었더니 매니페스트가 세 벌이나 있었습니다. .cursor-plugin/plugin.json, .claude-plugin/plugin.json, 그리고 gemini-extension.json. 플러그인은 분명 한 개인데 매니페스트 파일은 왜 세 개씩 필요했을까요?

스킬 폴더도 사정이 비슷했습니다. Supabase 플러그인 디렉터리에는 SKILL.md, AGENTS.md, CLAUDE.md, README.md 4개가 한꺼번에 들어 있었습니다. 사실 AI 도구마다 인식하는 설정 파일명이 제각각이라 이렇게 중복으로 만들어 둔 것입니다. 이렇게 되면 유지보수할 때 뭐 하나 수정하면 모두 동일하게 수정해야 하는 번거로움이 발생할 수밖에 없습니다.

atlassian 플러그인의 .claude-plugin·.cursor-plugin 중복 매니페스트와 supabase 스킬 폴더의 AGENTS·CLAUDE·SKILL.md 중복 파일 — <출처: 작가, Plugin 설치 상태>

바로 이런 파편화와 중복 관리의 고통을 끝내겠다고 2026년 7월에 나온 규격이 ‘Agent Plugins 1.0.0’ 표준입니다. 이건 스킬 문서와 MCP 도구를 구조적 규격화해 Cursor든 Gemini든 똑같이 사용 할 수 있게 하는 표준 규약입니다. 그런데 아직도 실제 플러그인들은 중복 구조를 여러 벌 들고 있었습니다.

표준이 나온 지 얼마 안 됐으니 그럴 수 있겠다는 생각이 들면서도, 그렇다면 지금 스펙 문서 그대로 플러그인을 한 벌만 만들면 다 되는 건지 궁금해졌습니다. 그래서 작은 플러그인을 하나 직접 만들어서 테스트를 진행해 봤습니다.

Agent Plugins 1.0.0이란?

우선 Agent Plugins에 대해 간단히 소개하자면, Agent Plugins 1.0.0은 재사용 가능한 컴포넌트를 배포 가능한 플러그인 단위로 패키징하는 표준 입니다. Amazon, Cursor, Microsoft, OpenAI, Vercel이 참여한 기술 운영 위원회(TSC)가 2026년 7월에 1.0.0 규격을 발표했고, 이후 구글이 코어 메인테이너로 합류했습니다.

여기서 다루는 요소들의 역할은 다음과 같습니다.

스킬(Agent Skills): 에이전트가 어떻게 판단하고 작업할지 정의하는 자연어 지침(SKILL.md)입니다.
MCP 서버(Model Context Protocol): 에이전트가 실제로 명령을 실행하거나 데이터를 가져오는 실행 도구(mcp.json)입니다.
Agent Plugins: SKILL과 MCP를 결합하여, Cursor든 Claude Code든 이기종 AI 환경 어디서나 동일하게 인식하도록 묶은 단일 패키지 규격(plugin.json)입니다.

이 표준이 나오기 전까지는 스킬과 MCP 도구를 묶어주는 단위가 없었습니다. 깃허브 저장소에서 SKILL.md를 내려받아 도구별 폴더로 직접 복사해야 했고, MCP 서버는 README.md에 적힌 설정 내용을 찾아 IDE에 일일이 등록해야 했죠. SKILL과 MCP가 사실상 한 쌍으로 움직여야 하는데도 각자 따로 돌아다니다 보니, 어느 한쪽만 업데이트 되면 버전이 틀어지는 문제가 빈번하게 발생했습니다.

Agent Plugins는 README.md에 텍스트로 적어두던 수동 설정을 표준화된 디렉터리 구조로 변경되었습니다. SKILL과 MCP가 정해진 위치에 있어야 하고 AI 도구들은 정해진 위치에서 이를 찾아 사용합니다. 덕분에 플러그인을 설치하고 사용하는 과정이 훨씬 간편해졌습니다.

구글(Google)은 에이전트 도구 생태계를 ① 발견(Discovery) → ② 기술/카탈로그(Catalog) → ③ 포장(Packaging) → ④ 실행(Execution)의 4단계로 정의했습니다. 이 중에서 Agent Plugins 1.0.0이 맡은 역할은 오직 ③ 포장뿐입니다. 내부 컴포넌트가 어떻게 동작하고 어떤 프로토콜로 통신하는지는 기존의 Agent Skills와 MCP 규격을 그대로 따르며, 이번 표준은 ‘파일과 폴더를 어디에 배치할 것인가’의 패키징 영역만 다루고 있습니다.

스펙 문서에서 규정한 핵심 규칙은 크게 세 가지입니다.

경로의 엄격한 고정: 스킬은 반드시 skills/<skill_name>/SKILL.md에 위치해야 하며, MCP 서버 선언은 최상위 mcp.json에 작성해야 합니다. plugin.json에서 임의로 경로를 변경하거나 컴포넌트를 인라인으로 선언하는 것은 허용되지 않습니다.
독립 실패(Independent Failure) 원칙: 플러그인에 포함된 특정 MCP 서버가 환경 불일치나 포트 충돌로 실행되지 않더라도, 클라이언트는 해당 도구만 건너뛰고 나머지 스킬과 도구를 정상적으로 로드합니다. 부품 하나가 고장 났다고 플러그인 전체가 멈추지 않도록 설계되었습니다.
의도적인 스코프 제외: 설치 방식, 원격 배포 프로토콜, 권한 모델, 샌드박싱, 출처 검증, 사용자 경험(UX)은 v1 스펙 범위에서 명시적으로 제외되었습니다. 데스크톱 IDE, 터미널 CLI, 클라우드 환경마다 요구되는 보안 제약이 다르기 때문에 런타임 클라이언트의 재량에 맡긴 것입니다.

스펙만 보고 만든 gen-test-doc 플러그인

실제로 스펙대로 만들면 잘 동작하는지 확인하기 위해 무엇을 만들지 고민했습니다. 스킬만 넣으면 텍스트 파일 하나라 표준의 절반밖에 못 써보고, MCP 서버만 넣으면 굳이 이 포맷을 쓸 이유가 없거든요. 결국 판단 규칙과 실행 도구가 둘 다 필요한 작업으로 골랐습니다. 소스 코드를 읽고 단위 테스트와 API 문서를 만들어주는 gen-test-doc-plugin입니다. 어떤 케이스를 테스트로 뽑을지 정하는 건 스킬에 맡기고, 실제로 테스트를 돌려 결과를 가져오는 건 MCP에 맡겼습니다.

완성된 디렉터리는 이렇게 생겼습니다.

gen-test-doc-plugin/
├── plugin.json                 # 플러그인 매니페스트
├── skills/
│   └── gen-test-doc/
│       ├── SKILL.md            # 단위 테스트 및 문서 생성 지침
│       └── references/
│           └── doc-template.md # API 문서 양식
├── mcp.json                    # MCP 서버 설정
└── scripts/
    └── test-runner.js          # stdio MCP 서버 구현

매니페스트에 꼭 넣어야 하는 필드는 두 개뿐이었습니다. 로컬에서 돌려보는 정도라면 이게 전부예요.

{
  "$schema": "https://agent-plugins.org/schemas/v1/plugin.json",
  "name": "gen-test-doc"
}

스키마에는 version, description, author, license 같은 메타데이터 필드도 있습니다. 카탈로그에 올리거나 배포할 때 쓰는 값들이라, 아직 그 단계가 아니면 $schema와 name만 적어도 됩니다.

스킬 파일 skills/gen-test-doc/SKILL.md에는 프롬프트에 매번 치기 번거로운 규칙들을 담았습니다. 함수 시그니처만 보고 넘겨짚지 말고 실제 호출부까지 찾아서 확인할 것, Happy Path만 쓰지 말고 빈 배열이나 네트워크 지연 같은 경계 조건을 셋 이상 넣을 것, 그리고 생성한 문서는 references/doc-template.md 양식을 사용하라는 형태의 내용입니다.

name: gen-test-doc
description: 소스 코드를 분석해 단위 테스트와 기술 문서를 만듭니다.

테스트 및 문서 생성 지침

지정한 대상 소스 코드를 분석할 때는 반드시 다음 순서로 작업합니다.

1. 대상 파일의 함수와 클래스 시그니처뿐 아니라, 실제 프로젝트 내 호출부(Call site)를 검색해 실제 입출력 형태를 확인합니다.

2. 단위 테스트 작성 시 정상 케이스(Happy Path) 외에 다음 경계 조건을 최소 3개 이상 포함합니다.

빈 입력값, Null, Undefined 전달 상황
비동기 호출 실패 또는 타임아웃 상황
유효하지 않은 타입이 인자로 전달되는 예외 상황

3. 생성하는 기술 문서는 `references/doc-template.md` 양식에 맞추어 마크다운으로 작성합니다.

mcp.json에는 작성한 테스트를 돌려 결과를 가져오는 도구 하나를 선언했습니다.

{
  "$schema": "https://agent-plugins.org/schemas/v1/mcp.json",
  "mcpServers": {
    "test-runner": {
      "type": "stdio",
      "command": "node",
      "args": ["${PLUGIN_ROOT}/scripts/test-runner.js"]
    }
  }
}

스크립트 scripts/test-runner.js는 표준 입출력으로 통신하는 작은 MCP 서버입니다. run_tests라는 도구 하나를 열어두고, 호출이 들어오면 npm test를 띄워 표준 출력과 종료 코드를 JSON-RPC 형식으로 돌려줍니다.


import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { execFile } from "child_process";

const server = new Server(
  { name: "test-runner", version: "1.0.0" },
  { capabilities: { tools);

    {
          },
        },
      },
    },
  ],
}));
  }
      resolve({
          {
              stdout,
              stderr,
            }),
          },
        ],
      });
    });
  });
});

여기까지 작업하는 데 5분도 채 걸리지 않았습니다. 스펙 문서대로 폴더를 만들고 매니페스트와 스킬, MCP 서버 파일을 제자리에 넣기만 하면 끝이었죠. 예전처럼 IDE마다 설정 파일을 따로 열어 경로를 잡거나 README.md에 복잡한 설치법을 적을 필요 없이, 폴더 하나로 깔끔하게 떨어지는 패키징 경험 자체는 꽤 만족스러웠습니다.

이제 이 폴더를 에디터에 얹기만 하면 커서(Cursor)든 어디서든 똑같이 돌아가겠구나 생각했는데요. 테스트 해보니 생각지도 못한 복병을 마주치게 되었습니다.

만들고 나서야 보인 것들(실측과 디버깅 기록)

1) 스펙 문서의 ${PLUGIN_ROOT}를 Cursor는 치환하지 않습니다

스펙 문서와 공식 가이드에서는 패키지 루트를 가리키는 공식 매크로로 ${PLUGIN_ROOT}를 안내합니다. 하지만 실제로 작성한 플러그인을 Cursor 환경에서 사용할 때 MCP가 전혀 뜨지 않았습니다.

돋보기로 들여다보는 플러그인 박스에 PLUGIN_ROOT 라벨이 붙고 뒤로 코드 창이 떠 있는 다크톤 일러스트 — <출처: 작가>

실제로 필자의 테스트 환경(macOS, Cursor 3.17.19 빌드)에서 런타임 코드를 정밀 분석해 보았습니다.

Cursor 3.17.19 번들 workbench.desktop.main.js에서 strings·grep으로 PLUGIN_ROOT·CLAUDE_PLUGIN_ROOT·CURSOR_PLUGIN_ROOT 치환 매크로를 검색하는 터미널 명령어 화면

결과는 의외였습니다. 번들 내부에는 오직 ${CLAUDE_PLUGIN_ROOT}와 ${CURSOR_PLUGIN_ROOT}만 치환 목록에 등록되어 있었고, 정작 표준 스펙인 ${PLUGIN_ROOT}는 목록에 아예 없었습니다.

스펙 문서대로 ${PLUGIN_ROOT}를 적으면 매크로가 문자열 그대로 전달되어 경로를 찾지 못하고 실패합니다. 더 큰 문제는 독립 실패(Independent Failure) 원칙 때문에 에러 메시지가 화면에 전혀 뜨지 않고 조용히 MCP만 누락된다는 점입니다. 스펙을 정확히 지킬수록 MCP가 소리 없이 누락되는 역설적인 상황이 발생하고 있었습니다.

2) 표준 스펙으로 정의된 경로를 제일 마지막에 확인한다

MCP 도구뿐만 아니라 에이전트의 사고 지침을 담은 Skill을 불러오는 과정에서도 예상치 못한 문제를 마주쳤습니다.

분명 스펙 문서에는 skills/<skill_name>/SKILL.md가 표준 경로로 정의되어 있는데, 기존에 배포된 다른 플러그인들을 열어보면 루트 경로에 SKILL.md를 두거나 .cursor/skills/ 같은 도구별 폴더에 두는 경우가 여전히 많았습니다. 의아한 마음에 호환 클라이언트가 스킬 파일을 실제로 어떤 순서로 찾아 들어가는지 추적해 보았습니다.

호환 클라이언트가 스킬 파일을 어떤 순서로 찾아 들어가는지 추적해 본 결과는 다음과 같았습니다.

스킬 파일 탐색 우선순위표: 1순위 Cursor 레거시, 2순위 Claude Code 레거시, 3순위 Agent Plugins 표준 경로, 4순위 SKILL.md 단독 비표준 경로

클라이언트는 하위 호환성을 위해 벤더별 레거시 경로를 먼저 확인한 뒤에야 표준 경로를 읽습니다. 만약 디렉터리 내에 이전 설정 파일이 남아 있다면 표준 경로의 최신 스킬이 무시될 수 있으므로, 플러그인 패키징 시 구버전 디렉터리가 섞이지 않도록 주의해야 합니다.

Agent Plugins, 실무에서 어떻게 활용하면 좋을까?

이제 플러그인 표준도 정식으로 발표되었으니, 평소 업무에서 자주 반복하는 작업이나 팀 협업에 꼭 필요한 플러그인을 직접 만들어 활용해 보면 어떨까요? 현업 엔지니어링 환경에서 바로 적용해 볼 만한 3가지 실무 활용 아이디어를 소개합니다.

1) 팀 단위 ‘사내 코딩 표준 및 엔지니어링 툴킷’ 배포

적용 시나리오: 신규 입사자 온보딩이나 팀 개발 환경 표준화.
패키징 구성:
- 스킬(skills/): 사내 아키텍처 규칙, 커밋 메시지 컨벤션, 에러 핸들링 가이드라인.
- MCP 도구(mcp.json): 사내 Jira 티켓 생성기, 사내 API 스키마 레지스트리 조회 도구, CI 파이프라인 트리거.
효과: 개발자마다 IDE가 Cursor이든 VS Code이든 상관없이, 팀의 공용 플러그인 폴더 하나만 등록하면 팀 전체가 동일한 규칙과 사내 도구를 즉시 활용할 수 있습니다.

2) 도메인 특화 ‘품질 검증 및 테스트 자동화’(본문 실습 모델)

적용 시나리오: 본문에서 다룬 gen-test-doc-plugin과 같은 QA 및 문서화 파이프라인.
패키징 구성:
- 스킬(skills/): 경계 조건(Null, 빈 배열, 비동기 타임아웃) 도출 지침과 API 명세서 Markdown 템플릿(references/).
- MCP 도구(mcp.json): 테스트 러너(Jest, PyTest) 실행 및 실패 로그 수집 도구.
효과: AI가 단순 텍스트로 테스트 코드만 짜주는 데 그치지 않고, 실제로 테스트를 구동하고 결과 로그를 확인하여 스스로 코드를 수정하는 ‘완결형 자동화 루프’를 플러그인 하나로 완성할 수 있습니다.

3) 인프라 및 DB 마이그레이션 안전장치(DevOps / DataOps)

적용 시나리오: 데이터베이스 스키마 변경, 클라우드 리소스 생성 등 휴먼 에러 위험이 높은 작업.
패키징 구성:
- 스킬(skills/): 마이그레이션 쿼리 작성 규칙 및 안전 점검 체크리스트.
- MCP 도구(mcp.json): 로컬 DB 연결 테스트 도구, 드라이런(Dry-run) 검증 스크립트.
효과: 고위험 작업을 수행할 때 AI 에이전트가 정해진 보안 지침을 철저히 따르면서 안전하게 실제 도구를 실행하도록 통제할 수 있습니다.

어떨 때 플러그인을 만들어 사용하는 게 좋을까?

모든 상황에서 무조건 플러그인을 만들어야 하는 것은 아닙니다. 작업의 성격에 따라 가장 단순하고 효율적인 단위를 선택하는 것이 실무적인 판단입니다.

프로젝트 상황별 권장 아키텍처표: 지침만 필요하면 SKILL.md 단독, 단순 도구 연동이면 mcp.json 단독, 지침과 도구 짝이 필요하면 Agent Plugins 1.0.0 — <출처: 작가>

직접 만들어보고 내린 결론은 이렇습니다. Agent Plugins 1.0.0이 고정한 포장 규칙 자체는 지금 써도 될 만큼 깔끔하게 정리되어 있습니다. 스킬과 MCP를 한 폴더에 넣고 정해진 자리에 두는 것만으로도, 예전에 README에 적어두던 “이 스킬 쓰려면 저 서버도 등록하세요”라는 안내에서 명확한 파일 구조로 바뀝니다. 팀원에게 폴더 하나를 건네는 것과 장문의 설치 안내문을 건네는 것은 차원이 다릅니다.

다만 그 포장을 런타임 클라이언트가 어떻게 열어 읽을지에 대한 구체적인 이행은 아직 적용되지 않은 것 같습니다. 이번 실측에서 겪은 문제들이 전부 그 지점에서 발생했습니다. 매크로 이름이 클라이언트마다 다르고, 탐색 순서가 스펙과 반대이며, 문서에 있는 설정 키가 릴리스 빌드에 누락되어 있기도 합니다.

표준이 설치와 권한을 정의하지 않은 것이 잘못이라고 보지는 않습니다. IDE와 CLI, 클라우드가 각자 다른 보안 모델을 갖는데 무리하게 하나로 묶으려 했다면, 어디에서도 채택되지 못하는 규격이 되었을 테니까요.

당장 플러그인을 도입할 계획이라면, 다음 사항들을 미리 염두에 두시길 권합니다.

경로 매크로 확인: 스펙 이름만 믿지 마시고 대상 클라이언트가 실제로 치환해 주는 매크로 이름을 꼭 확인하세요.
공식 스키마 사전 검증: 매니페스트에 스키마 검증을 걸어두면 사소한 속성 오류나 $schema 누락을 초반에 걸러낼 수 있습니다.
가벼운 전송 방식 고려: stdio 서버는 무거운 node_modules 의존성을 함께 묶어야 하므로, 팀 단위 배포까지 고려한다면 중앙 원격 서버(streamable-http) 방식이 관리 부담을 크게 덜어줍니다.

남는 질문은 결국 하나입니다. 표준이 비워둔 설치와 권한 승인 영역을 클라이언트 벤더들이 과연 사실상의 단일 표준으로 수렴시킬지, 아니면 매크로 이름이 갈라진 것처럼 또 다른 파편화를 낳을지입니다. 답은 규격 문서가 아닌 앞으로 나올 클라이언트들의 릴리스 노트에서 확인하게 될 것입니다.

<참고>

Google for Developers Blog, “Agent Plugins package your skills, tools, and more”