에이전트 스킬

리포지토리는 skills/spider-silk/`에 Agent Skills 형식의 에이전트 스킬을 담고 있다: 작업이 프레임워크에 닿는 순간 에이전트가 한 번 로드하는 `SKILL.md`와, 작업에 필요할 때만 읽는 참조 문서 파일들이다. Spider Silk를 본 적 없는 AI 코딩 에이전트는 추측하는데, 이만큼 의도적으로 설계된 프레임워크는 추측하기에 나쁜 곳이다. Gradle 플러그인은 Plugin Portal이 아니라 Maven Central에서 해석되고, JSON 매핑은 리플렉션이 아니라 직접 작성하며, 에이전트가 습관적으로 만들어 내는 `Controller 인터페이스는 정확히 핸들러가 만들지 말라고 하는 것이다. 스킬은 이 매뉴얼에서 추려낸 것이고, 매뉴얼이 진실의 원천으로 남는다: 스킬이 판가름하지 못하는 질문은 여기서 답하고, API를 바꾸는 릴리스는 스킬도 함께 바꾼다.

Claude Code

리포지토리는 플러그인 마켓플레이스를 겸하므로, 설치는 Claude Code 안에서 두 명령이면 된다:

/plugin marketplace add {project-repo}
/plugin install spider-silk@spider-silk

그러면 스킬은 모든 프로젝트에서 필요할 때 로드되며, 업데이트와 제거도 `/plugin`에서 한다.

단일 프로젝트에만 쓰려면 대신 스킬 디렉터리를 프로젝트의 `.claude/skills/`에 복사하여, 협업자가 클론만으로 스킬을 얻고 각자 아무것도 설치하지 않게 한다:

git clone --depth 1 https://github.com/benelog/spider-silk /tmp/spider-silk
mkdir -p .claude/skills
cp -r /tmp/spider-silk/skills/spider-silk .claude/skills/

프로젝트 수준 복사본은 아래 절에서 말하듯 Cursor와 GitHub Copilot도 읽으므로, 디렉터리 하나가 세 도구를 섬길 수 있다.

Codex

Codex는 모든 프로젝트에 대해 `~/.codex/skills`에서, 그리고 프로젝트 자체의 `.codex/skills`에서 스킬을 읽는다. `skills/spider-silk`를 둘 중 하나에 복사한다.

Cursor

Cursor는 프로젝트의 `.cursor/skills/`와 사용자 수준의 `~/.cursor/skills/`를 읽는다. 프로젝트의 `.claude/skills/`도 읽으므로, 이미 Claude Code용으로 설정된 프로젝트에는 더 필요한 것이 없다.

GitHub Copilot

Copilot은 프로젝트의 `.github/skills/`를 읽고, 코딩 에이전트와 CLI에서는 `~/.copilot/skills/`를 읽는다. Copilot 역시 프로젝트의 `.claude/skills/`를 읽는다.

그 밖의 도구

이 형식은 개방 표준이고, 이 스킬은 도구 특정적인 것을 전혀 쓰지 않는다: 이름과 설명이 담긴 YAML 프런트매터, Markdown 본문, 그리고 옆에 있는 참조 문서 파일로 가는 상대 링크뿐이다. SKILL.md 파일을 발견하는 어떤 도구든 같은 디렉터리를 그대로 받아들인다. https://agentskills.io 가 그런 도구의 목록을 관리한다.

무엇이 들어 있나

`SKILL.md`는 모든 작업에 필요한 것을 담는다: 에이전트가 거슬러 코딩해서는 안 되는 규칙으로 서술된 프레임워크의 원칙, 첫 빌드에 필요한 의존성 및 플러그인 리포지토리, 그리고 코어 API 한눈에 보기다. 나머지는 다섯 개의 참조 문서 파일이 영역별로 하나씩 담는다: 설정, 웹 API, 콘텐츠, 서버와 배포, 테스트다. 그러면 에이전트는 작업이 닿는 영역만 읽는다. 스킬에 새로운 정보는 없다: 모든 문장이 이 매뉴얼이며, 독자의 화면 대신 에이전트의 컨텍스트 윈도에 맞게 압축한 것이다.

측정된 효과

스킬은 2026-08에 같은 세 작업을 스킬을 설치한 채 한 번, 설치하지 않은 채 한 번, 두 번씩 Fable 5, Opus 5, Sonnet 5의 세 Claude 모델에서 실행하여 벤치마크했다. 모든 결과는 조건별 열여덟 개의 행동 단언에 대해 채점했다. 작업은 빈 디렉터리에서 만드는 노트 API, 동작하는 앱에 콘텐츠 협상과 API 키를 더하는 변경, 그리고 기존 {id} 라우트보다 앞서 리터럴 경로를 등록해야 하는 SSE 엔드포인트였다.

모든 단언이 모든 실행에서, 스킬이 있든 없든, 세 모델 모두에서 통과했다. 스킬 없는 에이전트도 무력하지 않다: 배포된 jar가 주어지자 모든 모델이 소스 jar를 풀거나 ~/.m2`에 `javap`를 돌려 API를 재구성했고, `accepts, before 필터의 null 계약, `WebResponse.sse`를 스스로 찾아냈다.

스킬이 바꾸는 것은 그 재구성에 드는 비용이다. 스킬이 있으면 같은 작업이 Fable 5에서 12%, Opus 5에서 16%, Sonnet 5에서 22% 적은 토큰으로 완료되었다. 모델 등급이 내려갈수록 절감폭이 커지는데, 비싸지는 것이 바로 그 재구성이기 때문이다: 스킬 없는 기준선은 작업당 Fable에서 80k, Opus에서 100k, Sonnet에서 130k 토큰이 들었다. 실제 소요 시간은 3~6%만 움직였는데, Gradle이 시간의 대부분을 차지하기 때문이다. 정확성이 수렴하는 최상위 모델 등급에서도 스킬의 이점은 토큰 절감이다: 에이전트가 프로젝트마다 반복했을 발굴 작업이 스킬 안에서 한 번에 끝난다.

통과율에는 반영되지 않았지만 기록해 둘 만한 효과가 둘 있다. 벤치마크 머신이 아티팩트를 mavenLocal에 갖고 있다고 들은 스킬 없는 에이전트들은 다른 어디서도 해석되지 않는 빌드를 내놓은 반면, 스킬을 쓴 에이전트들은 GitHub Packages 리포지토리와 그 자격 증명 패턴을 함께 선언했다. 등록 순서 함정에 걸린 유일한 실행은 실패를 스킬 자체의 경고와 대조하여 고쳤는데, 스킬 없는 실행들은 코드를 쓰기 전에 그 규칙을 처음부터 유도해야 했다.

이 숫자는 각 작업을 한 머신에서 한 번씩 실행한 것이므로, 측정치가 아니라 경향으로 읽는다.