Claude Code Skills 시스템 개선 제안서

작성일: 2026-02-28 22:45 작성자: 자비스 총괄이사 기반: YouTube "Claude Code Skills Are Broken (Beginner to Pro)" (Nate Herk) 분석 보고 대상: 머스크 VP, CEO 김준영

리서치 출처 (교차 검증 완료)

• Claude Code Skills Are Broken — Recapio 요약
• Scott Spence — Skills Not Recognised Fix
• GitHub Issue #9817 — Frontmatter 포맷 버그
• GitHub Issue #29441 — Team 스폰 Skills 미주입 (2026-02-27 오픈, 미해결)
• Anthropic 공식 Skills 문서
• Nate's Newsletter — 100명 관찰 기반 10대 문제

1. 영상 핵심 인사이트

1-1. "Skills Are Broken"이 의미하는 실제 문제 6가지

1-2. Nate Herk의 6단계 스킬 설계 프레임워크

1. Name & Trigger 정의 (언제 발동할지)
2. Goal 명시 (이 스킬이 달성하는 것)
3. Step-by-step 프로세스 (실행 순서)
4. Reference Files 식별 (필요한 참조 파일)
5. Rules & Constraints (금지/제한 규칙)
6. Self-improvement Loop (테스트-피드백-개선 사이클)

1-3. 공식 문서 최신 스펙 (2026)

• Progressive Context Loading: 초기에는 name+description만 로드, 발동 시 전체 로드
• disable-model-invocation: true: Claude 자동 발동 차단 (수동 전용 스킬용)
• user-invocable: false: 백그라운드 지식 스킬용 (슬래시 메뉴에서 숨김)
• context: fork: 독립 subagent로 스킬 실행 (기존 대화 컨텍스트 격리)
• !command`` 동적 인젝션: 스킬 실행 전 셸 커맨드 출력을 컨텍스트에 자동 삽입
• SKILL.md 500줄 이하 권장: 초과 시 supporting files로 분리

2. 우리 시스템 현황 진단

2-1. 현재 Skills 시스템 구조

.claude/skills/
├── jarvis-only/          # 자비스 전용 (~13개 파일)
│   └── jarvis-core.md    ← 핵심 운영지침 (단일 거대 파일)
├── shared/               # 공유 참조 (~12개 파일)
├── external/             # 외부 임포트 (~15개 파일)
└── *.md (루트 직속 ~7개 파일)

총 Skills 파일 수: 약 47개

2-2. 강점

2-3. 취약점 진단 (영상 인사이트 기반)

[취약점 1] YAML Frontmatter 누락 — 치명적

현재 jarvis-only/ 폴더 내 다수 파일이 frontmatter 없이 운영:

• session-start.md, task-management.md, team-management.md 등 대부분 해당
• 공식 스펙 기준: frontmatter 없으면 Claude가 자동 감지/발동 불가, 의도적 제어 불가

[취약점 2] Team 스폰 시 Skills 미주입 버그 (GitHub #29441, 2026-02-27 오픈)

우리 팀 운영 방식: Task tool → team_name: "jarvis-team" → PL 스폰

공식 버그 확인: team-spawned teammate는 skills: frontmatter가 있어도 스킬이 주입되지 않음. 현재 Open 상태, 미해결.

→ 우리 PL들이 스킬 컨텍스트 없이 작업 시작하고 있을 가능성 있음.

[취약점 3] 스킬 컨텍스트 예산 초과 위험

47개 파일 전체 메타데이터 총합이 컨텍스트 윈도우 2%(~4,000토큰) 초과 시 무음 누락 발생. 현재 어떤 스킬이 누락되는지 파악되지 않음.

[취약점 4] jarvis-core.md 단일 거대 파일

300줄+ 단일 파일. Anthropic 권장: 500줄 이하 + supporting files 분리.

[취약점 5] 피드백 루프 미구축

스킬이 실제로 올바르게 발동되는지 검증 체계 없음.

[취약점 6] disable-model-invocation 미활용

session-start.md, task-management.md 등 수동 전용 스킬에 자동 발동 차단 설정 없음.

3. 개선 제안 (우선순위별)

P1 즉시 실행 (이번 주)

P1-1. 핵심 Skills 파일 YAML Frontmatter 정비

우선순위 5개 파일 즉시 처리:

# session-start.md
---
name: session-start
description: 자비스 세션 시작 절차 — DB 현황 조회, CEO 브리핑, 맥락 복원, 텔레그램 점검. 세션 시작 시 수동 실행.
disable-model-invocation: true
---

# task-management.md
---
name: task-management
description: 자비스 태스크 관리 규칙 — Turso kanban DB 기반 생성/조회/상태변경. 태스크 조작 시 수동 실행.
disable-model-invocation: true
---

# coding-rules.md
---
name: coding-rules
description: 코딩 표준 규칙 — 금지 패턴, 에러 핸들링, DB 접근 규칙. 코드 작성 시 자동 적용.
user-invocable: false
---

# shared/db-schema.md
---
name: db-schema
description: Business Builder NeonDB 스키마 전체 참조 — tasks, okr_key_results, telegram_messages 테이블 구조.
user-invocable: false
---

# jarvis-core.md (인덱스 파일로 축소 예고)
---
name: jarvis-core
description: 자비스 총괄이사 핵심 운영지침 — 조직 구조, 4대 원칙. 세션 시작 필수 로드.
user-invocable: false
---

P1-2. Team 스폰 시 Skills 명시적 주입 워크어라운드

GitHub Issue #29441이 해결될 때까지 임시 대응:

모든 PL 프롬프트 맨 앞에 아래 보일러플레이트 추가:

[세션 시작 필수 — 다른 작업 전 먼저 실행]
다음 파일들을 Read tool로 순서대로 읽어라:
1. {business-builder-root}/.claude/skills/coding-rules.md
2. {business-builder-root}/.claude/skills/db-access-rules.md
3. {business-builder-root}/.claude/skills/shared/db-schema.md
(개발 PL 추가) 4. {business-builder-root}/.claude/skills/shared/available-agents.md

P1-3. 스킬 컨텍스트 예산 현황 점검

# 세션 내에서 실행
/context
# 또는 예산 확장
export SLASH_COMMAND_TOOL_CHAR_BUDGET=32000

P2 단기 (2주, VP 승인 후)

P2-1. jarvis-core.md 모듈 분리 (500줄 원칙)

분리 후 구조:

jarvis-only/
├── jarvis-core.md          ← 30줄 인덱스 파일
├── jarvis-okr.md           ← OKR 철학 + 실행 방법
├── jarvis-priorities.md    ← 현재 최우선 과업 (자주 업데이트)
└── jarvis-reporting.md     ← 보고 경로 + 커맨드 참조

P2-2. skill-health-check.md 신규 생성

주기적 Skills 시스템 점검 스킬:

• frontmatter 유효성 검사
• 컨텍스트 예산 초과 확인
• 미발동 스킬 식별
• PL Skills 주입 성공 여부 확인

P2-3. External Skills 참조 방식 개선

현재 외부 스킬 파일들 proper frontmatter 추가 후 Skill tool 직접 발동 방식으로 전환.

P3 중기 (1개월)

P3-1. 동적 컨텍스트 인젝션 (!command 패턴)

session-start.md에 적용 시:

## 현재 태스크 현황 (실시간)
!`psql "$DB_URL" -c "SELECT status, count(*) FROM tasks WHERE deleted_at IS NULL GROUP BY status"`

## 진행 중 맥락
!`psql "$DB_URL" -c "SELECT t.title FROM tasks t WHERE t.status = 'in_progress' LIMIT 5"`

→ 세션 시작 시 DB 상태 자동 주입, 수동 조회 불필요

P3-2. PL별 Skills 프로파일 정의

개발 PL 필수: coding-rules + db-access-rules + db-schema
리서치 PL 필수: available-agents + token-budget + seo-comprehensive

P3-3. Skills 자동화 테스트 케이스

각 스킬별 트리거 문구 + 기대 동작 + 검증 기준 문서화.

4. 예상 효과

5. 즉시 실행 체크리스트 (VP 검수 후)

□ P1-1: 핵심 5개 파일 frontmatter 추가 (session-start, task-management, coding-rules, db-access-rules, db-schema)
□ P1-2: team-management.md PL 프롬프트 보일러플레이트 교체 + MEMORY.md 반영
□ P1-3: /context 실행하여 현재 스킬 예산 초과 여부 확인
□ GitHub Issue #29441 모니터링 — Anthropic 공식 Fix 릴리스 대기
□ P2-1: jarvis-core.md 분리 (VP 별도 승인 후)

이 제안서는 자비스 총괄이사가 research-analyst 에이전트를 활용하여 작성하였습니다. GitHub Issue #29441은 우리 시스템에 직접 영향을 미치는 미해결 버그입니다. VP 즉시 검토 권장.