anhhung04/tracecat-스킬-관리

Tracecat 스킬 관리하기

Tracecat MCP는 list_skills, get_skill, prepare_skill_download, prepare_skill_upload, complete_skill_upload, publish_skill의 여섯 가지 스킬 도구를 제공합니다.

쓰기 작업은 즉시 반영되지 않고 단계적으로 준비됩니다. 파일 바이트가 도구 인수로 전송되지 않습니다. prepare_skill_upload는 메타데이터(경로, SHA-256, 크기, 콘텐츠 유형)만 받고 파일당 단기 PUT URL을 반환합니다. 바이트는 일반 HTTP를 통해 해당 URL로 전송됩니다. 그런 다음 complete_skill_upload가 준비된 블롭을 첨부하고 초안을 교체합니다. 인라인 content_base64 인수를 찾지 말고, 파일 바이트를 컨텍스트로 읽어서 전송하지 마십시오.

번들로 제공되는 도우미는 수동으로 처리하기 오류가 쉬운 부분(안전한 디렉토리 탐색, 심볼릭 링크 거부, 루트 SKILL.md 강제 적용, SHA-256 다이제스트)을 제거합니다.

스킬 업로드하기

동일한 네 단계가 새 스킬 생성과 기존 스킬 교체에 모두 사용됩니다. 유일한 차이점은 prepare_skill_upload가 받는 ID 인수입니다.

1. list_workspaces로 대상 워크스페이스를 확인한 다음 list_skills를 호출합니다. 새 스킬의 경우 이름이 사용 가능한지 확인하십시오. skill_id를 생략하면 항상 새 행이 생성되므로, 두 번째 생성은 동일한 name을 가진 두 개의 다른 슬러그 스킬을 만듭니다. 기존 스킬의 경우 skill_id를 가져옵니다.

2. 메타데이터 배열을 빌드합니다:

   python3 <이-스킬-디렉토리>/scripts/upload_skill_files.py metadata <로컬-스킬-디렉토리>
   

   이 명령은 files 배열을 그대로 출력합니다. 파일당 path, sha256, size_bytes, content_type 항목이 포함됩니다. 파일 내용은 포함되지 않습니다.

3. prepare_skill_upload를 workspace_id와 해당 files 배열과 함께 호출합니다. 그리고 다음 중 하나를 추가로 전달합니다:

   • name(및 선택적 description)과 없음 skill_id를 전달하여 스킬을 생성하거나,
   • skill_id와 없음 name/description을 전달하여 기존 스킬의 초안을 교체합니다.

   생성을 위해 로컬 프론트매터가 선언한 것과 동일한 name을 전달하십시오. 서버는 name과 description을 저장된 루트 SKILL.md 프론트매터에 병합한 후 유효성을 검사하므로, 일치하지 않는 인수는 저장되는 내용을 자동으로 덮어씁니다.

   응답에는 skill_id, base_revision, created 및 파일별 upload_id, upload_url, method, headers, expires_at이 포함됩니다.

4. 각 파일의 원시 바이트를 반환된 메서드와 헤더를 사용하여 해당 upload_url에 PUT합니다. 파일을 디스크에서 직접 읽어서 전송합니다. URL은 수명이 짧습니다. expires_at을 확인하고 만료된 경우 재시도하지 말고 다시 준비하십시오.

5. complete_skill_upload를 workspace_id, skill_id, 3단계의 base_revision 및 모든 파일에 대한 {"path": ..., "upload_id": ...} 형식의 files 배열과 함께 호출합니다. 이렇게 하면 초안이 교체되며 게시되지 않습니다.

6. 스킬을 프리셋에 연결할 수 있어야 하는 경우 publish_skill을 skill_id와 함께 호출합니다. 게시되지 않은 초안은 바인딩할 수 없습니다.

base_revision은 동시성 가드입니다. draft_revision_conflict는 3단계 이후 다른 사람이 초안을 편집했음을 의미합니다. get_skill을 호출하여 현재 draft_revision과 전체 트리 교체 시 삭제될 항목을 확인한 다음 다시 준비하십시오.

라이브 스킬 업데이트하기

complete_skill_upload 후에 중단되는 수정 사항은 에이전트가 실행하는 어떤 것도 변경하지 않습니다. 다음 세 단계를 순서대로 수행하십시오:

1. skill_id로 prepare_skill_upload 호출 → 바이트 PUT → complete_skill_upload 호출. 이렇게 하면 초안이 교체됩니다. 게시되지는 않습니다.
2. 동일한 skill_id로 publish_skill을 호출합니다. 스킬은 버전 관리됩니다. 이 호출은 새로운 불변 버전을 생성하고 스킬의 current_version_id를 이동시킵니다.
3. 소비하는 프리셋의 skills 목록(이미 가지고 있던 것과 동일한 {"skill_id": ...} 항목)을 사용하여 update_agent_preset을 호출합니다. 각 바인딩은 쓰기 시점에 해당 스킬의 현재 게시된 버전으로 다시 고정되므로, 2단계 이전에 바인딩된 프리셋은 이 호출이 다시 작성할 때까지 이전 버전을 계속 실행합니다.

3단계를 건너뛰는 것이 전형적인 실패 사례입니다. 새 버전이 존재하지만 프리셋이 이를 인식하지 못합니다.

재조회하여 확인하십시오. path 없이 get_skill을 호출하면 초안 매니페스트(경로, 다이제스트, 크기, draft_revision, is_publishable, validation_errors)를 반환하며 파일 내용은 반환하지 않습니다. path와 함께 get_skill을 호출하면 파일 하나를 읽으며, 작은 UTF-8 텍스트인 경우 인라인으로 반환합니다. list_skills는 스킬의 current_version_id를 표시합니다. get_agent_preset은 skills[].skill_version_id와 skills[].skill_version`을 표시합니다. 둘 다 변경되었는지 확인하십시오.

이것은 일상적이고 되돌릴 수 있는 작업입니다. 게시된 모든 버전은 불변이며 여전히 바인딩 가능하므로, 잘못된 푸시는 수정된 트리를 게시하고 다시 바인딩하여 취소할 수 있습니다. 위험을 설명하지 말고 수행하십시오. 실제로 되돌릴 수 없는 작업을 위해 주의를 아껴두십시오.

스킬의 도구 선언하기

스킬은 자체 도구를 가지고 있습니다. 이를 루트 SKILL.md 프론트매터의 metadata.tools 아래에 레지스트리 액션 이름 또는 mcp.<슬러그> / mcp.<슬러그>.<도구> 항목으로 선언하십시오. 최대 64개까지 가능합니다:

---
name: slack-triage
description: Slack에서 게시물 및 스레드 업데이트를 게시합니다.
metadata:
  tools:
    - tools.slack.post_message
    - tools.slack.list_replies
---

스킬이 연결된 모든 프리셋은 자체 actions 허용 목록에 추가로 해당 도구를 받습니다. 모델이 스킬을 열지 여부와 관계없이 프리셋이 확인되는 즉시 부여됩니다. 스킬의 지침만 요청 시 로드됩니다.

도구가 자연스럽게 그룹화되고 여러 에이전트가 이를 재사용하는 경우 각 프리셋의 actions에 동일한 도구를 나열하는 것보다 이 방법을 선호하십시오. 한 번의 편집과 재게시로 모든 소비 프리셋이 업데이트됩니다. 도구가 특정 에이전트에 한정된 경우 프리셋의 actions에 유지하십시오.

한 가지 주의 사항: 프리셋의 namespaces 필터는 통합의 레지스트리 도구에 적용되며 그 외부의 도구는 자동으로 차단합니다. 스킬을 네임스페이스 제한 프리셋에 연결한 후 get_agent_preset에서 tool_policy.blocked_tools를 확인하십시오. 스킬이 선언한 MCP 도구(mcp.<슬러그> / mcp.<슬러그>.<도구>)는 namespaces에 의해 필터링되지 않으며 거기에 나타나지 않습니다.

metadata.tools를 변경하면 에이전트가 실행할 수 있는 것이 변경되므로 다른 수정 사항과 동일한 세 단계(초안 교체, publish_skill, update_agent_preset으로 바인딩 재고정)를 따릅니다. 결과 프리셋을 읽으면 부여된 도구가 tool_policy.actions에 하나의 평평한 목록으로 표시되며, 스킬별 출처는 없습니다. 통합이 확인할 수 있는 전부입니다.

크기

바이트는 더 이상 모델 컨텍스트를 통과하지 않지만, 각 파일에는 여전히 서버 측 크기 제한이 있으며 전체 트리는 텍스트 전용이고 작을수록 검토하기 쉽습니다.

• Markdown, YAML 및 스크립트를 선호하십시오. 큰 이진 자산은 다른 곳에 호스팅하고 참조하십시오.
• 장문의 세부 정보는 SKILL.md에 넣지 말고 에이전트가 필요 시 읽는 references/ 파일에 넣으십시오.
• 트리가 너무 커서 추론하기 어려운 경우 스킬 자체를 두 개의 스킬로 분할하십시오. 여러 complete_skill_upload 호출에 걸쳐 하나의 트리를 분할하지 마십시오. 각 호출은 전체 초안을 교체하므로 부분 호출은 생략된 모든 것을 삭제합니다.

엄격한 규칙

• skill_id를 생략하면 생성합니다. 전달하면 교체합니다. 이미 존재하는 이름에 대해 생성하지 마십시오. 슬러그 재시도로 인해 중복이 실패하지 않고 성공합니다.
• 모든 쓰기는 전체 초안을 교체합니다. 로컬 디렉토리에 없는 파일은 스킬에서 삭제됩니다. 항상 완전한 트리를 전송하십시오.
• complete_skill_upload를 호출하기 전에 준비된 모든 파일을 업로드하고, 해당 upload_id와 함께 모든 경로를 다시 전달하십시오.
• 파일 바이트나 base64를 도구 인수에 인라인으로 포함하지 말고, 업로드 또는 다운로드 URL의 바이트를 컨텍스트로 읽지 마십시오. 디스크에서 디스크로 스트리밍하십시오.
• 게시는 기존 프리셋 바인딩을 이동시키지 않습니다. 새 버전을 적용하려면 프리셋의 skills 목록을 다시 작성하십시오.
• 심볼릭 링크된 파일과 디렉토리를 거부하고, 선택한 스킬 루트 외부의 콘텐츠를 절대 전송하지 마십시오. 도우미가 이를 강제합니다. 이를 우회하지 마십시오.
• 루트 파일은 정확히 SKILL.md여야 하며, 최상위 수준에 있어야 하고, 유효한 UTF-8이어야 합니다. 서버는 이를 포함하지 않은 파일 세트를 거부합니다.
• 클라이언트가 로컬 스크립트를 실행할 수 없는 경우, 사용자에게 도우미 명령을 실행하라고 알리십시오. 모델이 생성한 다이제스트를 대체하지 마십시오.

참조

• references/upload-contract.md에서 리터럴 요청 및 응답 형태와 이 경로가 보호하는 것과 보호하지 않는 것에 대해 읽으십시오.
• 업로드, 게시 또는 프리셋 재바인딩이 적용되지 않는 경우 references/troubleshooting.md를 읽으십시오.