에이전트 스킬 리팩토링: 컨텍스트 폭발에서 빠르고 신뢰할 수 있는 워크플로로

I’m happy to translate the article for you, but I’ll need the full text you’d like translated. Could you please paste the content (or the portion you want translated) here? I’ll keep the source line and all formatting exactly as you requested.

1️⃣ 근본 원인: 스킬을 문서처럼 다루기

첫 번째 함정은 매우 인간적이다:

“모든 것을 포함하면 모델이 언제나 필요한 것을 갖게 될 거야.”

그래서 도구당 하나의 Skill을 만들고, 각 Skill은 문서 덤프가 된다:

• 설정 단계
• API 레퍼런스
• 방대한 예시
• “X 하지 말라” 목록
• 2017년 이후 모든 엣지 케이스

그런 다음 “작은 UI가 있는 서버리스 함수 배포” 같은 작업은 다음을 끌어온다:

• Cloudflare Skill
• Docker Skill
• UI‑스타일링 Skill
• 웹‑프레임워크 Skill …

…그리고 모델은 이미 절반 정도 물에 빠진 상태로 작업을 시작한다.

Claude Code의 자체 문서에서는 Skill이 대화, 요청, 그리고 다른 Skill과 컨텍스트 윈도우를 공유한다고 경고한다—즉, 제어되지 않은 로딩은 직접적인 성능 비용이며(느려짐, 드리프트, “왜 명백한 부분을 무시하나요?”와 같은 현상으로 느껴진다).

핵심: 문제는 “정보 부족”이 아니다. “관련 없는 정보가 너무 많다”는 것이다.

2️⃣ 해결책: 점진적 공개 (세 레이어)

Claude Code 문서에서는 점진적 공개를 명시적으로 권장합니다: 필수 정보는 SKILL.md에 보관하고, 무거운 내용은 작업이 필요할 때만 로드되는 별도 파일에 저장합니다.

이는 세 레이어 시스템에 깔끔하게 매핑됩니다:

레이어 1 – 메타데이터 (항상 로드됨)

짧은 YAML 프런트머터에 name, description, 그리고 routing signal을 포함합니다. 책 표지와 소개글처럼 생각하면 됩니다—가르치는 것이 아니라 모델이 책을 열어볼지 결정하도록 돕는 것입니다.

레이어 2 – 진입점: SKILL.md (활성화 시 로드됨)

당신의 네비게이션 맵:

• Skill이 어떤 용도인지
• 언제 사용해야 하는지
• 따라야 할 고수준 단계
• 다음에 열어야 할 레퍼런스 파일

튜토리얼이 아니며, 위키도 아닙니다.

레이어 3 – 레퍼런스 및 스크립트 (필요할 때만 로드됨)

작고 집중된 파일들:

• 파일당 하나의 주제
• 파일당 약 200–300줄을 목표로 함
• 스크립트는 결정론적인 작업을 수행해 모델이 행동을 “설명”하는 데 토큰을 소모하지 않게 함

예시 폴더 구조

.claude/skills/devops/
├── SKILL.md
├── references/
│   ├── serverless-cloudflare.md
│   ├── containers-docker.md
│   └── ci-cd-basics.md
└── scripts/
    ├── validate_env.py
    └── deploy_helper.sh

3️⃣ “200‑라인 규칙”: 가혹하고, 다소 임의적이며, 이상하게 효과적

커뮤니티 리팩터 이야기에서 저자는 다음과 같은 강제 조건을 제시했습니다:

SKILL.md를 약 200줄 이하로 유지하세요.

그 이하로 만들 수 없으면, 엔트리 포인트에 너무 많은 내용을 넣고 있는 것입니다.

Claude 자체의 베스트 프랙티스 문서에서는 본문을 몇 백 줄 이하로 유지하고(그 한계에 다다르면 내용을 분할하라고) 권장하고 있습니다. “200줄”은 더 날카로운 기준입니다: 교과서가 아니라 목차를 작성하도록 강제합니다.

왜 효과가 있는가

• 모델이 엔트리를 빠르게 스캔할 수 있습니다.
• 다음에 로드할 레퍼런스 파일을 즉시 결정할 수 있습니다.
• 전체 “초기 로드”가 충분히 작게 유지돼 대화에 여유 공간이 남습니다.

훔쳐 쓸 수 있는 간단 테스트

1. 새 세션을 시작합니다(콜드 스타트).
2. Skill을 트리거합니다.
3. 첫 번째 활성화가 약 500줄 이상의 내용을 로드한다면, 설계가 범위를 새고 있는 것입니다.

4️⃣ 실제 사고 전환: 도구‑중심에서 워크플로우‑중심으로

대부분의 사람들이 놓치는 부분입니다.

도구‑중심 기술 (문제점)

cloudflare-skill
tailwind-skill
postgres-skill
kubernetes-skill

이들은 백과사전과 같습니다. 서로 잘 조합되지 않습니다.

워크플로우‑중심 기술 (추천)

devops          (배포 + 환경 + CI/CD)
ui-styling      (디자인 규칙 + 컴포넌트 패턴)
web-frameworks  (라우팅 + 프로젝트 구조 + SSR 함정)
databases       (스키마 설계 + 마이그레이션 + 쿼리 패턴)

이들은 개발 중 실제로 하는 일에 매핑됩니다.

워크플로우 기술은 다음 질문에 답합니다:

“이 작업 단계에 있을 때, 에이전트가 올바르게 행동하려면 무엇을 알아야 할까?”

—가 아니라—

“이 도구가 할 수 있는 모든 것이 무엇인가?”

이러한 재구성만으로도 컨텍스트 폭발을 거의 방지할 수 있습니다.

5️⃣ 최소 규모의 프로덕션‑등급 SKILL.md (예시)

아래는 의도적으로 작게 만든 진입점으로, 복사해서 커스터마이즈할 수 있습니다. 빠진 부분을 확인하세요: 긴 예시, 전체 문서, 그리고 “당신이 필요로 할 모든 것”.

---
name: ui-styling
description: Apply consistent UI styling across the app (Tailwind + component conventions). Use when building or refactoring UI.
---

# UI Styling Skill

언제 사용하나요

• 새 UI 컴포넌트를 시작할 때.
• 일관성을 위해 기존 컴포넌트를 리팩터링할 때.
• 디자인 시스템을 업데이트할 때.

High‑level workflow

1. 식별 the component or page that needs styling.
2. 실행 scripts/apply_tailwind.sh to scaffold Tailwind classes.
3. 참조 references/tailwind-utilities.md for utility‑class guidance.
4. 검증 with scripts/check_style.py to ensure no lint errors.

참고 파일 (필요 시 로드)

• references/tailwind-utilities.md – 승인된 유틸리티 및 패턴 목록.
• references/component-conventions.md – 명명 규칙, 폴더 구조 및 구성 규칙.

스크립트 (필요 시 로드)

• scripts/apply_tailwind.sh – Tailwind 클래스를 파일에 삽입합니다.
• scripts/check_style.py – 스타일 린팅을 실행하고 위반 사항을 보고합니다.

Quick tip

디자인 시스템을 이미 따르고 있는 컴포넌트라면 2단계를 건너뛰고 바로 검증 단계로 이동하세요.

### TL;DR Checklist

- **Metadata only** in the YAML front‑matter.  
- Keep `SKILL.md` **≤ 200 lines**.  
- Store heavy content in `references/` and `scripts/`.  
- Design Skills **around workflows**, not individual tools.  
- Test with a cold start; aim for **≤ 500 lines** on first load.

Apply this playbook, and you’ll watch your context window breathe again. 🚀

### When to use

- UI 컴포넌트나 페이지를 만들 때.  
- 일관된 간격, 타이포그래피, 반응형 동작이 필요할 때.  
- 기존 디자인 규칙에 맞춰야 할 때.

### Workflow

1. **Identify the UI surface** (page/component) and its constraints (responsive, dark mode, accessibility).  
2. **Apply styling rules** from the references—pick only what you need.  
3. **Validate the output** against the checklist.

### References (load only if needed)

- `references/design-tokens.md` — Spacing, font scale, colour usage  
- `references/tailwind-patterns.md` — Layouts, common utility combos  
- `references/accessibility-checklist.md` — Keyboard, focus, contrast

### Output contract

- UI 문자열은 영국식 영어를 사용합니다.  
- 복사‑붙여넣기 블록보다 재사용 가능한 컴포넌트를 선호합니다.  
- `className`은 가독성을 유지하세요 (복잡해지면 추출합니다).

#### Full‑screen toggles (example)

```html
Enter fullscreen mode
Exit fullscreen mode

그게 전부입니다.

Skill의 역할은 에이전트를 적절한 파일로 적시에 라우팅하는 것이지, 페이지 내 백과사전을 만드는 것이 아닙니다.

6️⃣ 개선 측정 (자신에게 거짓말하지 않기)

반복 가능한 결과를 원한다면 실제로 중요한 지표를 추적하세요:

• 활성화 시 초기 로드된 라인 수.
• 활성화까지 걸린 시간 (대략적으로 “얼마나 빠른지” 느낌).
• 관련성 비율 (로드된 콘텐츠 중 실제로 사용되는 비율).
• 컨텍스트 오버플로우 빈도 (긴 작업이 얼마나 자주 충돌하는지).

전체 관측 스택이 필요하지 않습니다; 간단한 저장소‑감사 스크립트만 있으면 충분합니다.

작은 파이썬 감사: 스킬당 라인 수 세기

from pathlib import Path

skills_dir = Path(".claude/skills")

def count_lines(p: Path) -> int:
    """Return the number of lines in a file, ignoring decode errors."""
    return sum(1 for _ in p.open("r", encoding="utf-8", errors="ignore"))

for skill in sorted(skills_dir.iterdir()):
    skill_md = skill / "SKILL.md"
    if skill_md.exists():
        lines = count_lines(skill_md)
        status = "OK" if lines < 200 else "TOO LONG"
        print(f"{skill.name}: {lines} lines – {status}")

이 스크립트를 매주 실행하면 “문서 부풀림”이 위기가 되기 전에 잡아낼 수 있습니다.

7️⃣ 일반적인 실패 모드 (및 회피 방법)

실패 모드: Claude가 “Skill” 대신 “문서”를 작성함

LLM은 마크다운을 튜토리얼 형태로 확장하는 것을 좋아합니다.

해결 방법:

• 모델에 명시적으로 알려 주세요: 이것은 문서가 아닙니다.
• “초보자”용 채우기 문구를 제거합니다.
• 예시는 짧게 유지하고, 상세 내용은 레퍼런스 파일에 넣습니다.

실패 모드: Skill 범위가 너무 넓어 진입점이 비대해짐

해결 방법:

• 워크플로 단계별로 Skill을 분할합니다.
• 혹은 의사결정 트리를 레퍼런스 파일로 옮깁니다.

실패 모드: 레퍼런스가 너무 많아 탐색이 어려움

해결 방법:

• SKILL.md에 짧은 “맵” 섹션을 추가합니다.
• 레퍼런스 파일은 단일 주제로 유지하고, 도구가 아니라 의도에 따라 이름을 지정합니다.

8️⃣ 복사 가능한 리팩터 체크리스트

1. 감사 – Skills와 라인 수를 나열하고, SKILL.md > 200줄인 경우 표시합니다.
2. 워크플로우별 그룹화 – 도구별 Skills를 역량 Skills로 병합합니다.
3. 레퍼런스 생성 – 자세한 정보를 SKILL.md 밖으로 이동합니다.
4. 입력 제약 적용 – SKILL.md를 간결하고 탐색하기 쉽게 유지합니다.
5. 콜드 스타트 테스트 – 첫 활성화가 선택한 예산 이하인지 확인합니다.
6. 스크립트를 결정론적으로 유지 – 가능한 경우 “작업 수행”을 코드로 오프로드합니다.
7. 월간 재검토 – Skills는 시간이 지나면서 변동하므로 코드처럼 다룹니다.

최종 정리: 컨텍스트 엔지니어링은 “올바른 정보, 올바른 시점”

큰 교훈은 “200줄”이나 “세 레이어”가 아니라, 이것입니다:

컨텍스트는 예산이다.

최고의 Skill 설계는 엔지니어처럼 예산을 사용하고, 사서처럼 사용하지 않습니다.
모든 것을 로드하지 마세요. 중요한 것을, 중요한 시점에 로드하고, 나머지는 한 파일 정도 떨어진 곳에 두세요.