gws-drive

gws-drive 스킬 개요

gws-drive가 하는 일

gws-drive는 Google Workspace CLI용 Google Drive 스킬입니다. 명령줄에서 파일, 폴더, 공유 드라이브, 그리고 관련 Drive API 워크플로를 관리할 수 있게 해주며, 리소스 이름이나 필수 필드, 권한 제약을 추측하지 않도록 스킬 전용 가이드를 제공합니다.

누가 사용해야 하나요?

Backend Development, 자동화, 운영 업무를 하면서 스크립트나 에이전트 워크플로에서 반복 가능한 Drive 작업이 필요하다면 gws-drive 스킬을 사용하세요. 특히 업로드, 메타데이터를 고려한 작업, API 기반 조회처럼 한 번성 프롬프트보다 CLI 기반 절차가 더 적합할 때 유용합니다.

설치 전에 중요한 점

gws-drive의 핵심 가치는 범위가 넓다는 데 있지 않고, 정확성과 재현성에 있습니다. 에이전트가 올바른 Drive 리소스와 요청 형태를 찾도록 유도해 주기 때문입니다. 도입을 막는 가장 큰 요인은 인증과 공유 설정인데, 이 스킬은 더 넓은 gws 환경과 플래그 및 보안 규칙을 다루는 gws-shared 지침에 의존하기 때문입니다.

gws-drive 스킬 사용 방법

설치 및 사전 조건 확인

Google Workspace CLI 환경에 gws-drive 스킬을 설치한 뒤, 먼저 공유 사전 조건인 ../gws-shared/SKILL.md를 확인하세요. 스킬 메타데이터는 gws 바이너리의 사용 가능 여부도 전제하므로, Drive 워크플로를 시도하기 전에 CLI가 정상 동작하는지 검증해야 합니다. 실무적인 설치 확인 방법은 설정 후 gws drive --help를 읽고 스킬의 리소스 목록과 대조해 보는 것입니다.

올바른 입력 형식부터 시작하기

gws-drive의 사용 패턴은 gws drive <resource> <method> [flags]이므로, 프롬프트에는 대상 리소스, 수행할 작업, 그리고 정확한 출력 제약을 함께 적어야 합니다. 좋은 입력 예시는 “내가 접근할 수 있는 shared drives를 나열하고, name과 id만 반환하며, trash는 제외해 줘.”입니다. 반대로 “Drive 확인해 줘.”처럼 주면 모호합니다. Backend Development에서 gws-drive 가이드를 쓸 때는 식별자, 상위 폴더, 그리고 권한 또는 스코프 가정까지 처음부터 포함하세요.

먼저 읽어야 할 파일

먼저 SKILL.md를 읽고, 그다음 ../gws-shared/SKILL.md를 확인하세요. 인증, 전역 플래그, 보안 동작은 그 파일이 담당합니다. 이 repo 조각에는 참고할 보조 스크립트나 지원 폴더가 없으므로, 스킬 파일 자체가 사실상 단일 기준 소스입니다. 특히 API 리소스 섹션과 보조 명령 +upload를 주의 깊게 보세요. 일반적인 Drive 문서에서 추론하게 두지 않고, 의도된 워크플로를 그대로 보여 주기 때문입니다.

더 나은 결과를 만드는 워크플로

세 단계로 진행하세요. 먼저 리소스를 정하고, 그다음 method를 좁히고, 마지막으로 API 응답에 영향을 주는 플래그만 추가합니다. 예를 들어 Drive 계정 정보를 가져오라는 요청이라면 about.get 호출에 fields가 필요하다는 점을 명시해야 하고, 업로드 작업은 자동 메타데이터가 필요할 때 보조 명령으로 라우팅해야 합니다. 이것이 gws-drive 사용의 핵심 원칙입니다. 가능한 한 넓은 응답이 아니라, 가장 작은 유효한 응답을 요구해야 합니다.

gws-drive 스킬 FAQ

gws-drive는 Drive 기본 기능만 다루나요?

아닙니다. gws-drive는 핵심 Drive 리소스뿐 아니라 자동화에서 중요한 특정 API 동작도 다룹니다. 예를 들면 about.get에서 fields가 필요하다는 점, 그리고 approver-only 제약이 있는 access proposal 처리 같은 내용입니다. 따라서 단순한 Drive 설명보다, 정확한 API 형식이 중요할 때 더 적합합니다.

언제 이 스킬을 사용하지 말아야 하나요?

수동으로 한 번만 확인하면 되는 Drive 팁만 필요하거나, gws CLI와 공유 인증 설정이 아직 준비되지 않았다면 gws-drive 스킬은 건너뛰세요. Drive 작업 자체가 아닌 경우에도 적합하지 않습니다. 이 스킬은 일반적인 Workspace 조언보다 요청 구성과 CLI 실행에 최적화되어 있기 때문입니다.

초보자에게도 친화적인가요?

구체적인 Drive 목표를 설명할 수 있다면 그렇습니다. 이 스킬은 resource-method 패턴과 핵심 주의사항을 보여 주어 추측을 줄여 주지만, 초보자도 대상 파일, 폴더, shared drive, 권한 시나리오 중 하나는 제공해야 합니다. 그렇지 않으면 에이전트가 모호한 명령을 만들거나 너무 넓은 API 호출을 선택할 수 있습니다.

일반 프롬프트와 가장 큰 차이는 무엇인가요?

일반 프롬프트는 Drive 개념을 설명할 수 있지만, gws-drive는 실제 CLI와 API 리소스에 맞춘 워크플로를 제공합니다. 첫 실행부터 실패하지 않아야 하는 결정적 명령, 올바른 필드 선택, 권한을 고려한 작업이 필요할 때 이 차이가 중요합니다.

gws-drive 스킬 개선 방법

에이전트에게 정확한 Drive 맥락을 주세요

가장 좋은 결과는 한 문장 안에 리소스, 작업, 범위를 함께 적을 때 나옵니다. 예: “gws-drive로 폴더 abc123 안의 파일을 나열하고, id, name, mimeType, modifiedTime을 반환하며, trashed 항목은 제외해 줘.” 이는 “문서를 찾아줘”라고 하는 것보다 훨씬 강력합니다. 검색 모호성을 줄이고 불필요한 API 출력을 피할 수 있기 때문입니다.

API 호출을 바꾸는 제약 조건을 명시하세요

shared drives가 필요한지, 특정 폴더가 필요한지, access proposal이 필요한지, account-level 정보가 필요한지 적어 주세요. gws-drive에서는 이런 세부 사항이 중요합니다. 리소스마다 권한과 응답 요구사항이 다르기 때문입니다. 이를 생략하면 첫 결과가 fields 누락, approver 접근 권한 부족, 또는 지나치게 넓은 쿼리 때문에 실패하는 경우가 많습니다.

명령에서 결과로 반복 개선하세요

첫 출력이 너무 넓다면, 선택적 출력을 줄이고 필요한 정확한 식별자를 추가해 요청을 더 좁히세요. 실패한다면 문제 원인이 인증인지, gws-shared의 사전 조건 누락인지, 아니면 resource-method 조합이 맞지 않는 것인지 확인하세요. gws-drive에서 가장 빠른 가이드는 작업 자체를 바꾸기보다 먼저 명령 형태를 바로잡는 것입니다.