입력을 잘 설계하는 법: 초보자용 템플릿 3종 세트 — Claude Skills 실전 활용 매뉴얼 3/7

시리즈: Claude Skills 실전 활용 매뉴얼 (총 7편) | 3편

입력을 잘 설계하는 법: 초보자용 템플릿 3종 세트

Claude Skills 결과물이 매번 달라서 답답하다면, 문제는 스킬이 아니라 입력 설계에 있어. 이 글에서 텍스트·JSON·CSV 템플릿 3종, 필수/선택 필드 구분법, 데이터 타입 명시 패턴, SKILL.md 작성 시 절대 하면 안 되는 실수까지 정리해 줄게.

Summary

• 입력을 스키마(정해진 양식)로 만들면 Claude의 추가 질문과 누락이 확 줄어들어
• 범용 텍스트·JSON·CSV 세 가지 템플릿을 상황에 맞게 골라 쓰면 돼
• 필수/선택 필드 구분, 데이터 타입 명시, 허용값 나열이 입력 설계의 핵심 패턴이야
• SKILL.md의 frontmatter에는 XML 태그(< >)를 절대 넣으면 안 돼

이 글의 대상

• Skills를 써 봤는데 결과물 품질이 들쭉날쭉한 사람
• 입력을 어떻게 구조화해야 할지 감이 안 잡히는 사람
• 나만의 SKILL.md를 처음 만들어 보려는 사람

목차

1. 왜 입력 설계가 중요한지
2. 범용 텍스트 템플릿
3. JSON 입력 템플릿
4. CSV/표 입력 템플릿
5. 입력 설계 5대 패턴
6. SKILL.md 작성 필수 규칙
7. 템플릿 선택 가이드

---

1. 왜 입력 설계가 중요한지

같은 스킬을 써도 입력을 어떻게 주느냐에 따라 결과가 완전히 달라져. 비교해 볼게:

입력 방식	예시	Claude 반응
대충 한 줄	“블로그 써 줘”	“어떤 주제요? 몇 자 정도요?” 되물음
키워드만 나열	“AI, 한국어, 2000자”	맥락 부족으로 엉뚱한 방향
구조화된 입력	목표·제약·출력형식 분리	추가 질문 없이 바로 결과물 생성

입력을 스키마로 만들면 두 가지가 동시에 해결돼:
- Claude의 되물음이 줄어들어 — 필요한 정보가 다 있으니까
- 출력 누락이 줄어들어 — 기대하는 형식을 명시했으니까

결국 한 번에 원하는 결과를 받을 확률이 올라가는 거지.

---

2. 범용 텍스트 템플릿

가장 많이 쓰게 될 기본 템플릿이야. 명시 호출 방식에서 바로 복사해서 쓰면 돼:

Use my [스킬명] skill to [작업].

목표: [한 문장으로 최종 결과물 설명]

입력 데이터: [붙여넣기 / 파일 첨부 / "아래 텍스트 참고" 등]

제약:
- 언어: 한국어
- 톤: 간결하고 업무용
- 길이: 요약 5문장 이내
- 금지: 이모지, 격식체

출력 형식:
1) Markdown 요약
2) 표 (컬럼: A, B, C)
3) 한 줄 결론

각 필드 설명:

필드	역할	생략 가능?
스킬명 + 작업	어떤 스킬로 뭘 할지	불가 (필수)
목표	최종 결과물의 모습	불가 (필수)
입력 데이터	Claude에게 줄 원재료	작업에 따라
제약	언어, 톤, 길이, 금지 사항	가능 (기본값 적용)
출력 형식	결과물의 구조	가능하지만 권장

특히 출력 형식을 적어주면 “표로 줘”, “번호 매겨 줘” 같은 추가 요청을 안 해도 되니까 시간이 절약돼.

---

3. JSON 입력 템플릿

재현성이 최우선일 때 쓰는 템플릿이야. 팀에서 같은 스킬을 돌릴 때나, 매번 동일한 구조로 결과를 받고 싶을 때 좋아:

{
  "task": "weekly-report",
  "language": "ko",
  "constraints": {
    "tone": "professional-casual",
    "max_length": 2000,
    "forbidden": ["이모지", "격식체(~합니다)"],
    "date_format": "YYYY-MM-DD"
  },
  "output": {
    "format": "markdown",
    "sections": ["요약", "주요 성과", "다음 주 계획"],
    "include_table": true
  },
  "data": {
    "period": "2026-03-02 ~ 2026-03-08",
    "achievements": [
      "신규 고객 15건 확보",
      "월간 매출 목표 달성률 120%",
      "팀 온보딩 프로세스 개선"
    ],
    "issues": [
      "배포 파이프라인 지연 2회"
    ]
  }
}

JSON 템플릿의 장점:

장점	설명
재현성	같은 JSON → 같은 구조의 결과물
버전 관리	Git으로 입력 이력 추적 가능
자동화	스크립트에서 JSON 생성 → 스킬 실행 파이프라인 구축 가능
검증	JSON Schema로 입력값 사전 검증 가능

주의할 점: JSON 안에 한국어를 넣을 때 인코딩 문제는 거의 없지만, 큰따옴표(") 안에 큰따옴표를 쓸 때는 이스케이프(\")를 잊지 마.

---

4. CSV/표 입력 템플릿

대량 데이터를 한꺼번에 처리할 때 쓰는 템플릿이야. 고객 목록 분류, 상품 설명 일괄 생성 같은 배치 작업에 적합해:

Use my [스킬명] skill to [작업].

입력 데이터 (CSV):
| 이름 | 직급 | 부서 | 이번 달 성과 | 요청 사항 |
|------|------|------|------------|----------|
| 김민수 | 매니저 | 마케팅 | 캠페인 ROI 150% | 성과 요약 |
| 이지연 | 리드 | 개발 | 배포 자동화 구축 | 기술 보고서 |
| 박서현 | 주니어 | 디자인 | UI 리뉴얼 완료 | 피드백 정리 |

처리 규칙:
- 각 행마다 [출력 단위] 1개 생성
- 출력 형식: [Markdown / 이메일 / 슬랙 메시지]
- 톤: [공식 / 캐주얼]

CSV 템플릿의 핵심은 헤더 고정이야:

좋은 헤더: | 이름 | 직급 | 부서 | 성과 | 요청 |
나쁜 헤더: | col1 | col2 | col3 | col4 | col5 |

헤더가 명확하면 Claude가 각 열의 의미를 정확히 파악해서 처리 품질이 올라가. col1 같은 추상적인 이름은 Claude를 혼란스럽게 만들어.

대량 처리 시 팁:
- 한 번에 50행 이상 넣으면 처리 품질이 떨어질 수 있어 → 20~30행 단위로 나눠서 실행
- 결과물 형식이 행마다 달라질 수 있으니 “처리 규칙”에 출력 형식을 꼭 명시

---

5. 입력 설계 5대 패턴

어떤 템플릿을 쓰든 이 다섯 가지 패턴을 적용하면 입력 품질이 확 올라가:

패턴 1: 필수/선택 필드 구분

# 필수
- task: "blog-writing"      # 반드시 입력
- topic: "AI 트렌드"        # 반드시 입력

# 선택 (기본값 있음)
- language: "ko"            # 기본값: ko
- tone: "casual"            # 기본값: casual
- length: 2000              # 기본값: 2000자

필수와 선택을 나누면 급할 때는 필수만 넣고, 세밀하게 조정하고 싶을 때만 선택 필드를 채우면 돼.

패턴 2: 데이터 타입 명시

- date: "2026-03-11"        # string (YYYY-MM-DD)
- count: 5                  # number (정수)
- include_chart: true       # boolean (true/false)
- tags: ["AI", "블로그"]     # array (문자열 배열)

패턴 3: 날짜 규격 고정

# 좋은 예 - 규격 통일
date_format: "YYYY-MM-DD"
start_date: "2026-03-01"
end_date: "2026-03-11"

# 나쁜 예 - 규격 혼재
start: "3월 1일"
end: "2026.03.11"

날짜 형식이 섞이면 Claude가 파싱하다가 엉뚱하게 해석할 수 있어.

패턴 4: 허용값 명시

tone:
  allowed: ["formal", "casual", "professional-casual"]
  default: "casual"

output_format:
  allowed: ["markdown", "html", "plain-text"]
  default: "markdown"

허용값을 미리 나열하면 Claude가 이상한 톤이나 형식을 만들어내는 걸 막을 수 있어.

패턴 5: 예시 값 제공

# 입력 예시
topic: "2026년 AI 에이전트 트렌드"  # 예: "React vs Vue 비교"
length: 2000                       # 예: 1500, 2000, 3000

예시가 있으면 Claude가 “아, 이 정도 구체성을 원하는구나”를 바로 파악해.

---

6. SKILL.md 작성 필수 규칙

직접 스킬을 만들 때 반드시 지켜야 할 규칙들이야:

파일명과 폴더명

규칙	올바른 예	잘못된 예
파일명은 반드시 SKILL.md	SKILL.md	skill.md, Skill.md
폴더/스킬명은 kebab-case	blog-writer	BlogWriter, blog_writer

YAML Frontmatter 필수 항목

---
name: blog-writer
description: "한국어 블로그 글을 2000~4000자로 SEO 최적화하여 작성. H2/H3 구조, FAQ 포함"
---

항목	필수 여부	설명
name	필수	스킬 식별자 (kebab-case)
description	필수	트리거 판단 기준 (1편 참고)
version	선택	버전 관리용
author	선택	제작자 정보

절대 하면 안 되는 실수

frontmatter에 XML 태그 넣기:

# 절대 금지!
---
name: my-skill
description: "<task>블로그 작성</task>"
---

왜 위험하냐면, < > 같은 XML 태그가 frontmatter에 들어가면 시스템 프롬프트 주입(injection) 위험이 있어. Claude가 태그를 명령어로 오해할 수 있거든. description은 순수 텍스트로만 작성해야 해.

본문에서 지시사항과 데이터를 섞기:

# 나쁜 예
키워드를 분석해서 글을 써. 키워드: AI, 블로그. 분량은 2000자.

# 좋은 예
## 절차
1. 키워드 분석
2. 아웃라인 생성
3. 본문 작성

## 입력
- keywords: 키워드 목록 (필수)
- length: 분량 (기본값: 2000자)

절차·입력·출력을 H2로 명확히 나누면 Claude가 각 섹션의 역할을 제대로 이해해.

---

7. 템플릿 선택 가이드

상황별로 어떤 템플릿을 쓸지 한 눈에 정리해 볼게:

상황	추천 템플릿	이유
빠르게 한 건 처리	범용 텍스트	가장 간단하고 직관적
팀에서 동일 결과 필요	JSON	재현성과 버전 관리에 최적
대량 데이터 배치 처리	CSV/표	행 단위 반복 처리에 적합
스킬 내부에 기본값 세팅	JSON (SKILL.md 안)	기본값을 코드처럼 관리 가능
비개발자와 협업	범용 텍스트	JSON 몰라도 바로 사용 가능

처음 시작한다면 범용 텍스트 템플릿부터 써 보고, 같은 작업을 반복하게 되면 JSON으로 전환하는 게 자연스러운 흐름이야.

---

핵심 정리

1. 입력을 스키마로 만들면 Claude의 추가 질문과 출력 누락이 줄어들어
2. 범용 텍스트(빠른 처리)·JSON(재현성)·CSV(대량 배치) 3종을 상황별로 선택
3. 필수/선택 구분, 타입 명시, 날짜 규격, 허용값, 예시 — 5대 패턴이 입력 품질을 좌우해
4. SKILL.md의 frontmatter에 XML 태그(< >)를 넣으면 시스템 주입 위험이 있으니 절대 금지

FAQ

Q: 범용 텍스트 템플릿에서 “제약” 항목을 안 쓰면 어떻게 돼?

A. SKILL.md에 기본값이 설정돼 있으면 그걸 따르고, 없으면 Claude가 알아서 판단해. 다만 톤이나 길이가 매번 달라질 수 있으니까, 일관성이 중요한 작업이라면 제약을 꼭 써 주는 게 좋아.

Q: JSON 템플릿이 더 좋은 결과를 내?

A. 꼭 그런 건 아니야. JSON의 강점은 “재현성”이지 “품질 향상”이 아니거든. 핵심은 필요한 정보를 빠짐없이 전달하는 거야. 범용 텍스트도 정보가 충분하면 JSON과 동일한 품질이 나와.

Q: CSV로 100행 넘는 데이터를 처리할 수 있어?

A. 가능하긴 한데, 행이 많아질수록 처리 품질이 떨어지고 토큰도 많이 소비돼. 20~30행 단위로 나눠서 여러 번 실행하는 게 더 나은 결과를 가져와.

Q: SKILL.md에서 frontmatter를 안 쓰면 스킬이 동작 안 해?

A. name과 description이 없으면 Claude가 이 스킬을 인식하지 못할 수 있어. 특히 description이 없으면 자동 트리거가 불가능해지거든. frontmatter는 반드시 작성해야 해.

Q: 허용값(allowed values)을 영어로 써야 해?

A. description은 영어를 추천하지만, 허용값은 실제 출력에 반영되는 거니까 원하는 언어로 써도 돼. 예를 들어 tone: ["친근한", "공식적인", "유머러스한"] 같이 한국어로 적어도 잘 동작해.

Q: 한 스킬에서 여러 출력 형식을 지원하게 만들 수 있어?

A. 물론이지. 입력에 output_format 필드를 추가하고, SKILL.md에 형식별 처리 절차를 나눠 적으면 돼. 예를 들어 output_format: "markdown" 이면 Markdown으로, "html"이면 HTML로 출력하게 분기할 수 있어.

Q: 날짜 규격이 왜 그렇게 중요해?

A. “3월 1일”, “2026.03.01”, “2026-03-01”, “March 1, 2026”이 섞여 있으면 Claude가 정렬이나 계산을 할 때 오류가 생겨. 특히 기간 비교(시작일~종료일)가 있는 작업에서 규격 통일이 안 되면 결과가 엉뚱해질 수 있어.

Q: 입력에 민감한 정보(개인정보, API 키)를 넣어도 돼?

A. 가급적 넣지 않는 게 좋아. 꼭 필요하다면 작업 후 대화를 삭제하고, 예시로 저장할 때는 반드시 민감 정보를 제거한 버전으로 저장해. 특히 API 키는 절대 입력에 직접 포함하지 마.

참고 자료 (References)

데이터 출처

출처	설명	링크
Best Practices	Skills 설계 모범 사례 및 입력 패턴	Best Practices
Anthropic Guide (Gist)	커뮤니티 정리 Skills 가이드	Gist Guide
Claude Help Center	Skills 사용 가이드	Use Skills
Agent Skills Overview	기술 문서: 로딩 모델, 구조	Overview
Anthropic Complete Guide	Skills 빌딩 종합 가이드 PDF	Complete Guide

핵심 인용

“Use structured input schemas to reduce ambiguity and improve output consistency.”
— Anthropic Best Practices for Agent Skills

다음 편 예고

[4편] 출력을 고정하는 법: JSON+Markdown 2트랙 표준

• JSON+Markdown 2트랙 전략으로 매번 같은 포맷 받는 법
• 표준 JSON 골격 설계와 필드 구성
• 4가지 출력 패턴별 사용법
• 운영 필드를 활용한 출력 품질 관리