Claude Code·Codex 에이전트 스킬 추천: 무엇을 설치할지, 설치 전 저장소 점검, 새 스킬이 작동 안 할 때 해결법

Name

Soren Atelier

업데이트 2026. 11. 15.

요약: 저장소를 통째로 설치하지 말고 스킬 몇 개만 설치하세요. 규칙은 세 가지입니다.

1. 용도에 맞게 고르세요. obra/superpowers(스킬 15개) 같은 작은 텍스트 전용 팩이나 Jane Street의 socratic-tutor 같은 단일 스킬로 시작하세요. google/skills(스킬 203개)나 NVIDIA/skills(452개) 같은 카탈로그는 그 안의 특정 스킬 하나가 필요해질 때까지 건드리지 마세요.
2. 설치 전에 읽어 보세요. 스킬은 지침에 선택적으로 스크립트가 붙은 것이고, 스크립트는 에이전트의 권한으로 실행됩니다. 아래 1단계의 점검 스크립트는 어떤 스킬이 코드를 포함하는지, 어떤 파일부터 열어 봐야 하는지 알려 줍니다. 파일을 읽기만 합니다.
3. 설치 후에는 스킬 목록을 확인하세요. Claude Code는 모델에게 스킬 이름과 설명 목록을 보여 주는데, 이 목록에는 상한이 있습니다. 이미 스킬이 98개 있던 머신에서는 새로 설치한 스킬이 이름만 목록에 올라갔고, 모델에게는 요청과 맞춰 볼 설명이 없었습니다. /skill-doctor를 실행한 뒤 skillOverrides로 예산을 비우거나 skillListingBudgetFraction으로 예산을 늘리세요.

테스트한 범위: 이 글의 모든 수치는 2026년 11월 15일에 받은 shallow clone과 macOS의 Claude Code 2.1.325에서 나왔습니다. 점검 스크립트, claude plugin validate, /skill-doctor, 디버그 로그는 모두 직접 실행했습니다. 그 뒤에 모델이 스스로 스킬을 고르는지는 테스트하지 않았고, SkillSpector, npx skills 설치 도구, Codex도 테스트하지 않았습니다. 글 끝부분의 "테스트한 것과 문서 기준인 것" 표에서 둘을 구분해 두었습니다.

스킬 저장소 10개 비교

에이전트 스킬은 SKILL.md 파일이 들어 있는 폴더이고, Claude Code, Codex 등 여러 에이전트가 필요할 때 불러옵니다. 경로, frontmatter, 두 도구에서 스킬 하나를 함께 쓰는 방법 같은 형식 자체는 이 글의 범위가 아닙니다. 이 글은 다른 사람이 만든 스킬을 고르고 설치하는 방법을 다룹니다.

스킬 저장소에 대한 관심은 11월 초에 크게 늘었습니다. Jane Street가 11월 3일에 스킬 하나짜리 저장소를 공개했고, Hacker News에서 712포인트를 받았습니다. GoogleChrome/modern-web-guidance는 11월 10일에 1.0.0을 냈습니다. anthropics/skills는 일주일 만에 스타가 약 6,200개 늘었습니다.

아래 표는 각 저장소의 모든 SKILL.md를 센 결과입니다. "설명 글자 수"는 description 텍스트의 총 길이로, 에이전트가 매 턴마다 모든 스킬에 대해 불러오는 부분입니다. 마지막 열은 이 값을 테스트 머신에서 Claude Code가 보고한 30,000자 목록 예산과 비교한 것입니다.

눈에 띄는 점은 세 가지입니다.

• 크기 차이가 100배 수준입니다. google/skills나 NVIDIA/skills를 전부 설치하면 목록 예산을 몇 배나 넘깁니다. 두 저장소의 README 모두 스킬을 하나씩 설치하는 방법을 안내합니다. NVIDIA는 --skill 옵션으로, Google은 설치 프로그램의 선택 프롬프트로 고릅니다.
• 대부분의 스킬은 순수 Markdown입니다. 782개 스킬 중 552개는 코드가 전혀 없습니다. 코드가 있는 스킬은 문서, 미디어, 클라우드 쪽에 몰려 있고, 스크립트가 결정적인 작업을 맡습니다.
• 도구를 미리 승인하는 스킬은 한 카탈로그 밖에서는 드뭅니다. allowed-tools를 선언한 스킬은 NVIDIA/skills에 126개, google/skills에 2개입니다. 나머지 여덟 저장소에는 없습니다.

용도별 추천

• obra/superpowers는 완결된 작업 방식입니다. 브레인스토밍, 계획 작성, 실행, 체계적 디버깅, 완료를 선언하기 전 검증까지 다룹니다. 컨텍스트 비용 기준으로는 큰 팩 중 가장 쌉니다.
• addyosmani/agent-skills는 엔지니어링 체크리스트 모음에 가깝습니다. 코드 리뷰, API 설계, CI, 관측성, 보안 강화를 다룹니다. 설명이 더 길어서 스킬 25개의 비용이 Superpowers의 약 4배입니다.
• mattpocock/skills는 직접 호출하는 짧은 명령(/grill-me, /tdd, /to-spec) 중심입니다. in-progress 스킬이 8개 들어 있습니다.
• anthropics/skills는 레퍼런스 세트입니다. 데이터 작업을 하는 사람은 보통 xlsx, pdf, docx, pptx 스킬을 찾는데, 실제로 파일을 만드는 스크립트가 함께 들어 있습니다. 분석을 노트북에서 한다면 RunCell (opens in a new tab)처럼 Jupyter 안에서 동작하는 에이전트가 이 파일 스킬들이 다루지 못하는 부분을 맡습니다.
• GoogleChrome/modern-web-guidance는 가이드 인덱스를 검색하는 CLI가 뒷받침하는 스킬 2개입니다. 에이전트가 오래된 프런트엔드 패턴을 쓰지 않게 하는 것이 목적입니다.
• kajisho5/ffmpeg-skill은 코드 파일 107개가 딸린 큰 스킬 하나가 두 위치에 미러링되어 있고, 여기에 작성자 본인의 프로젝트 스킬 14개가 .claude/skills 아래에 더해진 구성입니다. 저장소를 복사하지 말고 전용 설치 도구로 설치하세요.

1단계: 설치 전에 스킬 저장소 점검하기

스킬의 지침은 에이전트의 컨텍스트에 들어가고, 스크립트는 세션이 가진 권한 그대로 실행됩니다. 방어 수단은 저장소를 먼저 읽는 것뿐이니, 읽는 일을 빠르게 만들어야 합니다.

아래 스크립트는 폴더를 훑어 모든 SKILL.md를 찾고, 어떤 스킬이 코드를 포함하는지와 어떤 스킬에 살펴볼 만한 패턴이 있는지 출력합니다. Python 표준 라이브러리만 쓰고, 스캔하는 폴더의 어떤 것도 실행하지 않습니다.

#!/usr/bin/env python3
"""Read-only audit of SKILL.md folders. Runs nothing from the repo it scans."""
import os, re, sys
 
RISKY = {
    "pipe-to-shell": r"(curl|wget)[^\n|]*\|\s*(sudo\s+)?(ba|z)?sh",
    "reads-secrets": r"\.ssh/|\.aws/credentials|\.env\b|id_rsa|\.netrc|keychain",
    "sudo": r"\bsudo\s",
    "rm-rf": r"\brm\s+-[a-zA-Z]*r[a-zA-Z]*f|\brm\s+-[a-zA-Z]*f[a-zA-Z]*r",
    "skip-permissions": r"dangerously-skip-permissions|bypassPermissions|--yolo",
    "hidden-unicode": r"[\u200b\u200c\u200d\u2060\u202a-\u202e\U000e0000-\U000e007f]",
}
CODE = (".py", ".sh", ".js", ".mjs", ".ts", ".rb", ".ps1")
 
def frontmatter(text):
    m = re.match(r"^---\n(.*?)\n---\n?", text, re.S)
    if not m:
        return None, text
    fields, key = {}, None
    for line in m.group(1).splitlines():
        k = re.match(r"^([A-Za-z_-]+):\s*(.*)$", line)
        if k:
            key = k.group(1)
            fields[key] = k.group(2).strip().strip("\"'")
        elif key and line.startswith((" ", "\t")):
            fields[key] += " " + line.strip()
    return fields, text[m.end():]
 
def audit(root):
    rows = []
    for folder, dirs, files in os.walk(root):
        dirs[:] = [d for d in dirs if d not in (".git", "node_modules")]
        if "SKILL.md" not in files:
            continue
        text = open(os.path.join(folder, "SKILL.md"), encoding="utf-8", errors="replace").read()
        fields, body = frontmatter(text)
        everything, code_files = text, 0
        for sub, _, names in os.walk(folder):
            for n in names:
                if n.endswith(CODE):
                    code_files += 1
                if n.endswith(CODE + (".md",)) and n != "SKILL.md":
                    try:
                        everything += open(os.path.join(sub, n), encoding="utf-8", errors="replace").read()
                    except OSError:
                        pass
        flags = [name for name, pat in RISKY.items() if re.search(pat, everything)]
        if fields is None:
            flags.append("no-frontmatter")
            fields = {}
        if fields.get("allowed-tools"):
            flags.append("allowed-tools")
        if "hooks" in fields:
            flags.append("hooks")
        if re.search(r"!`[^`]+`|```!", body):
            flags.append("shell-injection-block")
        desc = (fields.get("description", "") + " " + fields.get("when_to_use", "")).strip()
        rows.append((os.path.relpath(folder, root), len(desc), len(body), code_files, flags))
    return rows
 
if __name__ == "__main__":
    rows = audit(sys.argv[1])
    listing = sum(d for _, d, _, _, _ in rows)
    print(f"{len(rows)} skills, {listing:,} description chars (~{listing // 4:,} tokens if all are listed)")
    print(f"{sum(1 for r in rows if r[3])} skills ship code files, {sum(r[3] for r in rows)} code files in total")
    for path, desc, body, code, flags in sorted(rows, key=lambda r: (-len(r[4]), r[0])):
        if flags or "-v" in sys.argv:
            print(f"  {path}: desc={desc} body={body} code={code} flags={','.join(flags) or '-'}")

저장소를 프로젝트 밖 어딘가에 clone한 뒤 스크립트에 경로를 넘기세요.

git clone --depth 1 https://github.com/obra/superpowers /tmp/superpowers
python3 audit_skills.py /tmp/superpowers

11월 15일 기준 Superpowers의 출력입니다.

15 skills, 2,317 description chars (~579 tokens if all are listed)
3 skills ship code files, 6 code files in total
  skills/brainstorming: desc=213 body=14933 code=3 flags=rm-rf
  skills/subagent-driven-development: desc=85 body=19484 code=0 flags=rm-rf
  skills/systematic-debugging: desc=91 body=9366 code=2 flags=reads-secrets

플래그 읽는 법

플래그는 "이 파일을 열어 보라"는 뜻이지 "이 스킬이 악성이다"라는 뜻이 아닙니다. 이 열 개 저장소에서 손으로 확인한 플래그는 모두 문제가 없었습니다. Superpowers의 rm-rf는 자기 임시 폴더를 정리하는 스크립트의 rm -rf "$SESSION_DIR"입니다. ffmpeg-skill의 hidden-unicode는 힌디어 합자에 관한 메모 안의 zero-width joiner입니다. reads-secrets는 .env가 언급되기만 해도 걸리며, 커밋하지 말라는 조언도 포함됩니다.

Claude Code에서는 마지막 세 가지가 가장 중요합니다. allowed-tools는 스킬을 호출한 턴 동안 묻지 않고 도구를 허용합니다. hooks 항목은 세션이 끝날 때까지 계속 실행됩니다. !`command` 블록은 스킬이 로드될 때 실행됩니다.

추가 확인 두 가지

Claude Code가 frontmatter를 검증해 줄 수 있습니다. 설치된 스킬 91개가 든 폴더에서는 문제 없이 통과했습니다. 플러그인으로 패키징되지 않은 저장소에서는 No manifest found로 실패하는데, 이는 그 저장소가 복사 전용이라는 뜻입니다.

claude plugin validate .claude/skills

더 깊이 스캔하려면 NVIDIA의 SkillSpector (opens in a new tab)가 있습니다. 71개 패턴과 0-100 위험 점수를 갖춘 전용 스캐너입니다. README는 아래를 빠른 사용법으로 안내합니다. 이 글에서는 실행하지 않았습니다.

uv tool install git+https://github.com/NVIDIA/skillspector.git
skillspector scan ./my-skill/ --no-llm

2단계: 필요한 것만 설치하기

폴더 하나를 복사하는 것이 변수가 가장 적은 설치 방법이고, 이 글에서 테스트한 방법입니다.

git clone --depth 1 https://github.com/janestreet/agent_skills /tmp/agent_skills
mkdir -p .claude/skills
cp -R /tmp/agent_skills/socratic-tutor .claude/skills/

복사한 위치에 따라 스킬이 로드되는 범위가 정해집니다.

시험 삼아 써 보는 스킬은 프로젝트 폴더에 두세요. 다른 세션에는 영향을 주지 않고, 폴더를 지우면 스킬도 사라집니다.

나머지 두 경로는 각 프로젝트의 README에서 가져온 것이며 여기서는 실행하지 않았습니다.

• 플러그인은 팩 전체를 설치하고 /plugin에서 업데이트합니다. 예를 들어 /plugin marketplace add anthropics/skills를 실행한 뒤 /plugin install document-skills@anthropic-agent-skills를 실행합니다. Superpowers는 /plugin install superpowers@claude-plugins-official입니다.
• Vercel Labs의 skills CLI는 여러 에이전트용 파일을 한 번에 프로젝트로 복사합니다: npx skills add addyosmani/agent-skills --skill test-driven-development -a claude-code. 먼저 둘러보려면 --list를 붙이세요.

Claude Code 문서에 나오는 주의점이 하나 있습니다. skillOverrides는 플러그인 스킬에 적용되지 않습니다. 플러그인 팩이 너무 크면 개별 스킬이 아니라 플러그인을 비활성화해야 합니다.

3단계: 새 스킬이 실제로 목록에 올라갔는지 확인하기

이 단계는 "설치했는데 작동 안 함"의 원인 가운데 오류 메시지가 전혀 나오지 않는 한 가지를 잡아냅니다.

Claude Code는 모든 스킬의 이름과 설명을 담은 목록을 모델에게 줍니다. 이 목록에는 예산이 있고, 기본값은 컨텍스트 윈도의 1%입니다. 예산을 넘으면 Claude Code는 이름은 모두 유지하되 가장 적게 쓴 스킬부터 설명을 뺍니다. 방금 설치한 스킬은 사용 횟수가 0입니다. 이 메커니즘은 Claude Code 문서의 스킬 설명이 잘리는 경우(Skill descriptions are cut short) (opens in a new tab) 절에 설명되어 있고, 아래 수치는 실제로 어떻게 나타나는지 보여 줍니다.

개인 스킬 84개와 플러그인 스킬 14개가 이미 있던 머신에서는 이렇게 나타났습니다. 새 스킬 하나를 복사해 넣자 디버그 로그에 다음이 찍혔습니다.

[WARN] Skill listing over budget: 112 skills, 37491 chars > 30000 budget — descriptions will be truncated.

그리고 /skill-doctor에서는 새 스킬이 이름만 올라간 것으로 표시되었습니다.

비용이 < 20이라는 것만으로는 증거가 되지 않습니다. 설명이 한 줄뿐인 스킬도 비용이 20 미만이기 때문입니다. 설명 길이와 함께 비교하세요. 아래 수치에는 설명이 충분히 길어서 판별할 수 있는 스킬만 넣었습니다.

스킬을 더 추가하면 나머지 스킬까지 나빠졌습니다. 프로젝트 스킬 91개를 설치했을 때는 76개가 목록에 올라갔고, 그중 70개는 80자 이상인 설명이 빠져 있었습니다. 289개일 때는 설명이 빠진 개인(personal) 스킬이 6개에서 39개로 늘었습니다. 새로 들어온 스킬이 잘 동작하던 스킬의 설명을 밀어낸 것입니다.

확인 실행하기

/skill-doctor는 스킬마다 한 줄씩 목록 비용을 출력합니다. Claude Code 2.1.252 이상이 필요하고 -p 모드에서도 동작합니다.

claude -p "/skill-doctor"

예산 경고 자체를 보려면 디버그 로그를 남기고 검색하세요.

claude --debug-file /tmp/cc-debug.log -p "hello"
grep "Skill listing over budget" /tmp/cc-debug.log

고치기

먼저 쓰지 않는 스킬을 끄세요. 프로젝트 단위라면 .claude/settings.json에, 모든 프로젝트에 적용하려면 ~/.claude/settings.json에 넣습니다.

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

"name-only"는 스킬을 /name으로 호출할 수 있게 둔 채 목록에서 설명만 뺍니다. "off"는 스킬을 완전히 숨깁니다. 대화형 세션에서는 /skills가 같은 설정을 기록합니다. 행에서 Space를 눌러 상태를 차례로 바꾼 뒤 Esc를 눌러 저장하세요.

정말로 전부 쓴다면 예산을 늘리세요. 대신 매 턴마다 컨텍스트를 더 씁니다.

{
  "skillListingBudgetFraction": 0.02
}

Codex에도 수치만 다른 같은 메커니즘이 있습니다. Codex 문서에 따르면 초기 스킬 목록은 컨텍스트 윈도의 최대 2%를 쓰고, 윈도 크기를 모를 때는 8,000자를 씁니다. 먼저 설명을 줄이고, 경고와 함께 일부 스킬을 목록에서 뺄 수도 있습니다. skills.max_context_tokens로 예산을 바꾸고, ~/.codex/config.toml에 enabled = false인 [[skills.config]] 항목을 넣으면 스킬 하나를 비활성화합니다.

4단계: 스킬을 무인으로 실행하기

11월 13일에 나온 Claude Code 2.1.325는 예약 작업에 영향을 주는 동작 하나를 바꿨습니다. 이제 예약 작업과 /loop는 allowed-tools나 훅을 선언한 스킬을 실행하기 전에 물어봅니다. 그런 스킬을 프롬프트 없이 실행하려면 이름으로 허용하세요.

{
  "permissions": {
    "allow": ["Skill(release-notes)"]
  }
}

반대 방향도 됩니다. Skill(deploy *) 같은 deny 규칙은 모델이 스킬을 호출하지 못하게 막고, 인자 없이 Skill을 deny하면 모든 스킬이 꺼집니다. 둘 다 Claude Code 문서에 나온 내용입니다. 저장소에 커밋해 둘 만한 나머지 권한 설정은 Claude Code 권한 강화 글에서 다룹니다.

5단계: 스킬 제거하기

• 복사한 스킬: .claude/skills/ 또는 .agents/skills/ 아래의 해당 폴더를 삭제합니다.
• 플러그인 스킬: /plugin uninstall <plugin>@<marketplace>를 실행하거나 /plugin에서 비활성화합니다.
• 남겨 두되 자동 사용만 막기: skillOverrides에서 "name-only"나 "off"로 설정합니다. 파일을 직접 관리한다면 frontmatter에 disable-model-invocation: true를 추가해도 됩니다.

테스트한 것과 문서 기준인 것

30,000자 예산은 머신 한 대가 보고한 값입니다. 실제 값은 모델의 컨텍스트 윈도에 따라 달라지므로, 비율 열을 믿기 전에 본인의 디버그 로그를 확인하세요.

FAQ

Claude Code에서 어떤 에이전트 스킬을 먼저 설치해야 하나요?

작게 시작하세요. obra/superpowers는 계획, 테스트, 디버깅, 리뷰 워크플로 전체를 스킬 15개로 제공합니다. addyosmani/agent-skills는 엔지니어링 체크리스트 25개를 더합니다. 스프레드시트, PDF, 슬라이드에는 anthropics/skills의 document-skills 플러그인을 설치하세요. 큰 카탈로그는 통째로 설치하지 말고 필요한 스킬만 하나씩 설치하세요.

새로 설치한 Claude Code 스킬이 왜 작동하지 않나요?

스킬이 많은 머신이라면 목록이 예산을 넘어서 새 스킬이 이름만 올라갔을 가능성이 큽니다. /skill-doctor를 실행하세요. 설명이 긴 스킬인데 컨텍스트 비용이 20 미만이면 설명이 빠진 것입니다. skillOverrides로 쓰지 않는 스킬을 끄거나 skillListingBudgetFraction을 늘리세요.

스킬을 설치하기 전에 안전한지 어떻게 확인하나요?

프로젝트 밖에 clone해서 읽어 보세요. 번들 스크립트, allowed-tools, hooks, !`command` 블록을 찾습니다. 위의 점검 스크립트는 아무것도 실행하지 않고 모든 SKILL.md에 대해 이를 나열합니다.

Claude Code에서 스킬은 몇 개부터 너무 많은가요?

개수가 아니라 설명 길이에 달려 있습니다. anthropics/skills의 스킬 20개는 30,000자 예산 중 약 9,500자를 씁니다. google/skills 전체는 약 107,600자가 필요합니다.

/skill-doctor는 무엇을 하나요?

로드된 모든 스킬을 출처, 목록 비용, 7일간 토큰 사용량, 호출 횟수와 함께 출력하고, 한 번도 쓰지 않은 스킬을 표시합니다. Claude Code 2.1.252 이상이 필요합니다.

Claude Code와 Codex가 모두 쓸 수 있게 하려면 스킬을 어디에 두나요?

Claude Code는 .claude/skills/, Codex는 .agents/skills/이고, 프로젝트나 홈 디렉터리에 둡니다. 사본은 하나만 두고 다른 쪽에는 심볼릭 링크를 거세요.

스킬을 삭제하지 않고 비활성화할 수 있나요?

네. Claude Code 설정의 skillOverrides를 쓰거나, Codex에서는 enabled = false인 [[skills.config]]를 씁니다. 플러그인 스킬은 /plugin으로 관리합니다.

Claude Code 2.1.325에서 예약 작업이 스킬을 실행하기 전에 왜 물어보나요?

이제 예약 작업과 /loop는 allowed-tools나 훅을 선언한 스킬을 실행하기 전에 물어봅니다. permissions.allow에 Skill(name)을 추가하세요.

출처

• Extend Claude with skills (opens in a new tab)와 settings reference (opens in a new tab), Claude Code 문서
• Claude Code changelog (opens in a new tab), 버전 2.1.325
• Build skills (opens in a new tab), Codex 문서
• Agent Skills specification (opens in a new tab)
• vercel-labs/skills (opens in a new tab)와 NVIDIA/SkillSpector (opens in a new tab) README
• Hacker News의 Socratic Tutor 스레드 (opens in a new tab)

관련 가이드

• Claude Code 권한 강화: 저장소 밖 쓰기 차단, 프롬프트 대신 거부, settings.local.json 점검
• Claude Code Mods 사용법: 첫 Mod 만들기·테스트·설치와 커뮤니티 예시 15선
• Claude Code AGENTS.md 사용법: CLAUDE.md 차이, 4가지 로딩 모드, Codex·OpenCode와 공유
• Codex 사용법 가이드: 시작 방법, 5가지 팁, 실전 베스트 프랙티스
• OpenCode 사용법 가이드: 시작 방법, 실전 팁 7가지, Oh My OpenCode와 함께 쓰는 법