Agent Skills 딥다이브
— AI 에이전트 스킬을 npm처럼, 보안 검증까지 끼워서 깔아주는 레지스트리

1프로젝트 한줄 요약

tech-leads-club/agent-skills는 보안 검증을 거친 AI 에이전트 스킬만 모아둔 중앙 레지스트리 + 설치 CLI + MCP 서버다. npx @tech-leads-club/agent-skills 한 줄이면 19개 이상의 AI 코딩 에이전트(Claude Code, Cursor, Copilot 등) 어디에든 같은 스킬을 깔 수 있다.

2왜 주목받는가

13.4%라는 숫자의 출처

Snyk 보안 연구진이 ClawHub·skills.sh에 올라온 3,984개 스킬을 전수 조사(2026-02-05 기준)한 결과, 13.4%(534개)가 최소 1개 이상의 치명적 보안 이슈(멀웨어 배포·프롬프트 인젝션·시크릿 노출)를 가졌다. "별 많이 받은 레포니까 괜찮겠지"가 통하지 않는다는 게 핵심이다.

기존 방식 vs. 이 레포

3스킬 구성/기술 스택 전체 지도

언어 구성

※ 비율은 GitHub 언어 통계 기준이며 시점에 따라 변동될 수 있음.

빌드 · 런타임 스택

스킬 규약 (SKILL.md 컨벤션)

스킬 한 개는 디렉토리 하나다. 그 안의 SKILL.md가 본체이고, 보조 폴더가 따라붙는다.

# SKILL.md — YAML frontmatter + 마크다운 본문
---
name: aws-advisor
description: AWS 리소스 보안·비용을 점검할 때 사용
allowed-tools: [Bash, Read, Grep]
---

# 이 아래는 LLM이 따라야 할 행동 지침(자연어)
사용자가 AWS 점검을 요청하면:
1. `aws s3api get-bucket-policy`로 버킷 정책 확인
2. 퍼블릭 접근 차단 설정을 검사
3. 발견한 리스크를 표로 정리해 보고

보안 스택 (이 레포의 정체성)

4스킬 로딩 구조 심화 분석

시스템 구조도

설치 한 줄의 7단계 흐름

핵심 설계 패턴 ①: Progressive Disclosure (점진적 공개)

핵심 설계 패턴 ②: Content-Addressable Storage (콘텐츠 주소 저장)

모든 스킬은 이름이 아니라 내용의 해시값으로 식별된다. 같은 내용이면 같은 ID, 한 글자라도 다르면 다른 ID.

핵심 설계 패턴 ③: Adapter 패턴 (19+ 에이전트 분기)

에이전트마다 폴더 구조가 제각각이다. 이걸 switch 폭주 없이 깔끔하게 분리하는 게 어댑터 패턴이다. GoF 디자인 패턴 교과서에 나오는 그대로다.

핵심 설계 패턴 ④: 다층 방어 (Defense in Depth)

보안의 기본 원칙은 "한 줄 방어선에 의존하지 마라"다. 콘텐츠 해시가 우회돼도 심볼릭 링크 가드가 디렉토리 탈출을 막고, 그것도 뚫려도 감사 로그가 사후 추적을 가능하게 한다. PR 게이트 → 다운로드 검증 → 설치 격리 → 운영 로그까지 겹겹이 쌓아 한 겹이 뚫려도 다음 겹에서 막는다.

5디렉토리 구조 해부

스킬 디렉토리 표준: SKILL.md(본체, YAML frontmatter + 지침) + templates/(파일 템플릿) + references/(참고 문서). 경로는 packages/skills-catalog/skills/(category)/(skill)/ 형태로 카테고리별로 나뉜다.

6학습 포인트 (기술별)

A. Nx 모노레포 설계

배울 것: CLI + MCP 서버 + 카탈로그 + 문서를 한 레포에 모으고도 빌드가 빠른 이유 — 의존 그래프 기반 캐싱으로 변경된 부분만 다시 빌드한다. 여러 패키지를 한 곳에서 버전·릴리스까지 일관되게 관리하는 법.

B. MCP 서버 작성

배울 것: LLM이 직접 호출할 수 있는 도구를 stdio 위에 노출하는 패턴. 읽기 전용·로컬·경로 검증으로 위협 표면을 좁게 설계하는 방법. 한 번 만들면 Claude·Cursor·VS Code가 같은 도구를 쓴다.

C. Content-Addressable 무결성 설계

배울 것: 콘텐츠 해시(SHA-256) + 락파일로 "이 파일이 진짜 그 파일인가"를 보장하는 법. Git·도커·npm 락파일이 쓰는 바로 그 발상을 직접 구현으로 본다.

D. Adapter 패턴 (다형성 분기)

배울 것: 19개 에이전트마다 다른 폴더 구조를, switch 폭주 없이 공통 인터페이스 하나로 흡수하는 GoF 어댑터 패턴. 새 에이전트 = 어댑터 1개 추가(OCP, 개방-폐쇄 원칙)의 실전 예.

E. 공급망 보안 (Supply Chain Security)

배울 것: PR 게이트(Snyk Scan) → 다운로드 검증 → 설치 격리 → 감사 로그로 이어지는 다층 방어(Defense in Depth)의 실제 코드. "별 많이 받은 레포 = 안전"이 왜 틀렸는지, 무엇으로 대체해야 하는지.

F. CLI UX & 배포 자동화

배울 것: npx 한 줄 실행, 인터랙티브 위저드, 락파일 기반 재현, semantic-release 기반 자동 버전·배포까지 — 사람이 쓰기 좋은 CLI를 만드는 표준 흐름.

7시스템 요구사항 (사용 환경)

지원 에이전트 (19개 이상, 3티어)

※ 지원 목록은 README 기준이며 계속 추가되는 중. 정확한 최신 목록은 레포 README 확인.

8직접 해볼 수 있는 실습 과제

# 1. 어디에 깔렸나
ls ~/.claude/skills/

# 2. 스킬 본체 열어보기 (frontmatter 구조 관찰)
cat ~/.claude/skills/aws-advisor/SKILL.md

# 3. 락파일 — 버전·해시가 고정돼 있는지
cat .agents/.skill-lock.json

# claude_desktop_config.json
{
  "mcpServers": {
    "agent-skills": {
      "command": "npx",
      "args": ["-y", "@tech-leads-club/agent-skills-mcp"]
    }
  }
}

# my-skill/SKILL.md
---
name: changelog-writer
description: 커밋 로그로 CHANGELOG 항목을 만들 때 사용
allowed-tools: [Bash, Read, Edit]
---
사용자가 릴리스 노트를 요청하면:
1. `git log --oneline 직전태그..HEAD` 수집
2. feat/fix/docs로 분류
3. 사용자 친화 문장으로 CHANGELOG.md 상단에 추가

9관련 기술 심화 학습 로드맵

1주차: 스킬 개념 & 설치 체험

2주차: 보안 & 무결성

3주차: 아키텍처 & 패턴

4주차: MCP & 기여

10핵심 키워드 사전

11참고 링크

• GitHub 레포 — tech-leads-club/agent-skills
• npm 패키지 — @tech-leads-club/agent-skills
• 공식 문서 사이트 — agent-skills.techleads.club
• 릴리스 노트
• AGENTS.md — 기여자용 작업 규약
• Snyk ToxicSkills 보고서 (스킬 공급망 취약점 연구)
• OWASP Agentic Skills Top 10
• MCP (Model Context Protocol) 공식
• Nx 모노레포 공식 문서