에이전트 스킬

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

Claude Code

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

/plugin marketplace add benelog/spider-silk
/plugin install spider-silk@spider-silk

그러면 스킬은 모든 프로젝트에서 필요할 때 로드되며, 제거는 /plugin으로 한다.

설치된 스킬은 마켓플레이스가 갱신되어야 새 릴리스를 따라간다. Claude Code는 Anthropic의 것이 아닌 마켓플레이스를 자동 업데이트가 켜져 있을 때만 스스로 갱신하며, 자동 업데이트는 기본으로 꺼져 있다. /plugin에서 Marketplaces, spider-silk, Enable auto-update를 차례로 골라 켠다. 자동 업데이트가 꺼져 있으면, 명령 하나가 마켓플레이스를 갱신하고 새 릴리스를 설치한다:

/plugin marketplace update spider-silk

실행 중인 세션은 로드한 버전을 유지하며, /reload-plugins나 재시작이 새 버전을 적용한다.

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

git clone --depth 1 --branch v1.1.0 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 plugin marketplace add benelog/spider-silk
codex plugin add spider-silk@spider-silk

그러면 스킬은 모든 Codex 세션에서 로드되며, codex plugin remove spider-silk@spider-silk는 플러그인을 제거한다.

설치된 스킬은 다시 추가하기 전까지 설치한 버전에 머문다. 두 명령이 마켓플레이스를 받아 오고 그것이 가리키는 릴리스를 설치한다:

codex plugin marketplace upgrade spider-silk
codex plugin add spider-silk@spider-silk

그 뒤에 시작한 Codex 세션이 새 버전을 로드한다.

Codex는 프로젝트 자체의 .agents/skills/에서도 스킬을 읽는다. 단일 프로젝트에만 쓰려면 대신 스킬 디렉터리를 그곳에 복사하여, 협업자가 클론만으로 스킬을 얻게 한다:

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

복사한 스킬이 바로 보이지 않으면 Codex를 다시 시작한다.

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이 시간의 대부분을 차지하기 때문이다. 정확성이 수렴하는 최상위 모델 등급에서도 스킬의 이점은 토큰 절감이다: 에이전트가 프로젝트마다 반복했을 API 재구성이 스킬 안에서 한 번에 끝난다.

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

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