스킬 마이닝: 3,500개의 후보에서 466개의 역량으로

이 글의 수치는 게시 시점(2026년 1월) 기준입니다. 최신 수치는 팀 페이지를 참고하세요.

3,500개 스킬 문제

에이전트 오케스트레이션 시스템을 만들기 시작했을 때, 우리는 흥미로운 과제에 부딪혔습니다. AI 생태계 전반에는 수천 개의 잠재적인 스킬이 흩어져 있습니다. GitHub 저장소, 벤더 문서, 커뮤니티 프로젝트, 내부 패턴까지, 스킬은 어디에나 존재합니다. 하지만 어떤 것이 중요할까요? 어떤 것이 실제로 작동할까요? 그리고 에이전트가 실제로 쓸 수 있는 일관성 있는 스킬 라이브러리를 어떻게 유지할까요?

우리의 답은 체계적인 마이닝 및 수집 루프입니다.

오늘의 수치

Anthropic이 2025년 10월 16일 Agent Skills를 출시한 지 세 달이 조금 지난 시점, 이 글이 게시된 2026년 1월 27일 기준 우리의 상황은 다음과 같습니다.

지표	수치
확인된 후보	3,500개 이상
채택된 스킬	466개
벤더 스킬	373개
내부 스킬	93개
활성 벤더	25개 이상
스킬당 평균 토큰 수	2,834
참조된 도구	89개
고유 태그	635개

우리는 3,500개 이상의 스킬 후보를 검토했습니다. 그리고 466개를 채택했습니다. 채택률 13%입니다. 그리고 그 선별성은 의도적입니다.

지식 계층 체계

모든 스킬이 동등하게 만들어지지는 않습니다. 우리는 이를 다섯 개의 지식 계층(K0-K4)으로 조직하며, 각각은 서로 다른 적용 범위를 나타냅니다.

K0: Foundations (보편적)

모든 에이전트가 가져야 하는 스킬. “좋은 사고자” 역량을 나타내며 어디서든 작동합니다.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0 스킬은 어떤 프로젝트, 어떤 도메인, 어떤 스택으로도 이식 가능합니다. 보편적인 인지 패턴을 담고 있습니다.

K1: Identities (규율)

하나의 분야 안에서 여러 프로젝트에 걸쳐 적용되는 “좋은 엔지니어” 혹은 “좋은 연구자” 스킬.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domains (주제 전문성)

한 분야 안에서 이식 가능한 “좋은 데이터베이스 전문가” 혹은 “좋은 보안 엔지니어” 스킬.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (기술)

특정 기술 스택을 위한 “좋은 Supabase 사용자” 혹은 “좋은 Cloudflare 개발자” 스킬.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Project (조직)

우리 조직과 워크플로에 특화된 스킬.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

마이닝 루프

1단계: 발견

스킬은 어디에서나 옵니다.

벤더 저장소: AWS, Anthropic, Cloudflare, Supabase, 그리고 커뮤니티 기여자들이 스킬 모음을 공개합니다. 우리는 25개 이상의 벤더 루트를 추적합니다.

커뮤니티 프로젝트: GitHub은 Claude Code 템플릿, 에이전트 패턴, 워크플로 정의로 가득합니다.

내부 패턴: 우리 팀이 문제를 해결하면서 패턴이 나타납니다. 이들은 스킬로 공식화됩니다.

문서 마이닝: 기술 문서에는 종종 암묵적인 스킬 — 절차, 체크리스트, 결정 트리 — 이 담겨 있습니다.

발견은 계속됩니다. 우리는 공식 평가 전에 후보를 추적하기 위해 스킬 백로그를 사용합니다.

2단계: 평가

모든 후보는 동일한 채점 기준을 거칩니다.

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

다섯 가지 제품 기준을 모두 통과해야 합니다. 이것이 후보의 87%가 거절되는 이유입니다.

그런 다음 모든 후보는 별도의 신뢰 검토를 거칩니다. 우리는 공식 벤더 저장소, 잘 알려진 커뮤니티 관리자, 그리고 무작위 GitHub 저장소를 동등한 신뢰의 원천으로 취급하지 않습니다.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

신뢰할 수 있는 벤더는 더 가벼운 출처 검토를 받지만, 그렇다고 무사통과는 아닙니다. 신뢰할 수 없거나 알려지지 않은 출처는 더 깊은 수동 감사를 받으며, 우리는 번들 스크립트를 읽고, 범위를 파악하고, 안전하다고 분류하기 전까지는 실행하지 않습니다.

갭 분석: 채택하기 전에 우리는 레지스트리를 검색합니다.

uv run orkestra skills search "<capability>"

이미 갖고 있다면 필요 없습니다. 비슷한 것을 갖고 있다면 채택하는 대신 병합할 수도 있습니다.

깊이와 표준 점수화: 우리는 또한 후보가 에이전트-스킬 모델을 얼마나 완전히 활용하는지 점수를 매깁니다. 단독 SKILL.md도 여전히 유용할 수 있지만, agentskills.io이 권장하는 방식으로 지침과 참조, 스크립트, 자산을 분리하는 더 깊은 스킬이 더 가치 있습니다.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHub 스타는 신뢰도 점수를 조금 끌어올릴 수는 있지만, 얕거나 안전하지 않은 스킬을 구제하지는 못합니다. 하나의 모호한 SKILL.md와 불투명한 스크립트를 가진 스타 많은 저장소는, 정확한 설명과 잘 정리된 references/, 그리고 전체 스킬 역량을 실제로 활용하는 원자적 헬퍼를 가진 더 작은 저장소보다 낮은 점수를 받습니다.

구조적 분석: 우리는 스킬 품질을 확인합니다.

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

후보가 스크립트를 포함한다면, 그 검토는 더 엄격해집니다. 좋은 스킬은 그저 유용한 것이 아니라, 에이전트에게 넘겨주기에 읽기 쉽고, 범위가 명확하고, 안전해야 합니다. 이 안전성 필터 하나만으로도 그 외에는 흥미로운 상당수의 후보가 탈락합니다.

3단계: 수집

스킬이 평가를 통과하면 레지스트리에 들어갑니다. 하지만 스킬이 그대로 채택되는 일은 없습니다. 우리 시스템에 맞게 수정됩니다.

채택 시 수정 사항:

1. 메타데이터 정규화: 모든 스킬은 우리의 프런트매터 스키마를 갖게 됩니다
2. K-계층 배정: 스킬은 적절한 지식 계층에 배치됩니다
3. 태그 보강: 발견을 위한 태그가 추가됩니다
4. 도구 선언: 허용된 도구가 명시적으로 선언됩니다
5. 섹션 정렬: 내용이 우리 템플릿에 맞게 재구성됩니다

수집 후 일반적인 스킬 YAML입니다.

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

4단계: 스코프 배정

스킬은 스코프에 배정됩니다. 어떤 에이전트가 어떤 스킬을 로드할지 결정하는 카테고리입니다.

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

에이전트는 자신의 스코프를 선언하고, 스킬은 자동으로 배정됩니다.

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

5단계: 실체화

스킬은 프로덕션에서 YAML로 존재하지 않습니다. Claude Code가 로드할 수 있는 SKILL.md 파일로 렌더링됩니다.

uv run orkestra sync

이 명령은 다음을 수행합니다.

1. 모든 스킬 YAML 정의를 읽습니다
2. Jinja 템플릿을 통해 이들을 렌더링합니다
3. .claude/skills/에 SKILL.md 파일을 씁니다
4. K-계층별로 정리합니다(foundations/, identities/, domains/, stacks/, project/)

최종 출력 구조입니다.

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

휴면 스코프 패턴

우리의 가장 강력한 패턴 중 하나는 “채택되었지만 로드되지 않은” 스킬입니다. 우리는 이를 휴면 스코프라고 부릅니다.

k-dense-scientific 저장소의 과학 컴퓨팅 스킬을 생각해봅시다. 우리는 생물정보학, 화학, 양자 컴퓨팅, 임상 정보학을 다루는 120개 이상의 스킬을 채택했습니다. 하지만 우리 에이전트 대부분은 분자 도킹이나 유전자 발현 분석이 필요 없습니다.

120개의 스킬 모두를 모든 에이전트에 로드하는(컨텍스트 윈도우를 부풀리는) 대신, 우리는:

1. 특정 스코프(예: bioinformatics)로 스킬을 채택합니다
2. 등록되어 있지만 로드되지 않은 상태로 휴면 상태를 유지합니다
3. 에이전트가 그 스코프를 선언할 때만 활성화합니다

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

이 패턴 덕분에 일반적인 에이전트가 40~60개의 관련 스킬만 로드하면서도 레지스트리에는 466개의 스킬을 둘 수 있습니다.

스킬 유형

스킬은 세 가지 인지 패턴으로 나뉩니다.

워크플로

순서가 있는 절차적 단계: “1. X를 한다, 2. 그다음 Y를 한다, 3. 마지막으로 Z를 한다”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

규율

행동 가드레일: “항상 X를 하라”, “절대 Y를 하지 마라”, “Z를 선호하라”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

체크리스트

검증 기준: “X를 확인하라”, “Y를 검증하라”, “Z를 점검하라”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

품질 게이트

모든 스킬은 출시 전에 검증을 통과해야 합니다.

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

설명은 Claude Code가 언제 제안해야 할지 알 수 있도록 트리거 문구(“~할 때 사용”, “가 필요할 때“)와 함께 50400자 사이여야 합니다.

우리는 지속적으로 검증합니다.

uv run orkestra validate --show-warnings

벤더 생태계

우리의 373개 벤더 스킬은 다음에서 옵니다.

제공자	스킬 수	도메인
AWS Agent	19	클라우드 서비스
Anthropic	12	문서 생성
Cloudflare	8	엣지 컴퓨팅
Supabase	5	데이터베이스
k-dense	100개 이상	과학 컴퓨팅
silvainfm	4	데이터 사이언스
Java Developer Kit	45개 이상	Spring/Java
Vercel	1	브라우저 자동화

각 벤더 루트는 metadata.yaml에 선언됩니다.

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

orkestra sync이 실행되면, 벤더 스킬은 제공자 네임스페이스와 함께 .claude/skills/vendor/에 심링크됩니다.

우리가 배운 것

선별성은 보상받습니다. 유용해 보이는 모든 것을 채택하고 싶은 유혹이 있습니다. 하지만 스킬 하나하나는 토큰 비용이 듭니다. 스킬당 평균 2,834토큰이면, 비대함은 금방 타격을 줍니다. 우리의 13% 채택률은 에이전트를 가볍게 유지합니다.

구조는 발견을 가능하게 합니다. K-계층 체계는 단순한 정리가 아니라 이식성에 관한 것입니다. K0 스킬은 어디서든 재사용할 수 있습니다. K4 스킬은 의도적으로 프로젝트에 특화되어 있습니다. 이 명확성은 사람과 에이전트 모두가 필요한 것을 찾는 데 도움이 됩니다.

휴면 스코프는 규모를 키웁니다. 모든 것을 로드하지 않고도 수백 개의 스킬을 채택할 수 있습니다. 스코프는 개별 에이전트의 컨텍스트 윈도우를 관리 가능하게 유지하면서도 포괄적인 레지스트리를 구축할 수 있게 해줍니다.

채택 시 수정은 필수적입니다. 가공되지 않은 벤더 스킬은 여러분의 시스템에 좀처럼 딱 맞지 않습니다. 메타데이터 추가, 계층 배정, 태그 보강이라는 수집 과정이 외부 스킬을 내부적으로 작동하게 만듭니다.

마이닝은 계속됩니다. 3,500이라는 숫자는 계속 늘어납니다. 새로운 벤더 저장소가 나타납니다. 커뮤니티 패턴이 떠오릅니다. 내부 워크플로가 굳어집니다. 루프는 절대 멈추지 않습니다.

다음 단계

우리는 여러 개선 사항을 작업 중입니다.

1. 자동화된 갭 탐지: 흔한 에이전트 실패가 아직 채택되지 않은 스킬로 해결될 수 있을 때 알림
2. 스킬 폐기 워크플로: 대체되었거나 사용되지 않는 스킬을 은퇴시키는 공식 절차
3. 스킬 간 의존성: 스킬의 전제 조건을 명시적으로 선언
4. 사용량 분석: 에이전트가 실제로 호출하는 스킬과 그저 로드만 하는 스킬을 추적

스킬 마이닝 루프는 인프라입니다. 화려하지 않습니다. 하지만 이것이 41개의 에이전트가 컨텍스트 한계 안에 머물면서도 466개의 역량과 함께 일관되게 작동하게 만드는 것입니다.

그것이 3,500이 466이 되는 이야기입니다. 3,000개를 무시해서가 아니라, 체계적으로 평가하고 작동하는 것만 채택함으로써입니다.

---

스킬 시스템이 실제로 작동하는 모습을 보고 싶으신가요? 현재 우리 레지스트리를 살펴보려면 uv run orkestra skills list을 확인하세요.