SKILL.md 본문과 참고 파일
자세한 지시문 작성하고 외부 컨텍스트 링크하기
⏱ 예상 ~5분
01 · 읽기
Frontmatter 아래의 마크다운 본문이 진짜 힘이 있는 곳이에요. 여기서 Claude가 따를 자세한 지시문, 예시, 제약, 규칙을 적어요.
한 가지 작업에 대한 매우 구체적인 지시 매뉴얼이라고 생각해 봐요.
마크다운 헤더로 섹션을 나누고, bullet 로 규칙을 적고, code fence 로 예시를 넣어요. 더 명확하고 구체적일수록 Claude가 더 일관되게 동작해요.
"좋은 코드를 써" 라고 적힌 본문은 쓸모없어요 - Claude 는 이미 그렇게 하려고 해요. "변수는 camelCase, React 컴포넌트는 PascalCase, CSS 클래스는 kebab-case 를 써" 라고 적힌 본문은 강제할 수 있어요.
핵심 정리
- 본문은 자유로운 마크다운이에요 - 헤더, bullet, code fence, 볼드
- 명확하게: "변수는 camelCase 를 써" 가 "좋은 이름을 써" 보다 나아요
- 좋은 출력이 어떻게 생겼는지 예시를 넣어요
- 헤더로 정리해서 Claude가 관련 규칙을 빨리 찾을 수 있게 해요
02 · 코드 예제
아래는 "API Developer" skill 이에요. 헤더, 규칙, 코드 예시로 본문 구조가 풍부해요.
api-developer/SKILL.md (본문 부분)
## API Conventions
- All endpoints return JSON
- Use kebab-case for URL paths: `/user-profiles` not `/userProfiles`
- Use camelCase for JSON fields: `{ "firstName": "Ada" }`
- Always include `Content-Type: application/json` header
## Error Response Format
Always return errors in this exact shape:
```json
{
"error": {
"code": "NOT_FOUND",
"message": "User with id 42 not found"
}
}
```
## Status Code Rules
- 200 for successful reads
- 201 for successful creates
- 400 for invalid input
- 404 for missing resources
- 500 should never be intentional — fix the bug
Claude 는 모든 헤더, bullet, 코드 예시를 읽어요. 나중에 "GET /users endpoint 를 만들어줘" 라고 말하면, Claude 는 이런 컨벤션을 자동으로 따라요 - kebab-case URL, camelCase JSON, 내가 지정한 정확한 에러 형식까지요.
03 · 읽기
가끔은 지시문이 외부 지식을 참고해요 - 데이터베이스 schema, 스타일 가이드, 타입 정의, 템플릿 같은 거요.
그 모든 걸 SKILL.md 에 붙여넣는 대신 (그러면 거대해지고 유지보수가 힘들어져요), 참고 파일을 링크할 수 있어요.
SKILL.md 와 같은 skill 폴더에 두고 본문에서 참조해요. Skill 이 활성화되면 Claude 는 링크된 파일을 추가 컨텍스트로 읽어요.
참고 파일의 장점: 단일 정보 출처가 돼요. Schema 가 바뀌면 Claude가 자동으로 최신 버전을 봐요 - skill 을 수동으로 업데이트할 필요가 없어요.
핵심 정리
- 참고 파일은 SKILL.md 와 같은 skill 폴더에 있어요
- 컨텍스트를 제공하면서 skill 파일이 거대해지지 않게 해줘요
- 흔한 참고 파일: schema 파일, 스타일 가이드, 템플릿, 타입 정의
- 참고 파일은 항상 최신이에요. 그 자체가 정보 출처니까요
04 · 코드 예제
아래는 Prisma schema 를 참고 파일로 링크하는 skill 이에요 - Claude에게 데이터베이스 구조의 완전한 지식을 주는 거죠.
폴더 구조
.claude/skills/db-developer/
├── SKILL.md
└── schema.prisma
db-developer/SKILL.md
---
name: Database Developer
description: Writes database queries and migrations following our schema
---
## Context
Our database schema is defined in `schema.prisma` (included in this skill folder).
Always reference it when writing queries or migrations.
## Rules
- Never use raw SQL — use Prisma Client
- Always include `createdAt` and `updatedAt` on new models
- Foreign keys must have `onDelete: Cascade` unless specified otherwise
- Index any column used in WHERE clauses
이 skill 이 활성화되면 Claude 는 schema.prisma 를 읽고 데이터베이스 구조를 이해해요. 나중에 schema 를 바꾸면 Claude가 자동으로 최신 버전을 봐요 - skill 을 업데이트할 필요가 없어요.
05 · 퀴즈
데이터베이스 schema 가 자주 바뀐다고 상상해 봐요. 왜 schema 를 SKILL.md 에 직접 붙여넣는 대신 참고 파일을 쓰나요?
- 참고 파일이 인라인 콘텐츠보다 빨리 불러와져요
- SKILL.md 는 100 줄의 엄격한 제한이 있어요
- Claude 는 SKILL.md 와 분리된 파일만 읽을 수 있어요
- 참고 파일은 출처가 바뀌면 자동으로 최신이 되고, SKILL.md 가 집중되도록 해줘요
06 · 짝짓기
Skill 의 네 부분을 배웠어요. 각 컴포넌트가 하는 일을 매칭해 봐요 - metadata, 지시문, 외부 컨텍스트가 각각 어디에 있는지 생각하면서요.
(이 섹션은 인터랙티브해요 — JavaScript를 켜 주세요.)
⚠ 전체 인터랙티브 경험에는 JavaScript가 필요해요. JavaScript를 켜고 새로 고침해 주세요.
※ 이 사이트는 독립 운영되는 교육 프로젝트로, Anthropic의 공식 제품이 아니에요. Claude™ 는 Anthropic, PBC 의 상표예요.