finestructure-ai/claude-plugin 내부: 파일 일곱 개로 만든 Claude Code 플러그인

저장소 전체가 파일 일곱 개

복제해 보면 파일 트리가 화면 하나에 들어옵니다.

.claude-plugin/
  plugin.json        686 B
  marketplace.json   507 B
commands/
  deploy.md          3.3 KB
  fs-domain.md       905 B
  fs-status.md       741 B
skills/
  fine-structure/
    SKILL.md         4.0 KB
LICENSE              MIT
README.md            2.3 KB

package.json도 잠금 파일도 CI도 dist도 없습니다. 컴파일하거나 번들링하는 것이 없고, 빌드가 실패할 수 있는 버전 자체가 존재하지 않습니다. 툴체인이 필요하다고 짐작해 플러그인 작성을 미뤄 왔다면 여기서 바로잡을 수 있습니다. 이 형식은 디렉터리 규약과 JSON 파일 두 개이고, 나머지는 산문입니다.

plugin.json은 프로그램이 아니라 포인터

매니페스트에는 흔한 식별 필드가 들어 있고 (name, 버전 0.1.0, description, author, homepage, repository, license, keywords) 그 뒤에 흥미로운 일을 전부 처리하는 블록이 하나 놓여 있습니다.

"mcpServers": {
  "finestructure": {
    "type": "http",
    "url": "https://finestructure.ai/api/mcp"
  }
}

키는 둘뿐입니다. command도 args도 env도 없습니다. 대다수 MCP 설정이 취하는 모양과 비교해 보십시오. 로컬 프로세스 (npx, uvx, 실행 파일 경로), 인자 목록, 그리고 API 키를 담은 env 맵으로 구성됩니다. 대신 streamable HTTP 엔드포인트를 선언하면 서버가 사용자 컴퓨터 밖으로 나갑니다. 그래서 도구 105개 (skill 파일이 밝힌 숫자)가 686바이트짜리 매니페스트 뒤에 자리할 수 있습니다. 사용자의 Node나 Python 버전 때문에 설치가 깨질 일이 없고, 서버 쪽 변경은 플러그인을 새로 배포하지 않아도 반영됩니다. 대가는 재현성입니다. 도구 표면을 클라이언트에서 고정할 수 없습니다.

marketplace.json이 저장소를 자체 배포 경로로 만든다

Claude Code는 패키지 레지스트리가 아니라 marketplace에서 플러그인을 설치하며, marketplace는 플러그인과 소스 경로를 나열한 JSON 파일입니다. .claude-plugin 안의 두 번째 파일이 바로 그 일을 하고, 유일한 플러그인 항목에는 "source": "./"가 적혀 있습니다. 저장소가 플러그인이면서 동시에 그것을 제공하는 marketplace이므로, 배포는 공개 git push 한 번입니다.

/plugin marketplace add finestructure-ai/claude-plugin
/plugin install finestructure@finestructure

둘째 줄에 같은 낱말이 두 번 나오는 이유는 marketplace 이름 앞에 플러그인 이름이 오기 때문이고, 둘 다 finestructure라서 겹쳐 보입니다. 이 구성을 그대로 가져온다면 이름을 다르게 지으십시오. 설치 안내가 분명해지고, 나중에 두 번째 플러그인을 추가할 여지도 남습니다.

명령은 frontmatter가 붙은 프롬프트 템플릿

commands/의 각 파일은 YAML frontmatter와 산문입니다. deploy.md는 description과 argument-hint를 선언하는데, 사용자가 선택 화면에서 보는 두 문자열입니다. 이어서 번호가 붙은 판단 절차를 펼칩니다. 프로젝트 최상위에 app_id가 담긴 .finestructure.json이 있는지 확인하고, 없으면 list_apps를 불러 이름이 일치하는 항목을 찾고, 그래도 없으면 첫 배포로 보고 $ARGUMENTS를 앱 이름으로 씁니다. fs-status.md는 741바이트이며 CLI 하위 명령에 해당하는 일을 합니다. 앱을 확정하고 get_app_status, get_app_links, get_errors를 호출한 뒤 요약합니다. fs-domain.md는 add_custom_domain, get_domain_verification, check_domain_verification, get_domain_ssl_status, set_primary_domain을 순서대로 지납니다.

설계의 핵심은 이 파일들이 아무것도 호출하지 않는다는 점입니다. 도구 이름을 대고, 순서를 정하고, 어떤 단계가 실패했을 때 무엇을 할지 서술할 뿐입니다. 실행은 모델이 MCP 도구를 부를 때 일어납니다. 슬래시 명령은 버전 관리에 올린 프롬프트이므로, 검토란 논리가 맞는지 묻는 일이 아니라 지시가 모호하지 않은지 묻는 일입니다.

가장 잘 쓰인 문장은 금지하는 문장들입니다. deploy.md는 사용자가 분명히 요청하지 않는 한 삭제 도구를 금합니다. fs-domain.md는 DNS 전파에 몇 분에서 몇 시간이 걸린다고 적고, 검증을 반복하지 말고 나중에 다시 시도하도록 제안하라고 지시합니다. 문장으로 쓴 재시도 정책이자 안전 난간이며, 어설픈 플러그인이 빠뜨리는 부분이 바로 이것입니다.

skill과 command: 당기기와 밀기

skills/fine-structure/SKILL.md에는 frontmatter 필드가 name과 description 둘뿐이고, 이 description은 요약이 아니라 발동 조건처럼 읽힙니다. 사용자가 앱을 배포하거나 만들거나 갱신하려 할 때, 도메인을 연결하려 할 때, 데이터나 시크릿을 다루려 할 때 사용하라는 식입니다. 이런 표현은 의도된 것입니다. 명령은 사람이 입력했기 때문에 실행됩니다. skill은 모델이 설명과 현재 상황을 맞춰 보았기 때문에 실행됩니다.

내용 분담도 여기서 따라 나옵니다. SKILL.md는 작업 목록이 아니라 개념 지도입니다. 여기서 앱이 무엇인지 (JSX 페이지, 공용 컴포넌트, 엔터티 스키마, 임의의 서버 코드는 없음), 엔터티가 무엇인지, 어떤 작업이 크레딧을 쓰는지 설명합니다. 이어서 작업 흐름을 도구 사슬로 제시해 get_app_files에서 read_app_file, write_app_file, validate_app, publish_app으로 이어지고, 여러 파일을 고칠 때는 변경 집합을 씁니다. 그다음이 오류 의미론이며 바이트당 무게가 가장 큽니다. 인증 오류는 다시 연결하라는 뜻이고, 크레딧 오류는 충전하라는 뜻이며, 둘 다 재시도 대상이 아닙니다. 이 지식이 없는 에이전트는 재시도해도 소용없는 실패를 반복하고, 사용량 기반 플랫폼에서 그 반복에는 비용이 붙습니다.

직접 만들 플러그인의 규칙도 깔끔하게 나옵니다. 명령 파일이 제품이 무엇인지 설명하고 있다면 그 문단은 skill로 가야 합니다. 명령은 절차로 남겨 둡니다.

매니페스트에 비밀이 없는 이유는 OAuth

엔드포인트는 OAuth 2.1과 동적 클라이언트 등록으로 인증하므로, 첫 도구 호출에서 브라우저에 동의 화면이 열리고 토큰은 저장소가 아니라 Claude Code의 자격 증명 저장소에 남습니다. 포크는 구조상 안전하고, 폐기는 모든 기기에 전달해야 하는 설정 수정이 아니라 서버 쪽에서 처리되며, 부주의한 커밋 한 번이면 공개 diff에 실릴 파일에 장기 유효 키를 붙여 넣으라고 요구하지도 않습니다.

직접 만들 플러그인에 옮길 것

구체적인 지침을 대체로 만드는 순서대로 적습니다.

• name, version, description을 담은 .claude-plugin/plugin.json으로 시작하십시오. 나머지는 모두 선택입니다.
• 호스팅 MCP 엔드포인트를 운영한다면 로컬 명령 대신 url과 함께 "type": "http"를 선언하십시오. 사용자의 실행 환경이 지원 범위에서 사라집니다.
• 플러그인이 하나인 동안에는 marketplace.json을 같은 저장소에 "source": "./"로 두고, 플러그인과 다른 이름을 붙이십시오.
• 모든 명령에 frontmatter의 description과 argument-hint를 주고, 이것이 무엇을 하는지와 뒤에 무엇을 입력하는지에 대한 답으로 쓰십시오.
• 위치 기반 문법을 새로 만들지 말고 $ARGUMENTS를 쓰십시오. 파서는 없고 치환만 있습니다.
• 명령 본문은 판단 절차로 쓰고 도구 이름을 분명히 밝히십시오. "설정 파일이 있으면 app_id를 읽고, 없으면 list_apps를 호출한다"가 의도를 늘어놓은 문단보다 오래 버팁니다.
• 실패 의미론을 글로 남기십시오. 어떤 오류가 최종이고, 어떤 오류가 재시도 가능하며, 재시도 대신 무엇을 말할지 적습니다.
• 파괴적인 도구는 본문에서 이름을 밝히고, 요청이 없으면 쓰지 못하게 하십시오.
• 도메인 모델은 SKILL.md에, 절차는 명령에 두십시오. 둘 사이의 중복은 나쁜 신호입니다.
• 누군가를 main으로 안내하기 전에 로컬 경로나 자신의 포크를 대상으로 /plugin marketplace add로 시험해 보십시오.

거친 부분

솔직히 세 가지가 있고, 치명적인 것은 없습니다. 전부 영어로 쓰여 있고, 형식 쪽에는 이를 고칠 고리가 없습니다. frontmatter에 locale 키가 없으므로 현지화는 명령 파일을 복제하거나 불일치를 감수하는 두 갈래뿐입니다.

API 키가 필요 없다는 설명에는 각주가 붙습니다. SKILL.md는 미디어 생성 도구가 OAuth 연결 밖에 있으며 미디어 범위를 가진 정적 MCP 토큰이 필요하다고 인정합니다. 이 토큰은 플랫폼의 Studio에서 만들고 bearer 헤더로 보냅니다. 플러그인은 이를 잘 처리해서, 벽에 부딪히며 재시도하는 대신 기능이 없는 이유를 설명하라고 모델에 지시합니다. 그래도 경로가 하나뿐이라는 점을 내세운 설계에 두 번째 인증 경로가 덧붙은 셈입니다.

그리고 버전은 0.1.0이며 changelog도 테스트도 CI도 없습니다. markdown이라면 변호할 수 있지만, pre-commit hook에 JSON 스키마 검사를 넣으면 설치를 실제로 깨뜨리는 유일한 오류 부류, 곧 형식이 망가진 매니페스트를 잡아낼 수 있습니다. 디렉터리 등재 신청은 이 글을 쓰는 시점에 심사 중이라, 당분간은 저장소 참조로 설치합니다.

명령 파일 세 개를 먼저 읽고, 그다음 SKILL.md, 마지막으로 JSON 파일 두 개를 읽으십시오. 이 순서라면 형식이 스스로를 설명합니다. markdown은 무엇이 어떤 순서로 일어날지 정하고, MCP 서버는 실제로 무엇이 실행될지 정하며, 매니페스트는 그 사이의 얇은 이음매입니다.