내 에이전트 만들기

같은 종류의 일에 매번 같은 설명을 붙이고 있다면, 그 설명을 파일로 한 번 적어 두는 편이 낫습니다. 그러면 다음부터는 Claude가 상황을 보고 알아서 그 워커에게 넘깁니다.

어디에 만드나

정의는 마크다운 파일 하나이고, 두 자리 중 하나에 둡니다.

• .claude/agents/ — 지금 프로젝트에서만 씁니다
• ~/.claude/agents/ — 내 모든 프로젝트에서 씁니다

만드는 방법도 두 가지입니다. Claude에게 만들어 달라고 요청하거나, 파일을 직접 쓰거나.

다른 자료에서 /agents를 쳐서 생성 화면을 띄우고 이름·색깔을 고르는 장면을 봤을 수 있습니다. 그 대화형 화면은 지금 없어졌습니다. 파일 위치와 적는 항목은 그대로입니다.

무엇을 적나

파일 맨 위 --- 사이에 설정을 적고, 그 아래 본문에 역할 설명을 적습니다. 본문이 그 에이전트의 시스템 프롬프트가 됩니다.

꼭 있어야 하는 건 둘뿐입니다.

• name — 소문자와 붙임표로 짓는 고유한 이름입니다
• description — 언제 이 에이전트에게 넘겨야 하는지를 적습니다

나머지는 필요할 때만 적는데, 자주 쓰는 것만 보면 이렇습니다.

• tools — 쓸 수 있는 도구를 좁힙니다. 안 적으면 쓸 수 있는 도구를 다 물려받습니다
• model — 어떤 모델로 돌릴지 정합니다. 안 적으면 본 대화와 같은 모델을 씁니다
• skills — 시작할 때 스킬 내용을 미리 들고 시작하게 합니다

만들자마자는 안 보입니다

파일을 만든 직후 같은 대화에서 불러 보면 “그런 에이전트가 없다”고 나오지만, 정의를 잘못 쓴 게 아닙니다.

쓸 수 있는 에이전트 목록은 대화를 시작할 때 정해집니다. 그래서 도중에 만든 정의는 그 대화에서는 안 보이고, 다음 대화부터 보입니다.

만들었으면 대화를 새로 시작하고 나서 확인합니다. 이걸 모르면 정의를 계속 고치면서 왜 안 되는지 찾게 됩니다.

설명이 호출을 결정합니다

Claude는 각 에이전트의 설명을 읽고 지금 요청을 넘길지 판단합니다. 그래서 설명을 어떻게 쓰느냐가 그 에이전트가 실제로 일을 하느냐 마느냐를 가릅니다.

역할만 적으면 잘 안 불려 나옵니다.

• 잘 안 되는 쪽: description: 코드 리뷰 담당
• 잘 되는 쪽: description: 파일을 고친 뒤 읽기 쉬움과 성능 관점에서 개선점을 찾을 때 사용

뒤쪽에는 언제가 들어 있고, 앞쪽에는 없습니다.

skills는 권한이 아니라 미리 들고 시작하기입니다

skills에 스킬을 적으면 그 스킬의 내용 전체가 시작할 때 주입됩니다. 설명만이 아니라 본문까지 들어갑니다.

여기에 적지 않았다고 그 스킬을 못 쓰는 건 아닙니다. 서브에이전트는 적어 두지 않은 스킬도 필요하면 불러 쓸 수 있습니다.

모든 스킬을 다 나열하지 말고, 처음부터 들고 시작해야 하는 것만 적습니다.

내가 만든 에이전트의 설명(description)을 보고, 어떤 요청일 때 불려 나오고 어떤 요청일 때 안 불려 나올지 예시를 세 개씩 만들어 줘. 안 불려 나오는 쪽이 내 의도와 다르면 설명을 고쳐 줘.

이 에이전트가 쓸 수 있는 도구를 지금 필요한 것만 남기고 좁혀 줘. 좁히면 못 하게 되는 일이 무엇인지도 함께 알려 줘.