초보자의 「AI Skill을 전부 파악하고 있나요?」

• 계기
• 파악하지 못하면 곤란한 점 2가지
• 애초에 스킬(Skill)이란 무엇인가?
• NVIDIA의 OSS로 139개를 전부 스캔했다
• --no-llm 모드의 함정
• 그래서 Opus로 재정밀 조사하는 2단계 플로우를 구축했다
• 모든 것을 파악해두고 싶은 사람을 위해
• 요약
• 참고

Claude Code를 사용하기 시작한 이후로, 편리해 보이는 스킬을 발견할 때마다 계속 추가하다 보니 어느새 139개가 되어 있었다.

게다가 이름만 봐서는 의미를 알 수 없는 것이 대량으로 존재한다. mobius-loop는 대체 무엇인가?

plan-ceo-review는 CEO가 구체적으로 무엇을 리뷰하고 무엇을 해주는 것인가? 나루토와 사스케가 병원에서 싸우기 시작하는 것을 지켜보는 사쿠라의 마음처럼, 전혀 파악하지 못하고 있다는 사실을 깨달았다.

하나는 보안(Security). 누군가가 만든 프롬프트(Prompt)를 거의 심사 없이 AI의 동작에 포함시키고 있다.

또 하나는 심리적 부담. "이 태스크, 스킬이 있었던 것 같은데 발동되지 않은 건가?"라는 불안이 항상 머릿속에 남는다. 파악하고 있지 않으니 확인할 방법도 없다.

그래서 정비하고 싶었던 것은 이것이다:

• 각 스킬이 무엇을 하는지 스스로도 알 수 있는 설명서
• 도입 전의 보안 스캔(Security Scan) - 스캔 → 설명서 기입 → 정기적인 재고 조사(Inventory)를
• 일관되게 돌릴 수 있는 플로우(Flow)

"스킬을 넣는다"는 것이 무엇을 하는 것인지 제대로 이해하지 못했기에 다시 처음부터 조사했다.

공식 문서에 따르면, 스킬은 프롬프트 파일(SKILL.md)을 에이전트(Agent)에게 전달하는 메커니즘이다.

~/.claude/skills/
└── my-skill/
└── SKILL.md ← 여기에 「이 스킬의 사용법·역할·제약」이 적혀 있다

Claude Code가 기동하면, 설치된 스킬의 이름과 description이 system-reminder에 모아서 전달된다. Claude는 그 정보를 바탕으로 "아, 이 스킬을 사용할 수 있겠구나"라고 판단하여 발동시킨다.

3단계의 단계적 공개 (Progressive Disclosure)

스킬은 기동 시에 전부 읽히는 것이 아니다.

• system-reminder에 name + description이 전달된다 (상시)
• 스킬이 사용될 것 같으면 SKILL.md의 본문이 읽힌다
• 필요에 따라 references/ 하위의 추가 파일이 읽힌다

컨텍스트(Context)를 절약하면서, 필요한 때에만 상세 내용을 전개하도록 설계되어 있다.

즉, 영창 생략(詠唱破棄) 같은 것이라고 할 수 있겠다.

Anthropic의 엔지니어링 블로그 「Equipping Agents for the Real World with Agent Skills」에서도 스킬을 "AI 에이전트가 실무에서 사용할 수 있는 실용적인 도구"로 정의하고 있다.

번외: 기왕이면 비슷한 것들을 비교해 보았다

정비를 시작하기 전, 참고가 될 만한 스킬 리포지토리(Repository). 둘 다 성격이 완전히 달라서 흥미롭다. addyosmani/agent-skills는 Google Chrome 엔지니어링 리드인 Addy Osmani 씨가 만든 리포지토리이다.

특징은 "시니어 엔지니어의 사고 플로우(Thinking Flow)"가 스킬화되어 있다는 점이다.

• /spec-writer → 요구사항 정의를 시니어 엔지니어의 관점에서 구조화한다
• /arch-review → 아키텍처를 여러 관점에서 비판적으로 평가한다
• /security-review → OWASP Top 10에 비추어 보안 심사를 한다

개인 개발에서는 "시니어 엔지니어가 옆에 없다"는 문제가 항상 존재한다. 이 스킬군은 그 빈자리를 채워주는 존재로서 기능한다.

gotalab/cc-sdd는 다른 접근 방식이다. Amazon Kiro(AI 구동 IDE)의 SDLC 파이프라인에서 착안하여, 요구사항 정의부터 구현까지 일관되게 흘려보낼 수 있는 스킬이다.

/kiro-impl이라는 명령어가 특징적이며, spec부터 구현까지 자율적으로 진행해 준다.

이 두 가지는 충돌하지 않는다. cc-sdd가 파이프라인의 골격을 제공하고, addyosmani/agent-skills가 각 단계에서 전문적인 사고를 보완한다. 조합해서 사용하는 것이 정답이라고 생각한다.

보안 스캔을 직접 수행하려고 하던 중, 딱 적당한 도구를 찾아냈다.

SkillSpector. NVIDIA가 만든 OSS (Open Source Software)로, AI 에이전트의 스킬에 포함된 취약점 및 악의적인 패턴을 탐지하는 보안 스캐너이다. Apache 2.0 라이선스. 스타(Star) 수 7,551개.

Research shows that

26.1% of skills contain vulnerabilities and 5.2% show likely malicious intent.

번역: 조사에 따르면, 스킬의 26.1%에 취약성이 있으며, 5.2%에서 악의적인 의도가 나타나는 것으로 나타났습니다.

라고 합니다. 위험하네요.

SkillSpector에는 두 가지 모드가 있다.

통상 모드 (Normal Mode): 정적 분석 (Static Analysis) + LLM (Large Language Model)을 통한 시맨틱 평가 (Semantic Evaluation)

--no-llm 모드: 키워드 패턴 매칭 (Keyword Pattern Matching)만 수행 (고속 · API 불필요)

이번에는 --no-llm 모드로 139개를 6개 배치 (Batch)로 나누어 병렬 스캔했다.

그랬더니 재미있는 일이 일어났다.

보안을 가르치는 스킬일수록 CRITICAL (심각) 판정이 나온다.

실제 사례:

security-reviewer (보안 검토 스킬)가 CRITICAL 100/100으로 "C2 프레임워크 지표 있음"이라고 판정되었다.

실제로 내용을 확인해보니, Metasploit 등의 도구 이름은 펜테스트 (Penetration Test) 참조표의 해설로서 적혀 있을 뿐이었다.

wordpress-pro가 CRITICAL이 된 이유는, WordPress 블록 표기법인 <!-- wp:... -->라는 주석이 "숨겨진 명령"으로 탐지되었기 때문이다.

키워드 매칭은 문맥을 읽지 않기 때문에, "위험한 것을 설명하는 것"과 "위험한 코드를 실행하는 것"을 구분할 수 없다.

--no-llm 모드의 한계를 보완하기 위해, SAFE 이외의 판정이 나오면 자동으로 Claude Opus가 재정밀 조사하도록 하는 플로우 (Flow)를 추가했다.

① SkillSpector --no-llm으로 스캔
↓
② SAFE 이외 → Opus에 "플래그된 부분의 코드와 탐지 이유"를 전달
...

결과적으로, 139개 스킬 전건 설치 가능. CRITICAL 판정이 나온 것들을 포함하여 모두 오탐 (False Positive)이었다.

여기서 기사 서두의 계기를 회수하자.

이름만 봐서는 의미를 알 수 없는 스킬이 대량으로 존재한다.

mobius-loop는 뭐지? plan-ceo-review는 무엇을 해주는 녀석이지? neta-trend는?

스킬이 발동하는 메커니즘을 떠올려 보길 바란다. Claude Code가 기동하면, 설치된 스킬의 이름만 system-reminder에 모아서 전달된다. Claude는 그 이름을 보고 "아, 이 스킬을 사용할 수 있구나"라고 판단하여 발동한다.

즉, Claude 측은 (이름으로부터) 의미를 추측할 수 있다. 하지만 나는 "그럼 CLAUDE.md에 모든 스킬의 설명을 적으면 되지 않나"라고 생각할지도 모른다. 하지만 그렇게 하면 매 세션마다 불필요한 컨텍스트 (Context)를 계속 소비하게 된다. 139개의 스킬 설명 = 추정 5,000~10,000 토큰이 항상 소비된다.

그래서 설계를 다음과 같이 했다:

① 인간용 풀 설명서 (~/.claude/SKILLS.md)

카테고리별로 정리한 완전판.

Claude Code 운용계 · 개발 · SRE 계 · 마케팅계 · Toriumi 개인용…… 등으로 분류하여, 각 스킬에 한 줄 설명과 "이렇게 사용한다"를 적었다. 재고 조사를 할 때 보는 용도다.

② AI용 미니멀 버전 (글로벌 CLAUDE.md에 추가)

이름만으로 의미를 추측할 수 없는 스킬들만 골라 한 줄씩 14개를 추가했다.

# Skills 활용 가이드
- handover: 세션 인계 기록을 ~/develop/nippo/ 에 저장한다
- mobius-loop: 여러 관점에서 문제를 순환적으로 심층 탐구하는 사고 프레임워크
...

분명히 이름으로 알 수 있는 스킬 (seo-audit, ab-test-setup, copywriting 등)은 추가하지 않는다. 컨텍스트 절약을 위해서다.

이번에 하고 싶었던 것은 "한 번 하고 끝"이 아니라, 새 스킬을 넣을 때마다 돌릴 수 있는 플로우를 만드는 것이었다.

새 스킬 발견
↓
SkillSpector로 스캔 (--no-llm)
...

이것으로 "일단 넣긴 했는데 정체가 뭔지 모르는" 스킬이 사라지게 된다.

너무 똑똑한 AI와 발을 맞추기 위한 노력도 중요하니까 말이야.

Claude Code의 스킬은 매번 이름만 로드된다. descriptions는 Claude가 추론할 수 있지만, 인간은 읽을 수 없다 -
139개나 넣어두면 스스로 파악할 수 없게 된다. 보안 리스크와 "스킬을 제대로 쓰고 있는지 불안한 문제"가 동시에 발생한다 -
**SkillSpector (NVIDIA OSS)**로 스캔 → Opus로 재정밀 조사하는 2단계 플로우를 구축했다. --no-llm 모드는 키워드 매칭 방식이라 오탐(False Positive)이 가득한데, Opus의 검토를 거침으로써 비로소 "진정한 위협인지"를 판단할 재료가 된다 - 결과는
전체 139건 설치 가능. CRITICAL 판정을 포함하여 전부 오탐이었다 -
SKILLS.md (인간용 풀 설명서)와 CLAUDE.md에 대한 미니멀한 추가 기입 (불명확한 이름의 14개만)이라는 2단계 전략으로 해결했다 - 새로운 스킬을 넣을 때마다 "스캔 → SKILLS.md 추가 기입"을 반복하는 운영 플로우로 정착시켜, 초보자로서의 노고(Toil)를 줄였다

• SkillSpector (NVIDIA GitHub) — AI 에이전트 스킬 보안 스캐너
• Claude Code Skills 공식 문서
• Anthropic Engineering Blog: Equipping Agents for the Real World with Agent Skills
• addyosmani/agent-skills — 시니어 엔지니어의 사고 플로우를 스킬화한 리포지토리
• gotalab/cc-sdd — Kiro에서 착안한 SDLC 파이프라인 스킬
• さくらの AI Engine — 향후 재정밀 조사 추론 기반의 후보

이번 재정밀 조사에는 Claude Opus를 사용했지만, 처음부터 SkillSpector의 LLM 모드를 사용할 수 있다면 될 문제다.

그래서 조만간 さくらの AI Engine을 추론 기반으로 사용해보고 싶다.

OpenAI SDK 호환이라 base_url을 바꾸는 것만으로 전환할 수 있고, 비용은 Claude의 약 1/20 수준이다.

데이터가 국내(일본)에서 완결된다는 점도 좋다(◎). 대량 스캔을 정기적으로 돌린다면 비용 측면에서 현실적인 선택지가 된다.

추가 사항

Sakana AI의 Sakana Fugu가 요즘 유행하고 있는데, 국산(일본산)이면서 이름도 너무 귀여워서 이쪽도 상황을 보며 사용해 나갈 수 있으면 좋겠다!