Claude Code가 CLI 명령어를 매번 처음부터 다시 학습하는 문제를 SKILL.md 파일의 3계층 구조로 해결하는 방법

Context

Claude Code는 도구를 호출할 때마다 --help를 반복 호출하며 같은 CLI 명령어를 처음부터 다시 학습한다. 각 세션마다 반복 학습이 발생하고, 에이전트가 결국 스스로 파악할 수 있는 명령어를 매번 재발견해야 하는 비효율이 존재한다.

Technical Solution

• CLI 도구 설치 시 skill 파일을 package data로 번들링하여 함께 배포한다.
• Frontmatter 계층에서 name, description(트리거 구문 포함), allowed-tools 목록을 정의한다.
• Body 계층에서 주요 명령어 예시와 핵심 워크플로우를 cheat sheet 형태로 제공한다.
• References 계층에서 상세 필드 설명 등 심화 내용을 별도 Markdown 파일로 분리한다.
• install --skills 명령어로 ~/.claude/skills/ 디렉토리에 skill 파일을 배치한다.

Impact

에이전트가 CLI를 명시적으로 언급하지 않아도 설치된 skill에서 도구를 자동 발견하고, 트리거 구문과 매칭되어 즉시 사용 가능하다.

Key Takeaway

CLI 자체를 재설계할 필요 없이 SKILL.md 파일만 추가하면 에이전트가 언제 도구에 도달해야 하는지 이해하고 어떤 명령어를 먼저 사용해야 하는지 파악할 수 있다.