내 첫 Claude Code 플러그인 만들기
I’m ready to translate the article for you, but I’ll need the full text you’d like translated (excluding the source line you’ve already provided). Please paste the content you want translated, and I’ll keep the source link at the top exactly as you requested.
소개
저는 Forgetful용 Claude Code 플러그인을 만들었습니다.
Forgetful는 제가 작업해 온 의미 기억 시스템으로, Claude Code 세션 전반에 걸쳐 지속되는 지식, 관련 개념 간 자동 연결, 저장소를 검색 가능한 기억으로 인코딩하는 기능을 제공합니다. 처음 출시했을 때 이에 대해 여기에서 작성했습니다.
몇 주 동안 매일 사용했지만, 다른 사람들을 설정하도록 하는 데는 마찰이 있었습니다 (MCP 구성, 환경 변수, 데이터베이스 백엔드 선택 등). README를 보내고 다시는 연락이 오지 않는 그런 상황이었습니다.
저는 또한 몇 가지 프롬프트 예시도 만들었습니다(some prompt examples as well).
Claude Code 플러그인이 해답처럼 보였습니다.
아직 사용해 보지 않으셨다면, Claude Code 플러그인에 대한 공식 문서(Claude Code plugins)를 확인하세요. 이를 통해 맞춤 슬래시 명령, 에이전트, 스킬, MCP 서버 등으로 Claude Code를 확장할 수 있습니다. 워크플로를 묶어 공유할 수 있으며, 누군가가 /install your-plugin을 실행하면 설정이 완료됩니다.
제가 원했던 바로 그 것이었습니다: Forgetful를 실행하는 하나의 명령과 제가 일상적으로 사용하는 슬래시 명령들을 하나로 묶어 다른 사람도 쉽게 시도할 수 있도록 하는 것이죠.
플러그인 명령
| 명령 | 설명 |
|---|---|
/forgetful-setup | MCP 연결을 구성합니다. |
/memory-search | 지식 베이스 전반에 걸친 의미 검색 |
/memory-save | Zettelkasten 제약 조건(하나의 개념, ≤ 400 단어, 중요도 점수, 적절한 맥락)으로 메모리를 생성합니다. |
/memory-list | 최근 메모리를 탐색합니다. |
/memory-explore | 깊은 그래프 탐색; 링크와 엔터티를 따라갑니다. |
/encode-repo | 코드베이스를 지정하고 그로부터 메모리를 추출합니다. |
또한, 세 가지 자동 활성화 스킬이 다음을 돕습니다:
- 언제 쿼리하고 언제 메모리를 생성할지 결정하기,
- 항목을 적절히 큐레이션하고 연결하기, 그리고
- 지식 그래프를 길을 잃지 않고 탐색하기.
이것은 새로운 아이디어가 아니라, 제가 이미 사용하던 워크플로우를 패키징한 것입니다.
주의사항 및 교훈
구성 파일은 업데이트 시 사라집니다
첫 번째 버전에서는 플러그인 디렉터리 안에 .mcp.json 파일을 포함시켰습니다. 업데이트 후 플러그인 디렉터리(~/.claude/plugins/forgetful-plugin@1.0.0/)가 삭제되면서 설정 파일이 사라졌습니다.
해결 방법: 플러그인 내부에 설정 파일을 포함하지 마세요. 저는 /forgetful-setup을 다음과 같이 실행하도록 다시 작성했습니다:
claude mcp add forgetful --scope user -- uvx forgetful-ai이 명령은 전역 ~/.claude.json에 기록되며, 플러그인 업데이트 시에도 유지됩니다. 사용자 지정 설정(Postgres, 원격 호스팅, 인증 토큰 등)의 경우, 해당 명령은 GitHub에서 최신 문서를 가져와 옵션을 단계별로 안내하므로 오래된 중복 문서를 피할 수 있습니다.
비용이 많이 드는 명령은 서브에이전트가 필요합니다
/memory-explore는 다섯 단계 탐색을 수행합니다 (쿼리 → 링크 따라가기 → 엔티티 찾기 → 관계 가져오기 → 엔티티 연결 메모리 추출). 전체 과정을 메인 모델에서 실행하면 컨텍스트 창이 빠르게 가득 차고 비용이 크게 증가합니다.
해결책: Haiku 서브에이전트를 생성하여 무거운 작업을 처리하고, 간결한 요약만 반환합니다. 이렇게 하면 비용이 약 1/10 수준으로 줄어들고 메인 대화가 깔끔해집니다. 커스텀 에이전트를 제공하는 것도 고려했지만, 각 에이전트 정의가 컨텍스트 창을 차지하므로 언제든 사용할 수 있고 모든 도구에 접근 가능한 내장 general-purpose 에이전트를 선택했습니다.
스킬은 단순한 프롬프트 이상입니다
처음에는 스킬이 단순히 마크다운 프롬프트 파일이라고 생각했습니다. 누락된 부분은 YAML 프런트머터 설명으로, 이 설명이 모델에 노출되어 스킬이 언제 활성화될지를 결정합니다. 모델은 각 메시지마다 전체 파일이 아니라 이 설명만을 스캔합니다.
핵심 요점:
- 스킬이 적용되는 시점을 명시하는 명확하고 3인칭 설명을 작성하세요.
- 모호한 설명은 트리거되지 않습니다.
- 설명은 주로 인간 독자를 위한 것이 아니라, 스킬 활성화 트리거 역할을 합니다.
시도해 보기
/install forgetful-plugin
/forgetful-setup표준 설정은 약 30 초 정도 걸립니다.
Links
- Plugin repository:
- Main Forgetful project: