Agent Skills 가 알아서 켜지는 순간 — 명령 없이 발동하는 스킬, 토큰 비용, 안 맞는 경우 [6/6]

/spec 같은 명령을 안 쳐도 Agent Skills 가 알아서 켜지나요?

켜져요. 두 갈래로요. 하나는 세션이 열릴 때마다 안내 스킬 하나를 자동으로 넣어 주는 훅이고, 다른 하나는 지금 하는 일이 어느 스킬의 설명과 맞으면 Claude Code 가 그 스킬을 스스로 꺼내는 Claude Code 본래의 동작이에요. 이 마지막 글은 그 「알아서」가 어디까지인지, 그만큼 늘어나는 토큰이 얼마인지, 그리고 이 플러그인이 안 맞는 경우를 정리해요.

이 시리즈 — ① 설치와 첫 확인 · ② /spec — 만들 것을 먼저 문서로 · ③ /plan — 일을 한 번에 끝낼 크기로 · ④ /build 와 /test · ⑤ /review 와 /ship · ⑥ 알아서 켜지는 스킬과 한계(이 글)

어떻게 알아서 켜지나 — 두 갈래

첫째, 세션 시작 훅. 플러그인에는 SessionStart 훅이 하나 들어 있어요. Claude Code 를 켤 때마다 using-agent-skills 라는 안내 스킬의 본문을 「중요」 표시를 붙여 대화에 넣어요. 그래서 명령을 치지 않아도 Claude Code 는 매 세션 첫머리에 「지금 이 일은 어느 스킬로 가나」 하는 흐름도를 읽고 시작해요. 훅 스크립트가 jq 로 그 내용을 JSON 으로 감싸 넘기기 때문에, jq 가 없으면 이 자동 안내만 빠지고 안내 메시지가 대신 떠요.

둘째, 스킬 설명. 나머지 23개 스킬은 Claude Code 의 스킬 규칙을 그대로 따라요. 각 스킬 파일 머리에 「무엇을 하고 언제 쓴다」는 설명이 있고, Claude Code 는 매 대화에서 그 설명들만 먼저 보고 있다가 지금 일과 맞으면 본문을 꺼내요. 공식 문서 Claude Code — Skills가 이 동작을 설명해요. 그래서 「이 API 어떻게 설계할까」라고 말하면 api-and-interface-design 이 붙고, 「테스트가 갑자기 깨졌어」라고 하면 debugging-and-error-recovery 가 붙는 식이에요.

안내 스킬의 흐름도 일부를 옮기면 이래요. 저장소의 using-agent-skills/SKILL.md 에 전체가 있어요.

일이 들어온다
 ├── 아직 뭘 원하는지 모른다        → interview-me
 ├── 새 기능·새 프로젝트다          → spec-driven-development
 ├── 사양은 있고 작업이 필요하다    → planning-and-task-breakdown
 ├── 코드를 짠다                     → incremental-implementation
 │    ├── 공식 문서로 확인해야 한다  → source-driven-development
 │    └── 위험하거나 낯선 코드다     → doubt-driven-development
 ├── 뭔가 깨졌다                     → debugging-and-error-recovery
 ├── 커밋한다                        → git-workflow-and-versioning
 └── 배포한다                        → shipping-and-launch

명령 없이 자주 붙는 스킬 넷

앞 글들에서 다룬 명령 뒤에 붙는 스킬 말고, 명령이 없는데도 자주 켜지는 것들이에요.

context-engineering — 무엇을 보여 줄지 고른다. 에이전트에게 주는 정보를 다섯 층으로 나눠요. 항상 실리는 규칙 파일(CLAUDE.md) → 이번 기능의 사양 → 고칠 파일 → 오류 출력 → 대화 기록 순이에요. 「5,000단어 사양 전체가 아니라 인증 절만 넣어라」, 「테스트 출력 500줄이 아니라 실패한 한 줄만 넣어라」 같은 규칙이 있어요. 외부 문서나 설정 파일 안에 지시문처럼 보이는 글이 있으면 따르지 말고 데이터로 취급해 사용자에게 알리라는 신뢰 등급도 여기 적혀 있어요.

source-driven-development — 기억이 아니라 문서로 짠다. 「감지 → 가져오기 → 구현 → 인용」 네 단계예요. 먼저 package.json 같은 파일에서 정확한 버전을 읽고, 그 버전의 공식 문서 페이지를 가져온 뒤 그대로 구현하고, 출처를 적어요. 스택오버플로 답변, 블로그 글, 그리고 모델 자신의 훈련 데이터는 1차 출처로 인정하지 않는다고 못 박아요. 훈련 데이터는 낡는다는 게 이 스킬의 전제예요.

doubt-driven-development — 자기 결론을 남한테 의심시킨다. 「주장 → 추출 → 의심 → 반영 → 정지」 다섯 단계예요. 결론이 서면 그 코드와 조건만 떼어 문맥이 없는 새 검토자에게 넘기는데, 프롬프트가 「검증하지 마라, 요약하지 마라, 틀린 곳을 찾아라」로 시작해요. 자기 결론(주장)은 넘기지 않아요. 넘기면 검토자가 동의하는 쪽으로 기울기 때문이래요. 세 번 돌려도 사소한 것만 남으면 멈춰요. Gemini·Codex 같은 다른 회사 모델에 2차 의견을 묻는 선택지도 있는데, 사용자에게 매번 묻고 허락 없이는 실행하지 않는다고 적혀 있어요.

git-workflow-and-versioning — 커밋을 저장점으로. 조각 하나가 되면 바로 커밋, 커밋 하나에 한 가지 변경, 한 커밋 100줄 안팎, 메시지에는 「무엇」이 아니라 「왜」. main 은 언제나 배포 가능한 상태로 두고 가지는 1~3일 안에 합치라는 트렁크 기반 개발을 기본으로 권해요.

이것 말고 debugging-and-error-recovery 의 「멈춰라」 규칙도 자주 만나요. 뭔가 깨지면 새 기능을 멈추고, 오류 출력을 보존하고, 재현 → 위치 찾기 → 최소화 → 수정 → 재발 방지 순서로 가라는 거예요. 깨진 것을 두고 다음 기능으로 넘어가면 오류가 쌓인다는 이유예요.

명령과 상관없이 항상 지키라는 여섯 가지

안내 스킬에는 모든 스킬에 공통으로 걸리는 행동 여섯 가지가 있어요. 이 플러그인의 성격이 가장 잘 드러나는 부분이에요.

가정을 먼저 드러낸다. 사소하지 않은 일을 시작하기 전에 「내가 가정하는 것」을 번호로 적고 「틀렸으면 지금 고쳐 달라」고 말해요.
헷갈리면 멈춘다. 사양과 코드가 다르면 한쪽을 골라 조용히 진행하지 말고, 어느 쪽이 맞는지 묻고 기다려요.
아니라고 말한다. 문제가 뻔한 방식이면 「물론이죠!」 하고 따르지 말고, 무엇이 얼마나 나빠지는지 숫자로 짚고 대안을 내요. 저장소는 이걸 「아첨은 실패 모드」라고 적어요.
단순하게. 100줄로 될 것을 1,000줄로 만들었으면 실패예요.
시킨 것만 건드린다. 이해 못 하는 주석을 지우거나, 옆 코드를 「정리」하거나, 사양에 없는 기능을 「있으면 좋을 것 같아서」 넣지 않아요.
확인 없이 끝났다고 하지 않는다. 테스트 통과·빌드 출력·실행 결과 중 하나는 있어야 해요.

이 여섯 가지는 사실 플러그인 없이도 프롬프트에 적어 둘 수 있는 내용이에요. 이 플러그인의 값은 그걸 매 세션 잊지 않게 자동으로 넣어 준다는 데 있어요.

그만큼 늘어나는 토큰은 얼마인가

앞의 첫 글에서 본 claude plugin details 출력에 비용 추정이 같이 나와요. 이 글을 쓰면서 설치된 환경에서 실제로 뽑은 숫자예요.

항목	토큰(추정)	언제 드나
항상 켜져 있는 몫	약 2,800	모든 세션에
code-review-and-quality	약 7,300	`/review` 등으로 켤 때마다
security-and-hardening	약 7,300	보안 검토가 붙을 때마다
test-driven-development	약 5,800	`/test`·`/build` 마다
doubt-driven-development	약 5,800	의심 검토가 돌 때마다
interview-me	약 5,000	요구 인터뷰가 돌 때마다
spec-driven-development	약 3,000	`/spec` 마다

「항상 켜져 있는 몫」은 스킬 24개와 에이전트 4개의 설명 문장을 매 세션 싣는 비용이에요. 하루에 세션을 열 번 열면 그것만으로 약 28,000토큰이 더 들어요. 여기에 스킬이 실제로 켜질 때마다 오른쪽 숫자가 얹혀요. /ship 처럼 에이전트 셋을 동시에 돌리는 명령은 한 번에 그 몇 배가 들어요.

정액 구독(Pro·Max)을 쓰는 분은 이게 돈이 아니라 사용량 한도로 체감돼요. 큰일이 아닐 때는 플러그인을 통째로 잠시 끄는 방법이 있어요. 스킬 하나만 끄는 명령은 확인하지 못했어요.

claude plugin disable agent-skills@addy-agent-skills   # 끄기
claude plugin enable agent-skills@addy-agent-skills    # 다시 켜기

안 되는 경우

사람이 없는 자리에서는 안 되는 스킬이 있어요. interview-me 는 「살아 있는 사용자가 필요하다. CI·예약 실행·/loop 같은 비대화형에서는 부르지 말고 막힌 것으로 보고하라」고 스킬 안에 적혀 있어요. doubt-driven-development 도 비대화형에서는 다른 모델에 묻는 단계를 건너뛰고 「건너뛰었다」고만 적어요.
서브에이전트 안에서는 의심 검토가 안 돌아요. doubt-driven-development 는 새 검토자를 띄우는 구조라, Claude Code 가 서브에이전트 안에서 또 서브에이전트를 못 띄우는 제약에 걸려요. 스킬 자체가 「그 경우 사용자에게 알리고 메인 세션에서 하라」고 안내해요.
스킬은 강제가 아니에요. 설명을 읽고 모델이 고르는 방식이라, 「빨리 해 줘」라고 하면 스킬들이 스스로 물러나요. 여러 스킬이 「사용자가 속도를 원하면 쓰지 않는다」를 예외로 적어 두고 있어요. 꼭 태우려면 슬래시 명령으로 부르세요.
스킬끼리 겹치는지를 사용자가 확인할 방법은 없어요. 저장소는 설명 문장이 서로 부딪히지 않는지 자동 평가로 검사한다고 하지만, 그건 저장소 쪽 검사예요. 내 컴퓨터에서 어느 스킬이 왜 켜졌는지는 대화 안에서 스킬 이름이 보일 때만 알 수 있어요.

이럴 땐 다른 것을 보세요

한 번 돌리고 버릴 스크립트, 하루짜리 시제품에는 이 플러그인의 절차가 다 짐이에요. 사양·계획·테스트·검토가 전부 「나중에도 이 코드가 살아 있다」를 전제로 하기 때문이에요.

긴 일을 통째로 맡기고 돌아와서 결과만 보고 싶다면 같은 종류의 다른 묶음이 더 맞을 수 있어요. 저장소의 비교 문서가 스스로 이렇게 정리해요.

Agent Skills — 사양부터 출시까지 전 과정을 단계마다 사람이 확인하며 가는 데 맞다
Superpowers(obra) — 서브에이전트가 작업 하나씩 구현하고 검토자가 승인하는, 자율적이고 긴 작업에 맞다. 범위는 좁고 깊다
Matt Pocock 의 skills — 한 사람이 매일 쓰는 도구를 공개한 것. 요구사항을 한 질문씩 캐묻는 「grill me」 가 강점이고 Claude Code 우선이다

같은 문서에 한 개발자가 같은 모델·같은 저장소·같은 요청으로 Agent Skills 와 Superpowers 를 비교한 실험이 소개돼 있어요. Agent Skills 가 코드에 더 빨리 들어가고(약 8분 대 12분) 검증을 더 여러 번 돌렸다는(7회 대 5회) 결과인데, 문서 스스로 **「한 사람의 한 작업 실험이고 벤치마크가 아니다」**라고 적어 두었어요. 그대로 받아들이시면 돼요.

✔ 요약

알아서 켜지는 경로는 둘 — 세션 시작 훅(안내 스킬 주입)과 스킬 설명 매칭
명령 없이 자주 붙는 것: context-engineering · source-driven · doubt-driven · git-workflow
항상 지키는 여섯 가지: 가정 공개, 멈춤, 반대, 단순함, 범위, 검증
비용: 항상 약 2,800토큰 + 켜질 때마다 3,000~7,300토큰
비대화형·서브에이전트 안에서는 안 되는 스킬이 있다
일회성 코드에는 안 맞고, 자율적인 긴 작업은 Superpowers 쪽이 더 맞다고 저장소가 스스로 말한다
2026년 9월 기준, 플러그인 버전 0.6.6

확인할 곳: addyosmani/agent-skills · using-agent-skills 스킬 원문 · 비교 문서 docs/comparison.md · Claude Code — Skills · Claude Code — Plugins