Deep Agent Builder 커스텀 스킬 만들기
커스텀 스킬은 에이전트가 반복해서 참고할 업무 절차와 전문 지식을 Markdown으로 저장하는 자원입니다. 이 페이지에서는 스킬을 만들고, 내용을 확인하고, 에이전트에 연결한 뒤 실제 입력으로 적용 여부를 확인하는 순서를 설명합니다.
만들기 전에 정할 것
먼저 스킬 하나가 담당할 업무 범위를 정합니다. 외부 시스템을 호출하는 기능은 도구가 맡고, 호출 결과를 해석하거나 답변을 구성하는 절차는 스킬에 적습니다. 서로 다른 업무를 한 스킬에 섞으면 필요한 규칙을 찾기 어려워지고, 도구 설정과 지침을 함께 고칠 때 변경 범위를 판단하기도 어려워집니다.
다음 항목도 미리 정합니다.
- 스킬을 사용할 업무와 독자
- 입력에서 반드시 확인할 조건
- 작업 순서와 예외 처리 기준
- 답변에 포함할 결과 형식
- 스킬이 있어도 도구나 권한이 별도로 필요한 작업
시크릿, 토큰, 고객 데이터와 실제 운영 접속 정보는 스킬 본문에 넣지 않습니다. 필요한 환경 키나 권한이 있다면 이름과 확인 조건만 설명하고 값은 별도 보안 경로로 관리합니다.
스킬을 만드는 세 가지 경로
Deep Agent Builder는 스킬을 파일로 업로드하거나 편집기에서 작성하거나 대화로 초안을 만드는 흐름을 제공합니다. 세 경로 중 무엇을 선택해도 저장된 스킬의 이름, 설명, 내용과 사용 범위를 확인해야 합니다.
파일로 업로드하기
이미 검토한 Markdown 파일이 있으면 파일 업로드 경로를 사용합니다. 업로드 전에 파일이 하나의 업무 범위를 설명하는지, 내부 식별자와 비밀값이 없는지 확인합니다. 업로드가 끝나면 스킬 목록 API에서 이름, 유형, 버전과 사용 가능 여부를 다시 조회하고, 콘텐츠 조회 API로 파일 전체가 저장됐는지 확인합니다. 실제 화면의 메뉴와 버튼은 제품 버전에서 확인하기 전 확정하지 않습니다.
편집기에서 작성하기
새 스킬을 직접 작성할 때는 업무 목적을 첫 부분에 적고, 이어서 조건과 절차를 순서대로 씁니다. 예시 입력과 예외를 넣을 때는 스킬이 적용되는 범위를 벗어나지 않게 합니다. 저장 후에는 콘텐츠 조회 API로 현재 내용이 저장됐는지 확인하고, 목록 API에서 유형과 버전을 다시 조회합니다. 편집기 화면의 실제 라벨은 확인 필요입니다.
대화로 초안 만들기
대화 흐름은 초안을 만드는 데 유용하지만, 대화가 끝났다는 사실만으로 스킬이 저장됐다고 판단하지 않습니다. 생성된 초안을 검토한 뒤 저장 결과와 콘텐츠를 다시 조회합니다. 대화 초안 흐름의 실제 제품 진입 경로와 저장 동작은 UI 확인 필요이며, 초안이 실제 업무 규칙과 맞는지는 비식별 테스트 입력으로 따로 확인합니다.
내용 작성 기준
좋은 스킬은 에이전트가 판단해야 할 조건을 직접 적습니다. 다음 순서를 기본 구조로 사용할 수 있습니다.
- 이 스킬이 다루는 업무와 다루지 않는 업무
- 시작 전에 확인할 입력과 권한
- 정상 처리 순서
- 실패 또는 예외가 발생했을 때의 판단 기준
- 결과를 기록하거나 답변으로 정리하는 형식
- 다른 도구나 스킬이 필요한 경우의 연결 조건
도구가 반환한 값을 스킬이 항상 성공으로 해석하도록 쓰지 마세요. 연결 확인과 실제 실행 결과가 다를 수 있고, 권한 부족이나 입력 형식 오류가 있으면 외부 호출이 실패할 수 있습니다. 스킬은 결과를 확인하는 기준을 제시해야 하며, 근거 없는 성공 메시지를 만들도록 지시해서는 안 됩니다.
저장 후 확인하기
저장한 뒤에는 API 응답과 제품에서 제공하는 확인 화면을 다음 순서로 대조합니다.
- 스킬 목록에서 이름, 설명, 유형과 버전을 확인합니다.
- 상세 정보에서 필요한 환경 키와 메타데이터를 확인합니다.
- 콘텐츠 조회로 저장된 Markdown을 다시 엽니다.
- 사용처 조회로 연결된 에이전트를 확인합니다.
- 필요한 입력을 넣어 절차와 결과 형식이 적용되는지 시험합니다.
목록의 can_use는 스킬을 사용할 수 있는지 판단하는 값이고, 편집 권한을 뜻하지 않습니다. 개인 스킬은 사용자 범위에서 사용할 수 있지만, 다른 origin 자원은 ABAC 그룹의 사용 권한을 별도로 확인할 수 있습니다. 접근 대상이 없거나 연결이 유효하지 않으면 사용할 수 없는 상태가 될 수 있습니다.
에이전트에 연결하기
에이전트의 설정 변경 요청에서 user_skill_ids에 연결할 스킬을 지정한 뒤 저장합니다. 저장 성공만 확인하지 말고 에이전트 상세 정보의 skill_list와 권한 상태를 다시 조회합니다. 실제 편집 화면의 선택·저장 동작은 UI 확인 필요입니다. 스킬 연결은 외부 도구 연결과 별개입니다. 스킬이 답변 절차를 설명하더라도 필요한 도구가 연결되지 않았거나 도구 사용 권한이 없으면 외부 작업을 수행할 수 없습니다.
실행 시험에서는 다음 세 결과를 구분합니다.
- 스킬이 에이전트에 연결됐는가
- 에이전트가 필요한 도구와 권한을 갖췄는가
- 실제 입력에서 스킬의 절차와 결과 형식이 적용됐는가
세 번째 결과가 기대와 다르면 스킬 내용, 에이전트 지침, 도구 결과를 나눠 점검합니다. 이름이나 설명만 바꿔 문제를 해결했다고 결론 내리지 않습니다.
수정과 콘텐츠 교체
스킬 내용을 바꿀 때는 사용처를 먼저 확인하고, 연결된 에이전트의 업무에 영향을 주는지 판단합니다. 수정 후에는 저장된 콘텐츠와 버전이 바뀌었는지 확인합니다. 콘텐츠 교체마다 minor version이 증가하므로, 같은 비식별 입력으로 이전 결과와 비교하면서 절차의 순서, 조건, 권한과 예외 처리가 바뀌었는지 기록하면 회귀 원인을 찾기 쉽습니다.
콘텐츠가 비어 있거나 읽기 결과가 예상과 다르면 스킬이 저장되지 않았다고 단정하지 마세요. 콘텐츠 조회 결과, 파일 구조와 접근 권한을 순서대로 확인합니다. 콘텐츠는 단일 파일의 경우 {uid}.md, 디렉터리형의 경우 대소문자를 구분하지 않는 SKILL.md, legacy 형식의 경우 {uid}.yaml, fork의 경우 origin SKILL.md 순서로 읽을 수 있습니다. 콘텐츠가 없거나 파일 읽기에 실패하면 빈 문자열이 반환될 수 있습니다.
콘텐츠를 교체할 때 빈 문자열이나 공백만 보내면 CONTENT_REQUIRED로 거부될 수 있습니다. 여러 파일 스킬은 MULTI_FILE_NOT_EDITABLE, 디렉터리형 스킬에 SKILL.md가 없으면 SKILL_ENTRYPOINT_REQUIRED가 반환될 수 있으므로, 수정 전에 파일 구조와 진입 파일을 확인합니다.
삭제 전에 확인할 것
삭제하기 전 사용처 조회로 해당 스킬을 참조하는 에이전트를 확인합니다. 단건 삭제는 사용 중인 스킬도 에이전트의 참조 배열을 정리한 뒤 삭제할 수 있으므로, 연결된 업무에서 지침이 사라지는 영향을 먼저 판단하고 대체 스킬이나 연결 변경을 준비합니다. DB 삭제와 파일·디렉터리 후처리는 같은 원자적 경계가 아닐 수 있습니다.
일괄 삭제에서는 빈 목록, 미소유 ID, 사용 중인 스킬을 각각 구분해 확인합니다. force=false에서 사용 중인 스킬 때문에 충돌이 반환되면 참조 에이전트를 확인한 뒤 삭제 범위를 다시 정합니다. force=true를 선택하면 참조 배열 정리와 row 삭제는 하나의 Service DB transaction으로 처리되지만 파일 후처리와 audit은 commit 뒤 진행될 수 있습니다.
대표적인 실패와 다음 판단
- 저장 후 목록에 나타나지 않으면 저장 결과, 사용자 범위와 조회 권한을 확인합니다.
- 콘텐츠가 비어 있으면 파일 이름 규칙, 파일 읽기 결과와 접근 권한을 확인합니다.
- 에이전트가 스킬을 사용하지 않으면 skill_list 연결, can_use와 실행에 필요한 도구를 각각 확인합니다.
- 사용처가 있는 스킬의 일괄 삭제가 거부되면 참조 에이전트를 확인하고 단건 또는 일괄 삭제 조건을 다시 판단합니다. 단건 삭제는 참조 정리 뒤 진행될 수 있습니다.
- 외부 호출이 실패하면 스킬 문장보다 도구의 권한, 시크릿, 입력 스키마와 연결 상태를 먼저 확인합니다.
공개 매뉴얼에서 다루지 않는 정보
이 페이지는 스킬의 작성과 확인 절차만 설명합니다. 내부 코드 경로, 고객 정보, 호스트, 실제 시크릿과 운영 접속 정보는 공개하지 않습니다. 화면을 촬영할 때는 비식별 데모 환경과 실제 제품 라벨을 먼저 확인하고, 확인하지 못한 메뉴나 성공 상태를 이미지나 문장으로 만들지 않습니다.