스킬생성 후 업데이트.

작성한 질문수 8

1

안녕하세요! 🙂

먼저 링크만 넣어두면 안 되냐는 부분인데요, 안 되는 건 아니지만 스킬이 동작하는 방식을 보시면 왜 파일로 담아두는지 자연스럽게 이해되실 거예요. 스킬은 클로드 코드가 작업 중에 곧바로 읽어서 참고하는 자료입니다. 링크만 적혀 있으면 그 페이지를 가져오는 단계가 한 번 더 생기고, 네트워크 상황을 타고, 무엇보다 공식 문서 한 페이지를 통째로 읽어오면 정작 작업에 써야 할 컨텍스트를 문서가 다 잡아먹아요. 링크가 있다고 해서 반드시 열어본다는 보장도 없고요.

레퍼런스 파일은 그 문서에서 실제로 필요한 내용만 추려둔 것이라 즉시, 정확하게, 적은 비용으로 참고할 수 있습니다. 대신 각 파일 상단에 원본 링크를 같이 적어두시는 건 추천드려요. 나중에 갱신할 때 어디를 보고 고쳐야 하는지 바로 찾을 수 있거든요. 링크는 대체재가 아니라 출처 표시로 쓰시면 됩니다.

그리고 여기서 가장 중요한 부분을 말씀드릴게요. 공식 문서가 업데이트된다고 해서 레퍼런스를 매번 따라 갱신하실 필요는 없습니다. 우리가 진행하는 프로젝트의 Next.js 버전은 고정되어 있고, 매번 최신 버전으로 올리지 않으니까요. 레퍼런스는 "가장 최신 문서"가 아니라 "내 프로젝트가 실제로 쓰는 버전의 문서"여야 정확한 자료가 됩니다. 오히려 최신 문서를 그대로 반영해버리면 프로젝트에 없는 API나 바뀐 문법이 섞여 들어와서 엉뚱한 코드가 나올 수 있어요. 그래서 갱신 시점은 문서가 바뀔 때가 아니라 프로젝트의 Next.js 버전을 올릴 때입니다.

이 관점으로 보시면 링크로만 걸어두는 게 왜 애매한지도 함께 이해되실 거예요. 링크는 항상 최신 문서를 가리키기 때문에, 프로젝트 버전과 어긋나는 정보를 계속 물어오게 되거든요.

분류 기준은 솔직하게 말씀드리면 저도 클로드 코드에게 나눠달라고 부탁했어요 ㅎㅎ 공식 문서를 주고 주제 단위로 쪼개달라고 했습니다. 다만 판단 기준은 하나였어요. "작업할 때 이 파일 하나만 열면 되는가."

라우팅 작업을 할 때 라우팅 문서만 열리면 되고, 캐싱을 건드릴 때 캐싱 문서만 열리면 되는 구조가 이상적입니다. SKILL.md는 목차 역할을 하고 실제 내용은 필요한 파일만 골라서 읽히기 때문에, 이렇게 나눌수록 컨텍스트가 절약돼요. 반대로 파일 하나에 여러 주제가 섞여 있으면 필요 없는 내용까지 매번 딸려 들어옵니다. 그래서 17개라는 숫자 자체에는 의미가 없고, 공식 문서의 목차 구조를 따라가시면 대체로 무난해요.

세 번째 방법도 정확합니다. 버전을 올리시는 시점에 해당 문서 URL을 주시고 어느 파일을 갱신할지 알려주시면 클로드 코드가 대조해서 수정해 줍니다.

마지막으로 하나 더 말씀드리면, 저는 레퍼런스를 미리 완벽하게 맞춰두려고 하지 않아요. 개발하다가 클로드 코드가 레퍼런스를 참고하지 않고 작업하면 그때 "이 레퍼런스를 참고 안 했다"고 짚어주고 그 자리에서 문서를 수정합니다. 참고하지 않았다는 건 대부분 문서 쪽 문제거든요. 설명이 애매하거나, 분류가 실제 작업 단위와 안 맞거나, SKILL.md에 그 파일을 언제 열어야 하는지가 안 적혀 있는 경우입니다. 그래서 실제로 써보면서 다듬는 쪽이 앉아서 완성도를 올리는 것보다 훨씬 빠르고 정확해요.

감사합니다 🙏

0

안녕하세요, 인프런 AI 인턴입니다. alsekfrwh님.

질문하신 내용과 가장 유사한 기존 답변을 아래 게시글에서 확인하실 수 있습니다.

• 스킬 작성 시 참고 섹션에 md가 아닌 웹 사이트도 가리킬 수 있나요?
  
• 가이드문서에 관하여
  

핵심 내용은 다음과 같습니다.

1. Reference에 공식 문서 URL만 연결하는 방식보다는, 프로젝트에서 사용하는 버전에 맞는 내용을 md 파일로 고정해두는 방식이 권장됩니다. 공식 문서는 계속 최신 버전으로 변경될 수 있기 때문에, 프로젝트가 Next.js 16을 사용한다면 Next.js 17 기준의 최신 문서가 아니라 현재 프로젝트 버전에 맞는 문서를 참고하는 것이 안전합니다.

2. Reference 파일을 여러 개로 나누는 이유는 CLAUDE.md가 지나치게 길어지는 것을 방지하고, 필요한 상황에서 관련 문서만 선택적으로 참고하게 하기 위해서입니다. 예를 들어 Next.js 레이아웃, 데이터 패칭, 라우팅, 인증 등 주제별로 나누고, CLAUDE.md에는 각 문서의 경로만 연결하는 방식입니다. 처음부터 완벽하게 분류하기보다는 자주 참조하는 영역과 독립적인 주제를 기준으로 나눈 뒤, 실제 사용하면서 계속 정리하면 됩니다.

3. 업데이트 시에는 Claude Code에 공식 문서 URL을 전달하고 해당 내용을 특정 Reference 파일에 반영해 달라고 요청할 수 있습니다. 다만 공식 문서 전체를 무조건 가져오기보다는 현재 프로젝트에서 필요한 부분만 선별하는 것이 좋습니다. 내용이 길거나 여러 페이지로 나뉘어 있다면 관련 문서를 파일로 저장한 뒤 @파일경로로 전달하고, 프로젝트 버전에 맞게 요약·정리하도록 요청한 다음 결과를 직접 검토하는 흐름을 추천합니다.

즉, 다음과 같은 방식으로 관리할 수 있습니다.

1. 현재 프로젝트의 기술 스택과 버전 확인
2. 해당 버전에 맞는 공식 문서 중 필요한 주제만 선정
3. Claude Code로 Reference md 파일 생성 또는 수정
4. CLAUDE.md에는 Reference 파일 경로만 연결
5. 실제 개발 중 문제가 발생하거나 공식 문서가 변경되면 해당 파일을 다시 검토하고 업데이트

관련 답변에서는 공식 문서 내용을 프로젝트에 맞게 정리해 docs/guides 아래에 저장하고, 사용해 보면서 필요한 규칙을 반복적으로 보완하는 방법도 안내하고 있습니다.

저는 질문자님의 이해를 돕고자 지식공유자님의 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다.
현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏
추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.